Getting Started

Prowl QA Documentation

Deterministic QA Hunts From Your CLI

Prowl QA turns browser workflows into repeatable hunts you can run locally, in CI, or hand to an AI agent. This page gets you from zero to a passing smoke test quickly.

Start In 60 SecondsBrowse Step Types

Before you start: Node.js 20+, npm, and a runnable web app.

Outcome

By the end of this guide, you will run one hunt that validates your homepage and produces artifacts under .prowlqa/runs/.

Install

npm install -g prowlqa

Prowl QA uses Playwright under the hood. Install the browser:

npx playwright install chromium

Initialize

cd your-project
prowlqa init

This creates a .prowlqa/ directory with a config file and 8 starter hunts:

.prowlqa/
├── config.yml              # Target URL, browser settings, guardrails
└── hunts/
    ├── homepage.yml         # Basic page load smoke test
    ├── login-flow.yml       # Email/password authentication
    ├── signup-flow.yml      # Registration with validation
    ├── form-submit.yml      # Form fill and submit
    ├── form-validation.yml  # Validation errors and resubmit
    ├── crud-cycle.yml       # Create, read, update, delete lifecycle
    ├── checkout-flow.yml    # E-commerce checkout
    └── onboarding-wizard.yml # Multi-step SaaS onboarding

Configure

Edit .prowlqa/config.yml to point at your app:

target:
  url: "http://localhost:3000"

If your app uses authentication, capture storage state early with prowlqa login so hunts run as an authenticated user.

Write Your First Hunt

Edit .prowlqa/hunts/homepage.yml or create a new file:

name: smoke-test
description: "Validates homepage loads correctly"
tags:
  - smoke
steps:
  - navigate: "/"
  - wait: "Welcome"
  - assert:
      visible: "Sign In"
assertions:
  - noConsoleErrors: true
retry:
  maxRetries: 0
  delay: 1000

note

• description — a human-readable summary stored in hunt metadata and shown by prowlqa list
• tags — categorize hunts for filtering with --include-tags and --exclude-tags
• retry — configure automatic retries on failure (maxRetries: 0 means no retries)

Run

prowlqa run smoke-test

  ● Running hunt: smoke-test
    ✓ navigate "/" (120ms)
    ✓ wait "Welcome" (85ms)
    ✓ assert visible "Sign In" (15ms)

  PASS smoke-test (220ms) 3/3 steps
  Artifacts: .prowlqa/runs/2026-02-09_10-30-45

You now have a stable smoke test and a run artifact folder you can inspect in CI.

What's Next

Assertions

Fail fast with inline and hunt-level checks

Step Types

All 19 step types available in hunts

Configuration

Tune browser behavior, artifacts, and guardrails

Variables

Inject credentials and dynamic runtime values safely