Getting Started

Prowl Documentation

Deterministic QA Hunts From Your CLI

Prowl 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 .prowl/runs/.

Install

npm install -g prowl-tools

Or with Homebrew:

brew tap prowl-tools/tap
brew install prowl

Prowl uses Playwright under the hood. Install the browser:

npx playwright install chromium

Initialize

cd your-project
prowl init

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

.prowl/
├── 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 .prowl/config.yml to point at your app:

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

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

Write Your First Hunt

Edit .prowl/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 prowl list
• tags — categorize hunts for filtering with --include-tags and --exclude-tags
• retry — configure automatic retries on failure (maxRetries: 0 means no retries)

Run

prowl 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: .prowl/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 28 step types available in hunts

Configuration

Tune browser behavior, artifacts, and guardrails

Variables

Inject credentials and dynamic runtime values safely