microsoft--webwright/skills/webwright/reference/workflow.md

Workflow

Detailed expansion of the six-step Webwright loop, adapted for Claude Code. The original loop relied on webwright.tools.image_qa for visual QA and webwright.tools.self_reflection for the final verdict. Both are replaced here by your native abilities (Read on PNG files + reasoning against plan.md). No OPENAI_API_KEY is required.

1. Plan

Parse the task into critical points (CPs) and write WORKSPACE_DIR/plan.md:

# Task
<verbatim task description>

# Critical Points
- [ ] CP1: <constraint / filter / sort / selection / required datum>
- [ ] CP2: ...

Rules for CPs:

• One CP per independently verifiable requirement.
• Numeric, date, quantity, and unit CPs must be exact.
• Ranking CPs ("cheapest", "best-selling", "highest-rated", …) must reference the site's actual sort/filter control.
• If the task asks for a final datum, make it its own CP (e.g. CP5: Record the displayed cheapest economy fare).

2. Explore

Goal: discover stable selectors, confirm every required filter control exists, and identify how to capture evidence for each CP.

• Run scratch Playwright scripts (see playwright_patterns.md) inside WORKSPACE_DIR/. Save scratch PNGs under WORKSPACE_DIR/screenshots/ (separate from final_runs/).
• Print URL, title, and aria_snapshot() for the region of interest at every step.
• Use Read on saved PNGs to confirm UI state when ARIA evidence is ambiguous.
• If a filter looks unavailable, expand drawers / accordions / mobile filter panels and inspect again before concluding it doesn't exist.
• A search-box query never substitutes for a dedicated filter control.

3. Author final_script.py

Create a fresh final_runs/run_<id>/ (use the next integer above any existing run_*) and place final_script.py inside it. Instrument per playwright_patterns.md:

• viewport 1280×1800, headless local Firefox, no full_page;
• one final_execution_<step>_<action>.png per CP;
• one step <n> action: <reason and action> log line per constraint-relevant interaction;
• the final datum printed into final_script_log.txt at the end.

Each screenshot should map to a CP from plan.md so verification is trivial.

4. Execute

Run the script once. If it crashes, fix it inside the same run folder and re-execute — but if a partial run already produced screenshots that don't match the fixed flow, delete them so the run folder reflects a single clean execution.

5. Self-verify (replaces self_reflection)

For every CP in plan.md:

1. Identify the screenshot(s) and/or log line that provide evidence.
2. Read each cited PNG.
3. Confirm the evidence is unambiguous:
   • Filter chip / selected state visibly applied (not hidden behind a closed drawer);
   • Numeric / date values match exactly (not broadened);
   • Sort applied via the site's control (not implied by result order);
   • Required submit / search / apply action visibly taken;
   • Final datum legibly displayed.
4. Tick the CP only when the evidence is concrete. Be harsh on partial, occluded, or ambiguous states.

If any CP fails, diagnose the specific issue — wrong filter value, missing control, hidden chip, broadened range, missing confirmation, missing screenshot, etc. Fix final_script.py, run it again inside final_runs/run_<id+1>/, and re-verify against plan.md.

Empty result sets are acceptable when the correct filters were demonstrably applied.

6. Done

Stop only when all of the following are true:

1. plan.md exists with every CP enumerated as a checklist item.
2. final_runs/run_<id>/final_script.py ran cleanly from scratch and produced final_script_log.txt plus all CP screenshots.
3. Every CP is checked off with a cited screenshot and/or log line.
4. The final datum (if the task asked for one) is reported to the user verbatim and is also present in final_script_log.txt.
5. ls -R final_runs/run_<id> and cat final_runs/run_<id>/final_script_log.txt show the expected artifacts.

If any of those is false, do not declare done — diagnose, fix, and re-run in a new run_<id+1>/.