Skip to content
Skills Library
Programming · Testing

watchwright

/watchwright

Write, run and fix browser tests with Watchwright, a Playwright test harness whose runs the person watches live on its web page. Use it when asked to test a website, write or fix a Watchwright test or test pack, run a pack, or read a run's results and screenshots. Works through the Watchwright MCP tools or the watchwright command.

Repository
watchwright ↗
Licence
Apache-2.0
Last repository change
12.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Write, run and fix browser tests with Watchwright, a Playwright test harness whose runs the person watches live on its web page. Use it when asked to test a website, write or fix a Watchwright test or test pack, run a pack, or read a run's results and screenshots. Works through the Watchwright MCP tools or the watchwright command.

Original author description

Write, run and fix browser tests with Watchwright, a Playwright test harness whose runs the person watches live on its web page. Use it when asked to test a website, write or fix a Watchwright test or test pack, run a pack, or read a run's results and screenshots. Works through the Watchwright MCP tools or the watchwright command.

How it works

  1. Start
  2. The loop
  3. Rules
  4. References
Original SKILL.md headings · 42 lines, 801 words
SKILL.md preview
---
name: watchwright
description: Write, run and fix browser tests with Watchwright, a Playwright test harness whose runs the person watches live on its web page. Use it when asked to test a website, write or fix a Watchwright test or test pack, run a pack, or read a run's results and screenshots. Works through the Watchwright MCP tools or the watchwright command.
---

# Watchwright

