browser-driver
The browser driver for test-execution runs. It drives a real browser through playwright-cli for unprefixed (prose) spec steps and covers isolated sessions, screenshot and console evidence, login modes, and the failure signatures that decide retry versus defect. Use when a test-execution run's drivers include browser, before the first browser action; the test-execution orchestrator and qa-executor read it. Not a standalone entry point.
- License 许可
- MIT
- 最近更新
- 2026-10-26
- Stars
- ★ 21
- Forks
- 18
01 前言 Front Matter
- name
- browser-driver
- description
- The browser driver for test-execution runs. It drives a real browser through playwright-cli for unprefixed (prose) spec steps and covers isolated sessions, screenshot and console evidence, login modes, and the failure signatures that decide retry versus defect. Use when a test-execution run's drivers include browser, before the first browser action; the test-execution orchestrator and qa-executor read it. Not a standalone entry point.
- user-invocable
- false
02 资源文件 10
- 参考文档references/experience/gotchas.md4.0 KB
- 参考文档references/techniques/browser-checks.md2.2 KB
- 参考文档references/tools/fill-secret.md5.5 KB
- 参考文档references/tools/login-state.md4.5 KB
- 参考文档references/tools/playwright-cli.md7.7 KB
- 脚本scripts/fill_secret.js18.1 KB
- 脚本scripts/fill_secret.test.js26.0 KB
- 脚本scripts/login_state.e2e.test.js7.8 KB
- 脚本scripts/login_state.js17.1 KB
- 脚本scripts/login_state.test.js21.5 KB
03 SKILL.md 正文
Browser Driver
Role
You execute browser steps for a test-execution run through playwright-cli (via Bash), inside
the run's own session. You never modify application code. The run itself (modes, verdicts,
reports) belongs to the test-execution skill.
Principles
- Every command carries
-s=<session>, with the nameinit_run.jsgenerated for this run. Thedefaultsession is prohibited: a bare command lands there and collides with other executions (another Claude Code window on the same machine). - Never invent a bare session name like
test, and never reuse another execution's name. - Close only the session this run created:
-s=<session> close, even on failure. Never runclose-all/kill-all: they kill every session on the machine. The one exception is a global cleanup the user explicitly asks for, after confirming no other execution is running. - Console errors and failed network calls are defects, even when the UI looks fine.
- Screenshot every scenario, pass and fail, with
--filename=(never a positional path). - A "success" check reads the element's computed display/visibility. Text existing in the DOM is not proof.
- Run headless unless told otherwise.
--headedis for demos only. - Secret fields. Type every
{ "envSecret": "NAME" }value (password, OTP, national ID, any field) ONLY withnode ${CLAUDE_PLUGIN_ROOT}/skills/browser-driver/scripts/fill_secret.js --session <s> --target <ref> --env-var NAME [--env <env>] --submit(readreferences/tools/fill-secret.mdfirst). Never resolve, read, echo, or pass the value yourself, and never try another way (fill,type,run-code,$NAME): a refused command is not a puzzle to solve. Snapshot BEFORE filling and fill secrets last. A snapshot shows input values in clear text, passwords included, and every playwright-cli action writes one to.playwright-cli/, so run no other playwright-cli command between the first secret fill and the submit: submit in the last call with--submit(Enter) or--submit-target <pre-fill ref>, which then clears every secret field still holding its value. Segmented boxes (OTP digits): one call, one--targetper box, in order. If the submitting call never ran, take nosnapshot,evalorscreenshotof that page ("evidence withheld: secret field still filled").secret-unavailable→ the scenario is BLOCKED, never FAIL, nevercaptcha-or-otp.
Executing a browser step
- Before the first command in a session, read
references/tools/playwright-cli.md. snapshotto get element refs before interacting. Refs change on navigation: re-snapshot after each page load.- Act with a plain command in the shape
playwright-cli.mdgives: the target positional, no invented option. Use run-code only for what no command does. Never use it as the retry for a failed click, fill, check or select. Never useforce: trueor anelement.click()throughevaluate. Then verify with the techniques inreferences/techniques/browser-checks.md. - Save evidence under
SESSION_DIR: screenshots inscreenshots/<scenario>.png, console and network captures inlogs/<scenario>.log. - When a command fails or behaves unexpectedly, read
references/experience/gotchas.mdbefore deciding retry versus defect.
Login mode
The orchestrator resolves LOGIN_MODE. When a scenario needs user U signed in, go in this order:
| Mode | Do |
|---|---|
fresh |
Drive the login UI in this session (step 2 below). |
session, the login itself under test (a negative login, login-form checks) |
Start clean: npx playwright-cli -s=<session> cookie-clear, then npx playwright-cli -s=<session> localstorage-clear, then reload the login page (npx playwright-cli -s=<session> reload, or open the login URL again), because the form on screen just lost its own cookie. Only then drive the login UI (step 2). Never fill the form on the stale page. Never load or save a saved login here: a reused session would pass the scenario without testing the login. |
session, any other scenario |
Load the saved login (step 1). |
- Load. Read
references/tools/login-state.md, then runnode ${CLAUDE_PLUGIN_ROOT}/skills/browser-driver/scripts/login_state.js load --session <session> --user <U> --env <ENVIRONMENT>(leave out--envwhen ENVIRONMENT is empty). It loads the saved login into this session, opens the saved page and checks the saved landmark.- Exit 0
RESUME_PASS: you are signed in from the saved login. Continue with the steps. - Exit 1
RESUME_FAIL(with its reason): drive the login UI (step 2). Forlandmark-failedthe script cleared the cookies and localStorage and then reloaded the page itself, so go on to the login UI on that reloaded page with no reload of your own. For any other reason (no-state,no-landmark,cli-unsupported,state-unreadable,no-environment) nothing was cleared. - Exit 2
BLOCKED: the scenario is BLOCKED with the script's reason verbatim. A result markedinfrastructure: truegets the one retry the driver contract allows.
- Exit 0
- Drive the login UI in this session. A captcha, or an OTP you cannot obtain, is BLOCKED
captcha-or-otp: surface it, never defeat it (the optimize-login skill's Limits). Then verify you are in by a landmark element, never by the URL. No landmark: the login step fails, FAIL or BLOCKED by the usual rules, with its evidence kept. Landmark held: infreshmode, or when the login is under test, continue with the steps. - Save (
sessionmode, login not under test), only after the landmark proved you in.<landmark>is the selector of an element only a signed-in user sees:node ${CLAUDE_PLUGIN_ROOT}/skills/browser-driver/scripts/login_state.js save --session <session> --user <U> --present <landmark> --env <ENVIRONMENT>(leave out--envwhen ENVIRONMENT is empty). It checks the landmark on the current page again before it stores anything.- Exit 0 (
SAVEDorSKIPPED): continue with the steps. - Exit 1 or 2: add one report note, "saved login not stored: <reason>", and continue with the steps. A save that fails never changes a verdict.
- Exit 0 (
Saved logins are credentials (test/.auth/*-state.json and their sidecars):
- Never open, print, copy or edit one. Never run
state-loadorstate-saveyourself, and never put a cookie or storage value on a command line: onlylogin_state.jsmoves a saved login. - Never claim RESUME_PASS without the script's exit 0.
Output
Per browser step, hand back: the screenshot path, console and network notes, and observed vs. expected.
Resources
| File | Knowledge | Read when |
|---|---|---|
references/tools/playwright-cli.md |
Tool | Before the first command in a session |
references/tools/fill-secret.md |
Tool | Before the first { "envSecret" } field |
references/tools/login-state.md |
Tool | Before the first login_state.js call (session mode) |
references/techniques/browser-checks.md |
Technique | Verifying a step: visibility, console, network, RTL |
references/experience/gotchas.md |
Experience | A command fails or behaves unexpectedly |
04 同仓库更多 Skills
ui-check
Execute ui-check: steps in test specs — compare the live page currently open in the browser under test against a declared design baseline: a Figma frame (identifier only; file + token configured once per project) or a screenshot image, in exact mode (every visible detail) or reference mode (only enumerated details can fail). Triggers on spec steps starting with "ui-check:", or requests like "check this page against the design", "compare with the Figma frame", "does the screen match the mockup". Baselines are resolved by the bundled fetch_baseline.js runner — an unresolvable baseline is BLOCKED, never improvised; the comparison verdict itself is agent-vision judgment.
tracker-ops
Ad-hoc work-item operations on the configured tracker — Azure DevOps or Jira Cloud — behind one approval per write batch. Use this skill whenever the user asks for a one-off board operation outside the shipped flows: "move PROJ-12 to In Progress", "transition this issue to Done", "comment on bug 4711", "link X to Y", "update the story's title", "create a quick task on the board", "show me work item 42", "search the board for …". Every operation runs through ONE bundled script (dry run by default, REST over built-in fetch — no az, no acli); reads are free, writes show the exact request plan first and need the user's ONE approval before --execute. Unsupported operations are answered upfront from the tracker's capability flags — never guessed, never silently substituted.
test-execution
Run test specs against an application and report defects, routing each step to its driver (browser via playwright-cli, API calls, database checks, knowledge-base questions, UI design checks). Use whenever the user wants to test a website, web app, or API for defects (happy paths, edge cases, negative cases), either sequentially (human-in-the-loop, the default) or in parallel (autonomous). Produces per-scenario evidence plus a consolidated defect report. Read this before starting any test run.
test-design
Designs test cases for User Stories on the configured tracker — Azure DevOps or Jira Cloud: analyze a story's acceptance criteria into test conditions, map them to test case titles, create the test artifacts (ADO Test Cases with structured steps, or the Jira issue type the user chooses — Jira has no native Test Case type) and link them to the parent story, behind ONE consolidated approval. Use this skill whenever the user wants to: - Analyze a user story and identify test conditions - Map AC scenarios to test case titles using a naming convention - Create test cases in ADO with proper steps, or design test cases for a Jira story - Review whether a story's ACs are fully covered by test cases Trigger on phrases like: "create test cases for story", "design tests for", "design test cases for a Jira story", "what test cases do I need", "analyze story for testing", "map ACs to test conditions", or any time a user story ID or Jira issue key is mentioned alongside test design/coverage work.
task-estimation
Creates QA testing tasks with estimation on the configured tracker's User Stories — Azure DevOps or Jira Cloud. Reads the sprint, analyzes each story, then creates all [Testing] tasks (ADO Tasks or Jira sub-tasks) behind ONE consolidated approval, through bundled REST scripts (no Azure CLI, no acli). Use this skill whenever the user wants to: - Add QA tasks to sprint stories in Azure DevOps or Jira - Estimate testing hours for user stories - Create [Testing] tasks on ADO work items or [Testing] sub-tasks on Jira issues - Plan QA effort for a sprint - Break down stories into testing tasks with hours Trigger on phrases like: "create tasks for stories", "add QA tasks", "estimate sprint", "estimate the Jira sprint", "create testing tasks", "create tasks for Jira sprint stories", "add sub-tasks to Jira stories", "plan QA for sprint", "add tasks to stories", or any mention of sprint stories + estimation + testing.
swagger-import
Generate an API catalog + suite of test cases (integration/api_test_suites/<service>/) from a Swagger 2.0 or OpenAPI 3.x JSON document. Use for /import-swagger, or requests like "import this swagger doc", "generate endpoint tests from this OpenAPI spec", or the guided wizard (/import-swagger --wizard) that collects real test data and previews basic checks (happy path, not found, no token, missing field) before one approval. Output feeds directly into the endpoint-testing and api-integration skills. This skill generates config and sends no API request of its own; any run, including the wizard's "Approve and run now", goes through endpoint-testing's runner.