Browser test agent

What you'll build

Step-by-step build

1. 1

   Stand up Playwright

   Install Playwright and write a plain script that opens a page, clicks something, and takes a screenshot. Confirm the browser launches both headed and headless. This is the muscle the agent will control, so make sure it works before adding any model.

2. 2

   Wrap browser actions as tools

   Expose navigate, click, type, and wait as functions with Zod-validated arguments like a selector or text. Each tool performs one action and returns whether it worked. Keeping actions atomic lets the agent reason one step at a time.

3. 3

   Give the model the page state

   After each action, extract a compact view of the page, such as visible text and interactive elements, and pass it back to the model. Because the page changes with every action, the model must always decide from the current state, not a stale plan. This observe-then-act cycle is the core of the project.

4. 4

   Parse the flow into steps

   Prompt the model to turn the plain-English flow into an ordered list of intended steps. This gives the run a checklist to measure pass or fail against. Print the steps so you can confirm the agent understood the flow.

5. 5

   Run the act-and-observe loop

   For each step, let the model choose a browser tool, execute it, then read the new page state to decide if the step succeeded. Feed the result back before moving to the next step. Cap total actions so a lost agent cannot click forever.

6. 6

   Capture evidence per step

   Take a screenshot after every action and save it with the step name. Screenshots are the proof that turns a claimed pass into a verifiable one. Store them in a run folder the report can link to.

7. 7

   Report pass or fail honestly

   Mark each step passed only if the observed page state actually matches the intent, and fail it with a reason otherwise. Never let the model declare success it did not verify. Output a summary listing each step, its status, and its screenshot.

8. 8

   Run it headless in CI

   Add a GitHub Actions workflow that runs the agent headless against a deployed preview URL. Upload the screenshots and summary as build artifacts. Now the flow is checked automatically on every push instead of by hand.

Done when

• ✓A described flow runs end to end and each step gets a screenshot
• ✓A deliberately broken flow is reported as failed with a clear reason, not a false pass
• ✓The action loop always terminates within its cap
• ✓The run summary matches what the screenshots actually show
• ✓It runs headless in CI and uploads its evidence as artifacts

Ship it

The agent runs in GitHub Actions on the free tier, driving Playwright headless against a preview URL. Store the Groq key as an encrypted repo secret. Write a README with one example flow, the resulting screenshots, and instructions to add it to a project's CI.

What it proves: Shows you can connect a model to a stateful, changing environment and produce honest, evidence-backed pass-or-fail results.

Paste this into Cursor, Claude, or ChatGPT and build it step by step.

You are my senior AI engineer pair. Help me build "Browser test agent" step by step. An agent here is an LLM that loops over tools; tool-calling means it asks to run an action like click or type and I run it in a real browser and feed back the new page state. The browser is a stateful environment, so the model must observe then act each step.

Stack: Playwright driving real Chromium, Node.js and TypeScript, Vercel AI SDK 6 for the tool-calling loop, Groq API for inference, and GitHub Actions for headless CI runs.

Requirements:
1. Take a plain-English user flow and parse it into ordered steps.
2. Expose navigate, click, type, and wait as Zod-validated tools.
3. After each action, feed compact page state back so the model picks the next move.
4. Screenshot after every step and report pass or fail per step with a reason.
5. Run headless in CI against a preview URL and upload the evidence.

Work in this order: plain Playwright script, then browser tools, then page-state feedback, then flow parsing, then the act-and-observe loop, then screenshots, then honest reporting, then CI. Give me commands and code for each step and STOP after each so I can test. Do not write the whole app at once.