Guide · Agent skill
How to use the Browser Test Runner agent skill (ce-test-browser)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Browser Test Runner is an agent skill that checks the web pages affected by your current git branch or pull request in a real browser. It is for web developers who want a quick click-through of touched pages before opening a PR, and for teams running unattended pipelines. After this guide you will know how to install the skill, how to ask for a run in plain language, and what the report looks like.
Browser Test RunnerEveryInc/compound-engineering-plugin · MIT Download the skill Quick start
- 1Download and unzip. Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or .claude/skills/ inside one project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills instead.
- 2Check requirements. Confirm your project is a git repository with changes relative to main, and that bash and lsof are available. Install the gh CLI if you plan to use PR numbers.
- 3Start your dev server. Run your local web app so it is reachable on localhost. In manual mode the skill uses the port it resolves and does not scan for alternatives.
- 4Ask for a run. Tell the agent in plain language to run browser tests for the current change, or name a PR number or branch.
- 5Answer the headed or headless question. If the agent-browser fallback is in use in manual mode, choose headed to watch the browser or headless to run it in the background.
- 6Review the summary. Check each affected route marked Pass, Fail, or Skip. Read the reason for every Skip and the repro for every Fail.
What the skill makes the agent do
When the skill runs, the agent looks at the files changed relative to main on your current branch, or on a pull request you name. It works out which web pages those changes affect, opens your local dev server in a browser, and exercises each affected page.
Every affected page is reported as Pass, Fail, or Skip. A Skip always carries a reason. Pages that need real OAuth, email, payment, or SMS verification are logged as Skip or paused for a human.
Install the skill by downloading the ZIP
Download the skill ZIP from the page you are reading. Unzip it into one of two places:
Your personal skills folder, which applies to all your projects: ~/.claude/skills/
A single project's skills folder, which applies only to that repository: .claude/skills/ inside the project root.
If you use the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project: .claude/skills/
- Claude apps: Settings → Capabilities → Skills (upload the ZIP)
Check the requirements before the first run
The skill needs a git repository with changes relative to main, a running local dev server (or one the skill can start), bash, and lsof, which the port scan uses. If you give a PR number, the gh CLI must be installed so the skill can read the PR's changed files.
For the browser itself, the skill prefers a browser built into your agent's host app. If none is available, it falls back to a tool called agent-browser. If agent-browser is missing, the skill tells you to set it up and stops.
- git repository with changes relative to main
- gh CLI, only for PR-number scope
- lsof, used by the --free port scan
- bash
- A running local dev server, or one the skill can start
- agent-browser, only when no host-native browser is available
Trigger the skill with a natural request
You do not need a special command. Ask the agent in plain language to run or check browser tests for the current change. The skill's description matches requests like that.
You can also name the scope. The skill accepts a PR number, a branch name, the word current, or a --port PORT option, which the agent passes as an argument.
- "Run browser tests for the pages affected by my current branch."
- "Check the browser tests for PR 123."
- "Run browser tests on branch feature/login using port 4000."
How the skill chooses the dev server port
The skill's port script prints one port number. It checks, in order: an explicit port argument; a --port flag in a package.json dev or start script; a PORT= line in .env, .env.local, or .env.development; and finally 3000.
In manual mode the port is used as-is, because you control your own server. In pipeline mode the skill may pick a free port and start the server itself.
scripts/resolve-port.shManual and pipeline modes
Manual is the default. You control the dev server. When the fallback agent-browser driver is used, the agent asks whether to run the browser headed (visible) or headless.
Pipeline mode is for runners such as LFG, invoked with mode:pipeline. The run is unattended: the agent never stops to ask a question. It runs agent-browser headless, logs flows that need human verification as Skip, logs failures, and continues.
- Manual: you run the server; agent-browser asks headed or headless
- Pipeline: unattended; headless; Skip and log instead of asking
Read the report
The run ends with a summary listing every affected route as Pass, Fail, or Skip, with a reason for each Skip. If a preflight problem stops testing before any route is exercised, the report names the blocker and what would clear it. Failures include the error state and an exact repro.
What people use it for
- Click through the pages touched by a feature branch before opening a pull request.
- Check the pages changed in a teammate's PR by passing its PR number.
- Run unattended in a pipeline that tests changed pages and logs results without stopping for questions.
- Record which flows were skipped because they need OAuth, email, payment, or SMS verification.
Frequently asked questions
How do I install the ce-test-browser skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for all your projects, or into .claude/skills/ inside one project. In the Claude apps you can upload the ZIP under Settings → Capabilities → Skills.
What does the browser test skill require?
It requires a git repository with changes relative to main, bash, lsof for the port scan, and a running local dev server or one the skill can start. The gh CLI is needed only for PR-number scope, and agent-browser is needed only when no host-native browser is available.
Is the Browser Test Runner skill free?
The skill is published under the MIT licence, as stated on its source page. Check the repository licence file for the full terms.
What are the alternatives to this skill?
This page does not compare it with other tools. The skill is designed not to substitute other browser automation stacks such as standalone Playwright or Puppeteer, so you would use those separately if you need them.
Why does the skill skip some pages?
Flows that need real OAuth, email, payment, or SMS verification are logged as Skip with a reason in pipeline mode, or the agent pauses for a human in manual mode. Pages the skill cannot reach are also reported rather than dropped.
What if the agent-browser tool is not installed?
The skill tells you that agent-browser is not installed, points you to the ce-setup skill for the current install command, and stops. An installed discovery skill does not mean the CLI or its browser runtime is installed.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you build a web front end with a local dev server and want a fast, reported browser check of pages touched by your current branch or PR. Skip it if your project has no web pages or dev server to open, or if your key flows depend on live OAuth, email, payment, or SMS checks that an automated run cannot complete.
Download the skill