playwright-test-agent 1.0.0 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,17 +1,21 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "playwright-test-agent",
|
|
3
|
-
"version": "1.0.
|
|
4
|
-
"description": "Initialize Playwright Test agents with a Playwright CLI-first browser workflow.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"bin": {
|
|
7
|
-
"playwright-test-agent": "bin/playwright-test-agent.mjs"
|
|
8
|
-
},
|
|
9
|
-
"files": [
|
|
10
|
-
"bin/",
|
|
11
|
-
"playwright-test-agent/"
|
|
12
|
-
],
|
|
13
|
-
"engines": {
|
|
14
|
-
"node": ">=18"
|
|
15
|
-
},
|
|
16
|
-
"license": "UNLICENSED"
|
|
17
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "playwright-test-agent",
|
|
3
|
+
"version": "1.0.2",
|
|
4
|
+
"description": "Initialize Playwright Test agents with a Playwright CLI-first browser workflow.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"playwright-test-agent": "bin/playwright-test-agent.mjs"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"bin/",
|
|
11
|
+
"playwright-test-agent/"
|
|
12
|
+
],
|
|
13
|
+
"engines": {
|
|
14
|
+
"node": ">=18"
|
|
15
|
+
},
|
|
16
|
+
"license": "UNLICENSED",
|
|
17
|
+
"devDependencies": {
|
|
18
|
+
"@playwright/test": "^1.62.1",
|
|
19
|
+
"@types/node": "^26.4.0"
|
|
20
|
+
}
|
|
21
|
+
}
|
|
@@ -5,7 +5,7 @@ description: Use first when a user asks to investigate or test a website, browse
|
|
|
5
5
|
|
|
6
6
|
# Playwright Test Agent
|
|
7
7
|
|
|
8
|
-
Use Planner -> Generator -> execute -> Healer (only on failure) for durable tests.
|
|
8
|
+
Use Planner -> Generator -> execute -> Healer (only on failure) for durable tests when new coverage is needed. Before choosing that path, inspect existing tests under the configured `testDir`. If they already fully cover the user's objective and assertions, skip Planner and Generator and execute the matching existing tests directly. Follow the platform routing defined by the project's `AGENTS.md` or `CLAUDE.md`.
|
|
9
9
|
|
|
10
10
|
## Required phase handoff
|
|
11
11
|
|
|
@@ -15,7 +15,7 @@ Use Planner -> Generator -> execute -> Healer (only on failure) for durable test
|
|
|
15
15
|
4. The parent executes the generated tests with `npx playwright test`.
|
|
16
16
|
5. If all generated tests pass, report the result. If any fail, Healer diagnoses, fixes justified test defects, and reruns the affected tests until they pass or a genuine blocker is identified.
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
Planner and Generator are conditional phases: use them only when preflight finds missing or insufficient coverage. Planner exploration without a saved plan is incomplete, and Generator output without test files is incomplete. Any selected or generated tests must be executed; Healer must never start before a real test failure exists.
|
|
19
19
|
|
|
20
20
|
Preserve the official Playwright Test MCP configuration and role tools. Use `playwright-cli` as the preferred live-browser path when the role instructions select it; missing optional MCP tools must not block a role when the CLI can perform the same work.
|
|
21
21
|
|
|
@@ -23,19 +23,21 @@ Before Planner, the parent may read relevant local project information to unders
|
|
|
23
23
|
|
|
24
24
|
If the available context is sufficient, start/enter Planner without further confirmation. During exploration, pause when required information is missing, incorrect, or contradictory, including credentials, URL, role, prerequisites, expected behavior that changes assertions, or authorization for a consequential action. Ask the user for the specific correction, then resume or restart Planner with the answer and blocking observation. Do not guess credentials, probe nearby environments, bypass access controls, or wander through unrelated pages.
|
|
25
25
|
|
|
26
|
-
Keep credentials and tokens in environment variables or ignored secret files. Never copy them into plans, tests, screenshots, evidence, or chat.
|
|
26
|
+
Keep credentials and tokens in environment variables or ignored secret files. Never copy them into plans, tests, screenshots, evidence, or chat. Browser snapshots and session artifacts produced by `playwright-cli` under `.playwright-cli` are reusable workflow state: preserve them across Planner, Generator, and Healer phases by default. Do not clean up snapshots, sessions, or other transient browser artifacts merely because they were created during validation. Remove or redact only a file that is confirmed to contain an exposed credential/token, or when the user explicitly requests cleanup.
|
|
27
27
|
|
|
28
28
|
## Planner
|
|
29
29
|
|
|
30
|
-
Planner—not the parent—opens the supplied URL with `playwright-cli open <deployed-url>`, investigates the application, converts its findings into a human-readable Markdown test plan, and saves it under `specs/`. Once
|
|
30
|
+
Before starting Planner, the parent performs a focused preflight: reads relevant local project information, resolves Playwright's configured `testDir`, and inspects tests in that directory for reusable coverage, fixtures, routes, and constraints. Compare their scenarios and assertions with the user's objective. If coverage is complete, report the matching paths and run them directly with `npx playwright test <paths>`; do not start Planner or Generator. If coverage is partial or absent, continue to Planner and pass the reusable paths and coverage gaps. This initializer defaults `testDir` to `./playwright-tests`; respect an existing project's configured value instead. Do not broadly scan the repository for test files unless no Playwright configuration or test directory can be resolved. If the project and user-provided information are insufficient or contradictory for the objective, URL, account or role, expected behavior, environment, prerequisites, or authorization boundary, the parent asks the user for the specific missing information and waits for the answer. Planner—not the parent—opens the supplied URL with `playwright-cli open <deployed-url>`, investigates the application, converts its findings into a human-readable Markdown test plan, and saves it under `specs/`. Once all required information is available, Planner's first browser action must be that CLI command. It then uses compact `snapshot` or `find` output and refs for interaction.
|
|
31
31
|
|
|
32
32
|
The plan contains prerequisites, test data, independent scenarios, steps, observable expected results, exclusions, and intended output files. Reconnaissance must not mutate durable/shared data or perform consequential actions unless authorized.
|
|
33
33
|
|
|
34
34
|
Planner returns the saved plan path and a scenario summary. The parent shows the plan and exclusions to the user. Generator starts only after the user explicitly confirms that plan.
|
|
35
35
|
|
|
36
|
+
Planner, Generator, and Healer may reuse the existing `.playwright-cli` session and snapshot state when the target, account, and authorization context are compatible. Prefer reusing that state over deleting it and starting from scratch; if it is stale or incompatible, start a new session without deleting the old artifacts unless cleanup is explicitly requested.
|
|
37
|
+
|
|
36
38
|
## Generator
|
|
37
39
|
|
|
38
|
-
Generator starts only after confirmation and converts the confirmed plan into executable Playwright test code. Generator—not the parent—uses `playwright-cli` to validate flows, locators, and assertions, writes
|
|
40
|
+
Generator starts only after confirmation and converts the confirmed plan into executable Playwright test code. Pass the resolved Playwright `testDir` to Generator. Generator—not the parent—uses `playwright-cli` to validate flows, locators, and assertions, writes every new test inside that configured `testDir`, and returns their paths. Generic `tests/` paths in generated role examples, plans, or seed references do not override the configured directory. Generate only confirmed scenarios; prefer independent tests, semantic locators, explicit assertions, and environment-based secrets.
|
|
39
41
|
|
|
40
42
|
After Generator returns, the parent executes the generated test files with `npx playwright test`. This execution step is mandatory. If all tests pass, report the executed result. If any fail, pass the failed test names, failure output, confirmed plan, and generated file paths to Healer.
|
|
41
43
|
|
|
@@ -13,11 +13,11 @@ const cliFirstInstructions = (role) => `${ROLE_BLOCK_START}
|
|
|
13
13
|
|
|
14
14
|
## Browser tool priority
|
|
15
15
|
|
|
16
|
-
Use the installed \`playwright-cli\` command as the primary browser interface for this role. Read the globally installed \`playwright-cli\` skill when available. Start or attach a session with \`playwright-cli open\`/\`attach\`, navigate with \`goto\`, inspect compact state with \`snapshot\`, and interact through refs from the latest snapshot. Prefer \`snapshot\` and \`find\` over screenshots. Keep credentials in environment variables or ignored files and never print them.
|
|
16
|
+
Use the installed \`playwright-cli\` command as the primary browser interface for this role. Read the globally installed \`playwright-cli\` skill when available. Start or attach a session with \`playwright-cli open\`/\`attach\`, navigate with \`goto\`, inspect compact state with \`snapshot\`, and interact through refs from the latest snapshot. Prefer \`snapshot\` and \`find\` over screenshots. Keep credentials in environment variables or ignored files and never print them. Preserve \`.playwright-cli\` snapshots, sessions, and other browser artifacts for reuse by later phases; do not delete validation artifacts by default. Only remove or redact a confirmed credential/token leak, or act on an explicit cleanup request.
|
|
17
17
|
|
|
18
18
|
Keep the official Playwright Test MCP configuration and tools generated for this role; do not remove or disable them. Prefer CLI for live page interaction and use it when those MCP tools are unavailable, so missing \`planner_*\`, \`generator_*\`, \`test_*\`, or \`browser_*\` tools must not block the phase. Do not call Chrome DevTools or an unrelated browser integration, and do not spawn a nested or same-role agent.
|
|
19
19
|
|
|
20
|
-
${role === 'planner' ? 'FAST START: you are the Planner. The parent
|
|
20
|
+
${role === 'planner' ? 'FAST START: you are the Planner. The parent must first perform a focused preflight of the project and tests under Playwright\'s configured `testDir`, then pass the findings and any user-provided answers to you. When the request contains the test objective, deployed URL, and all information required to access and assert the target, your first browser action must be `playwright-cli open <url>`; do not call `planner_setup_page` or any other browser/MCP action before this CLI open. After the session is open, use compact CLI `snapshot`/`find` output for exploration; MCP tools remain available as an optional supplement. Do not wait for the parent agent to open a browser. If the preflight context is insufficient, missing, or contradictory, stop and return the precise question for the user instead of guessing. Investigation is not the final output: you must turn the findings into a complete Markdown test plan and save it under `specs/` using filesystem tools or the available planner save tool. Return the saved plan path and scenario summary to the parent.' : ''}${role === 'generator' ? 'You are the Generator. Start only after the user confirms the saved test plan. The parent must pass Playwright\'s configured `testDir`; resolve it from `playwright.config.*` yourself if it was omitted. Write every new test file inside that resolved directory. Ignore generic `tests/` paths in upstream role descriptions, examples, plans, or seed references when they conflict with the configured `testDir`. Begin live validation with `playwright-cli open`/`attach` and use CLI snapshots/find to verify the confirmed plan; MCP setup and browser tools remain optional. Generate executable Playwright test code for the confirmed scenarios and write the test files using filesystem tools or the available generator write tool. Return the generated test file paths to the parent; generating code does not complete the workflow because the parent must execute the generated tests next.' : ''}${role === 'healer' ? 'You are the Healer. Start only after execution of the generated tests reports failures. Receive the failing test names and failure output, reproduce them with `npx playwright test`, begin UI diagnosis with `playwright-cli open`/`attach`, and use CLI snapshots/find to inspect the current UI; MCP tools remain optional. Diagnose and patch justified test defects, rerun the affected tests, and continue within the healer guardrails until they pass or a genuine application/environment/product blocker is identified. Return the final run result and classification to the parent.' : ''}
|
|
21
21
|
|
|
22
22
|
${ROLE_BLOCK_END}`;
|
|
23
23
|
const CODEX_INSTRUCTIONS = `${BLOCK_START}
|
|
@@ -26,10 +26,10 @@ const CODEX_INSTRUCTIONS = `${BLOCK_START}
|
|
|
26
26
|
Codex routing is mandatory for website, browser workflow, HTTP API, or application-feature testing:
|
|
27
27
|
|
|
28
28
|
1. Load \`.agents/skills/playwright-test-agent/SKILL.md\`.
|
|
29
|
-
2. Before starting Planner, the main agent
|
|
30
|
-
3.
|
|
29
|
+
2. Before starting Planner, the main agent must perform a focused preflight: read relevant local project information, resolve Playwright's configured \`testDir\`, and inspect tests in that directory for reusable coverage, fixtures, routes, and constraints. Compare existing scenarios and assertions with the objective. If existing tests fully cover the objective, report their paths and run them directly with \`npx playwright test <paths>\`; skip Planner and Generator. Only start Planner when coverage is partial or absent. This initializer defaults \`testDir\` to \`./playwright-tests\`; respect an existing configured value and do not broadly scan the repository unless no Playwright configuration or test directory can be resolved. The main agent may not open or inspect the website during preparation. If the project and user-provided information are insufficient or contradictory for the objective, URL, account or role, expected behavior, environment, prerequisites, or authorization boundary, ask the user for the specific missing information and wait for the answer.
|
|
30
|
+
3. When preflight finds missing or insufficient coverage, directly start a subagent with \`agent_type: "playwright_test_planner"\`, passing the objective, deployed URL, supplied access information, preflight findings (including reusable test files and coverage gaps), relevant project context, and constraints. The main agent must not perform Planner work, open or inspect the website, or call \`playwright-cli\`, browser MCP tools, Chrome DevTools, or another browser integration.
|
|
31
31
|
4. Planner opens and investigates the website with \`playwright-cli\`, converts its findings into a complete Markdown test plan under \`specs/\`, and returns the saved plan path. After Planner returns, show that plan to the user and wait for explicit confirmation; investigation alone is not completion.
|
|
32
|
-
5. Only after confirmation, directly start a subagent with \`agent_type: "playwright_test_generator"\`, passing the confirmed plan
|
|
32
|
+
5. Only after confirmation, directly start a subagent with \`agent_type: "playwright_test_generator"\`, passing the confirmed plan and resolved \`testDir\`. Generator validates the confirmed scenarios with \`playwright-cli\`, writes every executable test inside that \`testDir\`, and returns their paths.
|
|
33
33
|
6. After Generator returns, the main agent must execute the generated tests with \`npx playwright test\`. Generating test files alone never completes the workflow.
|
|
34
34
|
7. If every generated test passes, report the result. If any generated test fails, directly start a subagent with \`agent_type: "playwright_test_healer"\`, passing the failed test names, failure output, confirmed plan, and generated file paths. Healer diagnoses and patches justified test defects and reruns the affected tests until they pass or it identifies a genuine application/environment/product blocker. Never report generated-but-unexecuted tests as passing.
|
|
35
35
|
|
|
@@ -43,10 +43,10 @@ const CLAUDE_INSTRUCTIONS = `${BLOCK_START}
|
|
|
43
43
|
Claude Code routing is mandatory for website, browser workflow, HTTP API, or application-feature testing:
|
|
44
44
|
|
|
45
45
|
1. Load \`.claude/skills/playwright-test-agent/SKILL.md\`.
|
|
46
|
-
2. Before starting Planner, the main agent may read relevant local project information and ask for information that materially affects the test, such as the deployed URL, account or role, expected behavior, environment, and authorization boundary.
|
|
47
|
-
3.
|
|
46
|
+
2. Before starting Planner, the main agent resolves Playwright's configured \`testDir\` and inspects tests there. Compare existing scenarios and assertions with the objective. If existing tests fully cover it, report their paths and run them directly with \`npx playwright test <paths>\`; skip Planner and Generator. Only start Planner when coverage is partial or absent. The main agent may also read relevant local project information and ask for information that materially affects the test, such as the deployed URL, account or role, expected behavior, environment, and authorization boundary.
|
|
47
|
+
3. When preflight finds missing or insufficient coverage and the required context is available, directly start \`playwright-test-planner\` with the objective, deployed URL, supplied access information, reusable test paths, coverage gaps, relevant project context, and constraints. The main agent must not open or inspect the website itself and must not call \`playwright-cli\`, Chrome DevTools, browser MCP tools, or another browser integration.
|
|
48
48
|
4. Planner opens and investigates the website with \`playwright-cli\`, converts its findings into a complete Markdown test plan under \`specs/\`, and returns the saved plan path. After Planner returns, show that plan to the user and wait for explicit confirmation; investigation alone is not completion.
|
|
49
|
-
5. Only after confirmation, directly start \`playwright-test-generator\` with the confirmed plan
|
|
49
|
+
5. Only after confirmation, directly start \`playwright-test-generator\` with the confirmed plan and resolved \`testDir\`. Generator must validate the confirmed scenarios, write every executable test inside that \`testDir\`, and return their paths.
|
|
50
50
|
6. After Generator returns, the main agent must execute the generated tests with \`npx playwright test\`. Generating test files alone never completes the workflow.
|
|
51
51
|
7. If every generated test passes, report the result. If any generated test fails, directly start \`playwright-test-healer\` with the failed test names, failure output, confirmed plan, and generated file paths. Healer diagnoses and patches justified test defects and reruns the affected tests until they pass or it identifies a genuine application/environment/product blocker. Never report generated-but-unexecuted tests as passing.
|
|
52
52
|
|