page-ok

Evaluate web pages for console errors, page errors, and failed requests.

A lightweight CLI tool that opens a URL in a headless browser (Puppeteer), collects all runtime errors and warnings, and reports whether the page is OK.

Install

npm install -g page-ok

# or use directly with npx
npx page-ok https://example.com

Usage

page-ok <command> [options] [url]

Commands

| Command | Description | |---|---| | (none) | Check the target URL (default) | | setup | Install system dependencies (Chrome libraries) + download Chromium | | self-check | Quick environment health check |

First-time users: Run page-ok setup before your first check to ensure Chromium and system dependencies are installed.

Examples

# First-time setup (install Chrome deps + download Chromium)
page-ok setup

# Verify environment is ready
page-ok self-check

# Check localhost (default: http://localhost:5173)
page-ok

# Check any URL
page-ok https://example.com
npx page-ok http://localhost:3000 -f json

# Only care about errors, ignore warnings
page-ok https://example.com -F error

# Output as JSON for CI pipelines
page-ok https://example.com -f json > report.json

# Show browser window for debugging
page-ok --no-headless https://localhost:5173

Options

| Option | Alias | Default | Description | |---|---|---|---| | --url | -u | http://localhost:5173 | Target URL to check | | --wait | -w | 5000 | Wait time after page load (ms) | | --timeout | -t | 30000 | Navigation timeout (ms) | | --format | -f | summary | Output format: text, json, or summary | | --filter | -F | all | Filter output: all, error, or warn | | --headless | | true | Run in headless mode | | --no-headless | | | Show browser window (for debugging) | | --no-colors | | | Disable colored output | | --help | -h | | Show help | | --version | -V | | Show version |

Output Formats

Summary (default)

Human-readable verdict:

  [page-ok] https://example.com

  Status:       ✗ NOT OK
  Console Errs: 1
  Warnings:     6
  Page Errors:  0
  Failed Reqs:  0

  Console Error Details:
    1. Cannot read property 'x' of undefined

---JSON---
{"url":"https://example.com","ok":false,"errorCount":1,...}
---END_JSON---

The JSON block at the bottom is designed for easy parsing by AI tools and CI scripts.

JSON

Full structured output:

{
  "url": "https://example.com",
  "timestamp": "2026-04-16T...",
  "ok": false,
  "summary": {
    "totalMessages": 42,
    "errors": 1,
    "warnings": 6,
    "pageErrors": 0,
    "failedRequests": 0
  },
  "details": { ... }
}

Text

Raw streaming output — messages are printed in real-time as they occur.

Exit Codes

| Code | Meaning | |---|---| | 0 | OK — No console errors or uncaught exceptions | | 1 | Not OK — Errors found on the page | | 2 | Fatal — Could not load the page at all |

This makes it trivial to use in shell scripts and CI:

page-ok https://staging.example.com || echo "Build has errors!"

What It Checks

| Source | What's collected | |---|---| | Console | All console.* calls (error, warn, log, etc.) | | Page Errors | Uncaught JavaScript exceptions (window.onerror) | | Failed Requests | Network requests that returned error status codes |

Use Cases

• CI/CD smoke test — After deploying a PR, verify no console errors appear
• Local dev — Quickly check if your dev server is clean before committing
• Monitoring — Cron job that checks production pages periodically
• AI-assisted debugging — The summary JSON output is optimized for LLM consumption

How It Works

┌─────────────┐     Puppeteer      ┌──────────────┐
│  Target URL │ ──────────────────▶│ Headless Page │
│  (any URL)  │                    │              │
└─────────────┘                    │ Collect:     │
                                    │ • console.*  │
                                    │ • pageerror  │
                                    │ • req failed │
                                    └──────┬───────┘
                                           │
                                           ▼
                                    ┌──────────────┐
                                    │   Report:    │
                                    │ ✓ OK / ✗ ERR │
                                    │ + details    │
                                    └──────────────┘

Why domcontentloaded?

The tool uses domcontentloaded instead of networkidle2 for navigation. This avoids timeouts on pages with persistent WebSocket connections (e.g., Vite HMR, live reload). The --wait option gives control over how long to wait after DOM ready for async scripts to execute.

Requirements

• Node.js >= 16
• Chromium (bundled via puppeteer, auto-downloaded via page-ok setup)

Docker

When running page-ok in a container (e.g., CI/CD), you need both Chrome system libraries and the bundled browser:

RUN apt-get update && apt-get install -y \
    libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
    libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
    libgbm1 libpango-1.0-0 libcairo2 libasound2t64 fonts-liberation \
  && rm -rf /var/lib/apt/lists/*
# Then npm install will auto-download Chromium via puppeteer

Or simply run inside the container:

page-ok setup   # handles everything automatically

License

MIT