Your first run

This guide installs Pingwright and runs one scenario. You need Node 22.18 or newer and a site with a cookie banner.

A coding agent, for example Claude Code, can do these steps for you. Copy the prompt and paste it into the agent. The agent installs Pingwright, asks for your site and writes your first scenarios.

Read the prompt

Set up Pingwright to test the tracking and the cookie consent on my website.

Pingwright is a command-line tool. It opens my site in a real browser, acts as a visitor, records every tracking request and checks the requests against rules that I write. The docs are at https://pingwright.dev.

1. Install it with `npm i -g pingwright@next`, then run `pingwright install-browser`. Check that `pingwright --version` works.
2. Read https://pingwright.dev/docs/guide/first-run and https://pingwright.dev/docs/cli before you write a scenario. Use `pingwright run --help` for the flags. Do not guess flags or step names.
3. Ask me for the address of my site and the tracking tools it uses, for example GA4, Google Ads, Meta or Pinterest.
4. Write three scenarios in a `pingwright/` folder: the visitor ignores the cookie banner (`consent: none`), accepts it (`consent: accept`) and rejects it (`consent: reject`). Each scenario opens the home page and one product or content page. Add rules: no Meta or Google Ads hit before consent, no marketing hit after a reject, and the analytics hits that I expect after an accept.
5. Run each scenario with `pingwright run <file> --site <address>`. Keep the default network mode, `stub`, so no tracking hit leaves my machine.
6. Show me a short table: the scenario, the result, and each failed rule with its evidence IDs. Explain each failure in plain words. Tell me if it looks like a real problem on my site or a rule that needs a change.

Rules for you:
- Never type real personal data. Pingwright makes a fake visitor for each run.
- Never automate a payment or a log-in. Use a `handoff` step and ask me to do that part.
- Do not use `--network live` unless I ask for it.
- Keep the `runs/` folder on my machine. Do not commit it or upload it.

Install

npm i -g pingwright@next
pingwright install-browser

The first command installs the pingwright command. The second installs Chromium, the browser that Pingwright drives. Both steps are needed once per machine. The CLI page lists other ways to install.

Write a scenario

A scenario is a YAML file. Save this as scenario.yml:

start: /
steps:
  - consent: none
  - wait: 4s
expect:
  mustNot:
    - { vendor: [meta, google-ads], before: consent }

This is what each part does:

• start: / opens the home page of the site.
• consent: none checks that a cookie banner is on the page. It does not answer the banner.
• wait: 4s waits 4 seconds so that late requests can arrive.
• mustNot is an expectation: a rule about which requests the site may send. It says that Meta and Google Ads must send nothing before the visitor answers the banner.

If the page shows no banner, the run stops with "banner not shown" and exit code 2.

Run it

pingwright run scenario.yml --site https://test.example.com

Replace the address with your own site. Use a test copy of your site when you can.

flowchart TB
  a["scenario.yml<br/>and --site"] --> b["pingwright run"]
  b --> c["Chromium plays<br/>the visitor"]
  c --> d["Text summary,<br/>record file<br/>runs/run_ID.jsonl,<br/>exit code 0, 1 or 2"]

pingwright run plays the scenario in Chromium, then prints a summary, writes a record file and sets the exit code.

The summary lists the hits, the consent epochs and each check with PASS or FAIL. Reading a run's results explains it line by line.

The exit code

Code	Meaning
0	Every expectation and built-in check passed.
1	At least one expectation or built-in check failed.
2	The run could not finish. For example, the scenario is not valid, or no banner was shown.

A script can read this code. So can a job that runs your tests on every change. Code 1 means the site broke an expectation. Code 2 means the run itself needs a fix.

Safe by default

• The run is in stub mode. Pingwright records known tracking requests and answers them itself. It does not send them on. See What Pingwright checks.
• Pingwright types fake data only.
• A request to a site it does not know is flagged as an unknown destination, and the run fails. Allow a host in the scenario with options: { allowUnknownDestination: ['tracker.example.net'] }.

Next

• Reading a run's results
• CLI reference for every option and command
• Design for scenario steps and expectations