Watchwright runs browser test packs on a local server (by default `http://127.0.0.1:7420/`; the MCP server's instructions give its real address) and shows every run live on its web page. A **pack** is a folder: `pack.yaml` (or `watchwright.pack.ts`) for the site and options, and tests under `tests/`, in YAML (a list of steps) or TypeScript. You reach it through the MCP tools (`list_packs`, `start_run`, …) or the `watchwright` command; both do the same.

## Start

1. Check the server: `list_packs`, or `watchwright status`. When nothing answers, start it with `watchwright serve --no-open` (it keeps running; the MCP bridge starts one by itself).
2. Tell the person the web page's address so they can watch what you do: the run's own page, which `start_run` gives as "Watch it live: …", or the address in the MCP server's instructions. Don't assume port 7420; a server can run on another.
3. Read the pack: `get_pack` (tests, parameters, flags), `list_pack_files` and `read_pack_file`.

## The loop

1. **Explore** before writing: `explore_start`, then `explore_look` (the page as an aria snapshot; every element has a ref like `e4`) and `explore_do` (steps; a target can be `{ "ref": "e4" }`). Refs become real targets in the steps you get back. `explore_stop` answers the steps as YAML. Without MCP, read the page some other way and write the steps yourself.
2. **Write the test**, YAML first: `id`, `title`, `steps`. Use code only when YAML can't say it (loops over data, computed values, helpers). Prefer targets a person reads (`role` + `name`, `label`, `text`, `testId`) over CSS. Check each step's fields in [yaml-steps.md](references/yaml-steps.md).
3. **Check** it without saving: `check_test` with the file's text. Fix every problem it lists.
4. **Save** with `write_pack_file` (pass the `stamp` from `read_pack_file` when changing a file). The answer lists the pack's load problems; fix them.
5. **Run** only the tests you need: `start_run` with `tests: ["T1"]`, or `watchwright run <pack> T1`.
6. **Wait** in steps: `wait_for_run` waits up to 110 seconds (60 by default); while its `reason` is `timeout`, call it again with `after` set to the `cursor` it gave, until the reason is `ended` or `paused`. A run paused on a broken attempt (`pauseReason: broken`) waits for you: look at the attempt, then `control_run` with retry or skip. With the command line: `watchwright wait <run>`, again with `--after <cursor>` while it exits 6.
7. **Read** `get_run` (one line per attempt), then `get_attempt` for one that didn't pass: its error, the step it stopped at, the log, flags and files. Look at its screenshots with `get_file`; they come back as images.
8. **Decide** whose fault it is. An attempt is `failed` when an expectation didn't hold and `broken` when the robot couldn't do a step (a target not found, a timeout). A broken attempt is a problem in the test until the screenshots say otherwise: fix the target or add a wait and run again. A failure the screenshots confirm is a finding about the site: report it to the person with the run's address, the step and what the screenshot shows. Don't change the test to make a real failure pass.

## Rules

- Never stop, pause or change a run you didn't start, and only stop explore sessions you started.
- Never delete runs, packs or files unless the person asks. Deleting waits for the person to approve it on the web page; when a tool answers that it is waiting, tell the person, then wait with `wait_for_approval` (or `watchwright approvals wait <id>`).
- When a run is paused by a person (`pausedBy` in its `live` state), stop and ask them before doing anything to it.
- Keep every wait bounded and keep the person told: what you ran, its address, and what you found.
- Don't run a whole pack to check one test; packs can take hours.
- Keep secrets out of test files: use `${secret.NAME}` (or `h.secret("NAME")`) for passwords and tokens, and `${params.name}` for values a run chooses. The person sets secrets on Admin › Secrets; ask them for the name rather than for the value. `${env.NAME}` reads the machine's environment.
- For a site that needs signing in, prefer one login test that ends with `saveSignIn` and runs that start signed in (`signIn: true`, or `site.signIn: saved` in the pack) over logging in at the start of every test.
- Schedules and alerts act while nobody watches. Create or change them only when the person asks; like deleting, they wait for the person's approval.

## References

- [yaml-tests.md](references/yaml-tests.md): YAML test files, targets, variables, hooks.
- [yaml-steps.md](references/yaml-steps.md): every step and its fields.
- [test-packs.md](references/test-packs.md): packs in code, `test()`, `h` helpers, options, parameters, flags.
- [tasks.md](references/tasks.md): setup, teardown, pack tasks (run with `kind: "task"`) and pack state.
- [mcp.md](references/mcp.md): every MCP tool and exploring.
- [cli.md](references/cli.md): every command and exit code.
Files in this package (7)
  • SKILL.md 5 KB
  • references/cli.md 18 KB
  • references/mcp.md 8 KB
  • references/tasks.md 7 KB
  • references/test-packs.md 33 KB
  • references/yaml-steps.md 12 KB
  • references/yaml-tests.md 10 KB

Versions

The database has no other skills named watchwright.

Database snapshot: 13.11.2026 · package version 698f20e65d89 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100playwright-testing
    UI/E2E test automation with Playwright MCP. Use when the user asks to "test the UI", "automate browser tests", "check the page", "take a screenshot", "run Playwright", "write E2E tests", or anything about browser-based testing.
  • 100ce-test-browser
    Run browser tests for pages affected by the current branch or PR. Use when asked to run or check browser tests for the current change.
  • 95memstack-development-webapp-testing
    Use when the user says 'write browser tests', 'test this page', 'playwright test', 'e2e test', 'end to end test', 'browser test', 'test the UI', or needs Playwright-based browser testing for a web application. Do NOT use for unit tests, API tests, or non-browser testing.
  • 100playwright-test-writer
    Write or extend Playwright end-to-end tests for a web page or feature. Use when the user asks to add, write, improve or fix Playwright, e2e or browser tests.
  • 100debug-e2e-test
    Debug and fix failing Playwright E2E tests. Use when tests fail, when asked to fix failing tests, or when investigating test failures. Analyzes test output, screenshots, error context, and uses Playwright MCP to identify root causes.
  • 100playwright-expert
    Use when writing E2E tests with Playwright, setting up test infrastructure, or debugging flaky browser tests. Invoke to write test scripts, create page objects, configure test fixtures, set up reporters, add CI integration, implement API mocking, or perform visual regression…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.