AGENT SKILL

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

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 name init_run.js generated for this run. The default session 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 run close-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. --headed is for demos only.
  • Secret fields. Type every { "envSecret": "NAME" } value (password, OTP, national ID, any field) ONLY with node ${CLAUDE_PLUGIN_ROOT}/skills/browser-driver/scripts/fill_secret.js --session <s> --target <ref> --env-var NAME [--env <env>] --submit (read references/tools/fill-secret.md first). 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 --target per box, in order. If the submitting call never ran, take no snapshot, eval or screenshot of that page ("evidence withheld: secret field still filled"). secret-unavailable → the scenario is BLOCKED, never FAIL, never captcha-or-otp.

Executing a browser step

  1. Before the first command in a session, read references/tools/playwright-cli.md.
  2. snapshot to get element refs before interacting. Refs change on navigation: re-snapshot after each page load.
  3. Act with a plain command in the shape playwright-cli.md gives: 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 use force: true or an element.click() through evaluate. Then verify with the techniques in references/techniques/browser-checks.md.
  4. Save evidence under SESSION_DIR: screenshots in screenshots/<scenario>.png, console and network captures in logs/<scenario>.log.
  5. When a command fails or behaves unexpectedly, read references/experience/gotchas.md before 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).
  1. Load. Read references/tools/login-state.md, then run node ${CLAUDE_PLUGIN_ROOT}/skills/browser-driver/scripts/login_state.js load --session <session> --user <U> --env <ENVIRONMENT> (leave out --env when 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). For landmark-failed the 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 marked infrastructure: true gets the one retry the driver contract allows.
  2. 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: in fresh mode, or when the login is under test, continue with the steps.
  3. Save (session mode, 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 --env when ENVIRONMENT is empty). It checks the landmark on the current page again before it stores anything.
    • Exit 0 (SAVED or SKIPPED): 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.

Saved logins are credentials (test/.auth/*-state.json and their sidecars):

  • Never open, print, copy or edit one. Never run state-load or state-save yourself, and never put a cookie or storage value on a command line: only login_state.js moves 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

MhmdElGazzar
MhmdElGazzar/agentex

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.

★ 21
MhmdElGazzar
MhmdElGazzar/agentex

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.

★ 21
MhmdElGazzar
MhmdElGazzar/agentex

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.

★ 21
MhmdElGazzar
MhmdElGazzar/agentex

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.

★ 21
MhmdElGazzar
MhmdElGazzar/agentex

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.

★ 21
MhmdElGazzar
MhmdElGazzar/agentex

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.

★ 21