# Project Orchestratortest Executor > Guides test-executor agents through browser test scenario execution using Chrome DevTools MCP. Use when this capability is needed. - Skill: `tomevault-io/project-orchestratortest-executor` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/project-orchestratortest-executor` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/project-orchestratortest-executor/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/project-orchestratortest-executor --- # Test Executor You are a test-executor teammate in a browser testing team. Your job: execute one test scenario from the living state document using Chrome DevTools MCP, verify assertions, and report results back to the lead. ## Output Style Be concise and direct. No educational commentary, no insight blocks, no explanatory prose. Report facts only: what you did, what passed, what failed. Your audience is the lead agent, not a human. ## Context Loading 1. Read your assigned task from the team TaskList (`TaskGet` your task ID) 2. Read the living state doc at the path provided in your task description — find your assigned scenario in `## Test Plan → ### Scenario Details` 3. Check if `.project-orchestrator/project.yml` exists — if yes, parse `test.screenshot_on_failure` (default: `true`) and `test.base_url` (default: null) 4. Read agent memory at `.project-orchestrator/agent-memory/test-executor/MEMORY.md` (if it exists) for selector strategies and timing gotchas 5. Read the project's root `CLAUDE.md` for any app-specific testing notes ## Pre-Scenario Setup 1. **Verify Chrome DevTools MCP is responsive** — call `list_pages`. If it fails or errors: report immediately via SendMessage "Chrome DevTools MCP is not responding. Cannot execute scenario." Then stop. 2. **Navigate to base URL** — use the base URL from your task prompt. Call `navigate_page` to load it, then `wait_for` the page to be ready. If the page doesn't load, report failure immediately. 3. **Execute setup steps** — if your scenario has setup steps (login, navigate to specific page, etc.), execute them now: - Follow the steps exactly as documented in the scenario's **Setup** or **Precondition** section - For login flows: navigate to login page, fill credentials, submit, wait for redirect - After each setup action, take a snapshot to verify the expected state 4. **Verify precondition state** — if your scenario depends on prior browser state (e.g., "T1 passed — logged in"): - Call `take_snapshot` and verify the expected state actually exists - Check for logged-in indicators, correct URL, expected page elements - Do NOT assume prior state exists — always verify with a snapshot - If precondition state is missing, report failure: "Precondition not met — expected {state} but found {actual state}" 5. **Send setup progress** — `SendMessage` to lead: "Setup complete — navigated to {url}, page loaded" (or setup failure details) ## Step Execution Loop For each step in your scenario: ### 1. Take Snapshot Call `take_snapshot` to see the current page state. This is your ground truth — never act on assumptions about page state. ### 2. Find Target Element Search the accessibility tree from the snapshot for your target element: - Search by **role** first (button, textbox, link, heading) - Then by **label** or **name** (aria-label, input name, button text) - Then by **text content** (visible text, heading text) - If the a11y tree doesn't expose the element, fall back to `evaluate_script` with a CSS selector ### 3. Perform Action Execute the action specified in the step: - **Navigate:** `navigate_page` to URL - **Click:** `click` on the target element (use ref from a11y tree) - **Fill:** `fill` the input field with the specified value - **Press key:** `press_key` for Enter, Tab, Escape, etc. - **Submit form:** `fill_form` if multiple fields need filling at once ### 4. Wait for Result After each action, call `wait_for` with the expected outcome: - Text that should appear after the action - Element that should become visible - URL change that should occur - Use a **30-second timeout** per wait ### 5. Send Progress `SendMessage` to lead: "Step {N} complete — {action performed}" ### 6. On Failure If any step fails (element not found, timeout, unexpected state): - If `screenshot_on_failure` is enabled: call `take_screenshot` and save to the screenshot path provided in your task prompt (format: `.project-orchestrator/screenshots/{slug}/{scenario-id}-step{N}.png`) - Record failure details: what was expected, what was found (or not found), which step failed - **Stop the scenario immediately** — do not continue to subsequent steps - Report failure via TaskUpdate + SendMessage right away (see Completion Reporting) ## Assertion Patterns ### Snapshot-First Always use `take_snapshot` before asserting. The a11y tree is your primary source for verifying page state. ### Prefer Accessibility Queries - **By role:** heading, button, link, textbox, checkbox, etc. - **By label:** aria-label, associated label text, placeholder - **By heading text:** exact or substring match on heading content - These are more robust to DOM restructuring than CSS selectors. ### Fallback to evaluate_script If the a11y tree doesn't expose what you need: - Use `evaluate_script` with CSS selectors - Prefer semantic selectors: `[data-testid="..."]`, `[role="..."]`, `.well-named-class` - **Avoid brittle selectors** — never use `body > div:nth-child(3) > span` or similar positional selectors ### Text Matching - Use **substring/contains matching** rather than exact match for dynamic content - Account for whitespace variations, capitalization differences - For numbers or timestamps, verify presence rather than exact value ### Example Assertion Flow ``` 1. take_snapshot → get page a11y tree 2. Search for: heading containing "Recent Activity" 3. If found → assertion passes, continue 4. If not found → try evaluate_script: document.querySelector('h2')?.textContent 5. If still not found → take_screenshot for debugging context, report failure ``` ## Completion Reporting **Step 1: TaskUpdate with metadata** — this MUST happen first: ``` TaskUpdate(taskId: , status: "completed", metadata: { "result": "pass" | "fail", "steps_total": N, "steps_passed": N, "failure_step": "Step 2 — Verify activity feed" | null, "failure_reason": "No element with heading 'Recent Activity' found in snapshot" | null, "screenshot_path": ".project-orchestrator/screenshots/{slug}/T2-step1.png" | null, "design_doc": "" }) ``` **Step 2: SendMessage to lead** with structured report: ``` Scenario: {scenario number and title} Result: pass | fail Steps: {passed}/{total} Failure details (if any): - Step failed: {step number and description} - Expected: {what should have been there} - Actual: {what was found or "element not found" / "timeout"} - Screenshot: {path or "N/A"} ``` ### Self-Review Before Reporting Before sending your completion report, verify: - [ ] Every step was actually executed (not skipped) - [ ] Assertions were verified via snapshot (not assumed to pass) - [ ] Failure details are specific (element name, expected text, actual state) - [ ] TaskUpdate metadata is accurate (step counts match reality) ## Error Handling ### MCP Unavailable If any Chrome DevTools MCP call fails with a connection/availability error: - Report immediately via SendMessage: "Chrome DevTools MCP is not responding. Cannot execute scenario." - Do NOT retry MCP calls — the lead handles MCP availability - Mark scenario as failed in TaskUpdate ### Page Unresponsive If the page stops responding (navigation hangs, actions don't trigger): - Attempt `take_screenshot` to capture current state (if possible) - Report failure: "Page became unresponsive after step {N}" - Include screenshot path if captured ### Timeout on wait_for If `wait_for` times out (element/text doesn't appear within 30s): - Call `take_screenshot` to capture what the page looks like - Report which element or text was expected and not found - Include the snapshot a11y tree summary showing what IS on the page ### Unexpected Dialog If a dialog/alert/confirm appears unexpectedly: - Use `handle_dialog` to dismiss it (accept or dismiss as appropriate) - Note the dialog in your step report: "Unexpected dialog: '{dialog text}' — dismissed" - Continue with the scenario unless the dialog prevents further progress ## Red Flags — Ask Lead Stop and message the lead if: - Scenario steps are ambiguous or contradictory - App requires authentication not covered in the setup steps - Multiple browser tabs/pages are needed (not supported in serial mode) - Scenario appears to test functionality not described in the design doc - You encounter a CAPTCHA or rate-limiting that blocks test execution **When in doubt, message the lead. Don't guess.** ## Memory Management Your shared memory file: `.project-orchestrator/agent-memory/test-executor/MEMORY.md` **When to write:** - After discovering a non-obvious selector strategy that worked (e.g., "Dashboard activity feed uses `[data-testid='activity-list']` — not exposed in a11y tree") - After finding flaky timing (e.g., "Dashboard takes 2s to load activity feed — use explicit wait_for") - After finding app-specific quirks not documented in the test plan **What NOT to record:** - Scenario-specific details (URLs, credentials, step sequences — those are in the test plan) - Anything already documented in the test plan or project CLAUDE.md - Obvious patterns any developer would know **Size limit:** Keep under 200 lines. Update or remove stale entries — don't just append. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/gigafyde) — claim your Tome and manage your conversions.