Your first run

This page walks through a cold start no knowledge base, no prior runs, just a fresh install and a URL.

Starting state

After ./scripts/install.sh (one-shot bootstrap) you have nitpick on your PATH. Create a per-app project directory and work from there:

~/my-app-qa/
├── nitpick.yaml    # ← you'll create this with `nitpick init`
├── .env            # ← also written by init, auto-loaded on every run
├── knowledge-base/ # empty until first crawl
└── runs/           # empty until first run

One dir per app you test — configs, credentials, and the knowledge base stay isolated.

Step 1: nitpick init (~60 seconds)

Walks through ~10 quick questions. Key inputs:

• Base URL of the app under test
• LLM provider + API key, then a model picker with rough per-run cost estimates
• Role credentials. Leave Login URL path blank for SPAs that auto-redirect to login or show a login modal on the base URL
• Persistent instructions (optional, free-form) the scope router obeys on every run — e.g. “only test /tasks/new”, “skip billing”

Writes nitpick.yaml + .env. See Install for the full flow.

Step 2: nitpick crawl (2–5 minutes)

Builds the page graph from scratch. You’ll see:

[14:32:01] Starting crawl { base_url:"...", spa_mode: true }
[14:32:03] Crawling as role { role:"admin" }
[14:33:41] Crawl complete { pages: 15, edges: 42 }
Discovered 15 pages in 100s

Now on disk:

knowledge-base/
├── auth/admin.json
└── page-graph.json

Step 3: Smoke check (optional, ~90 seconds)

nitpick run --scope smoke

Fast sanity check. If this passes, your pipeline is healthy.

Step 4: First deep test

Either one page:

nitpick run --scope targeted --url /tasks/new

Or the whole thing (15–45 min):

nitpick run --scope full

The Phase 3.5 checkpoint

After exploration + synthesis, Junior QA presents what it found and asks you to approve. Your context gets merged into the model. Junior QA then generates Playwright tests, runs them, and reports.

Step 5: Open the report

open runs/<timestamp>/reports/unified-report.html

A GitHub-styled dashboard with:

• Header stats (pages passed/failed, total tests, bugs)
• Per-page sections (collapsible, with failure details inline)
• Flow results
• App bugs (with severity)
• Flaky test registry
• Changes since last run (empty on first run)

Common first-run issues

Auth failure. If your app has OAuth, MFA, or a non-standard login form, the default crawler auth will fail. See Troubleshooting.

Crawler finds 0 pages. Some SPAs render everything client-side with no <a> tags. Nitpick’s SPA mode handles most, but not all. Fall back to --scope targeted --url /a --url /b.

A page test hits max iterations. Default is 100. If the app is confusing the agent, lower llm.max_iterations in your config or improve the terminal guard list.