An agent explores the product. CI replays the path with no AI. A broken step is a named report. Your tools decide ticket or heal.

What it is · Start · Flows · Usage · CI · Architecture · Engineering

---

What it is

You can already ask an agent to click through a checkout. That works once. The next morning you want the same path on every commit, without paying for another model call, and without a test that dies the first time a designer changes a CSS id.

Today that usually means one of two dead ends:

• Chat browsers (most MCP tools). The agent looks at the page, clicks, and talks to you. Tomorrow you run the agent again. Every replay spends tokens. The path lives in a transcript, not in CI.
• Recorders (Playwright codegen, Selenium IDE, and friends). You get #txt_visit_date and .btn-primary. The next rename breaks the test. The log does not say "Login is gone." It says a selector missed. A person has to debug CSS.

BrowserEngine is the middle path.

The agent drives a real Chrome window and refers to controls the way a person would: "Username", "Login", "the Add to cart near Sauce Labs Backpack." Those visible names are what get saved, as ordinary JSON. CI then opens Chrome and follows the same names. No language model is in that run. No MCP session is required. The bill is the same as any other headless test.

When a step fails, CI gets a named report, not a dead CSS selector: step 2 click Login: two matches. --report writes JSON. --junit writes one testcase. This repo does not open tickets or push a heal. Everyone uses a different tracker and a different branch policy. Your next job (or an agent) reads the file and uses your tools.

That is what this repo is for: author with an agent, keep a file, replay without one, emit a report when it breaks. Headed while you watch, headless in CI. Same engine.

Modes

Mode	For	How
Headed (default)	Authoring and demos	Visible Chrome, cursor HUD, paced typing
Headless	CI and background	BROWSER_ENGINE_HEADED=0
MCP stdio	A live agent in this process	npm start
MCP HTTP	A remote agent	npm start -- --http
CLI compile	Check a flow file, no Chrome	node dist/cli.js compile path.json
CLI run	Replay a flow	node dist/cli.js run path.json
CI report	Machine file for any host	--json · --report out.json · --junit out.xml

Pace, type delay, expect timeout, and the work-area snap are all env-configurable. See usage.

---

Start

Requires Node.js >= 20.19.

git clone https://github.com/PremierStudio/BrowserEngine.git
cd BrowserEngine
npm install
npm run build

Check the checked-in fixture (compile does not open Chrome). The JSON is a schema example. https://example.com/login is not a real form, so do not run this file against the network.

node dist/cli.js compile tests/fixtures/login.flow.json

Replay your flow headless, and write a report:

$env:BROWSER_ENGINE_HEADED='0'
node dist/cli.js run flows/your.flow.json --report reports/flow.json --junit reports/flow.xml

A failure names the step (step 2 click: no target ...) and the same facts land in the report file. Paste-ready GitHub, GitLab, Forgejo, and Bitbucket jobs: CI.

Give an agent the same engine over MCP:

npm start

Point the client at node dist/cli.js. Prefer one run_flow over observe-per-page. Full tool list, desk controls, and env vars: usage.

---

Flows

Click and navigate must declare expectUrl or expectText. Type, hover, scroll, select, and press do not.

{
  "version": 1,
  "name": "login",
  "origin": "https://example.com",
  "steps": [
    {
      "action": "navigate",
      "url": "https://example.com/login",
      "expectText": "Username"
    },
    { "action": "type", "name": "Username", "text": "tomsmith" },
    {
      "action": "click",
      "name": "Login",
      "role": "button",
      "expectText": "Logout"
    }
  ]
}

Author with run_flow until every bind is unique, write the JSON (no uids), then compile / run in CI. Any host can fail the job on exit code 1. Pass --report / --junit for a machine file your next job (or an agent) can read. Paste-ready GitHub, GitLab, Forgejo, and Bitbucket jobs: CI.

---

Docs

Doc	What is in it
Usage	MCP, desk/page/intent tools, env, public-site demos
CI	compile / run on GitHub, GitLab, Forgejo, Bitbucket
Architecture	Engine, clients, page model, what is not in this repo
Engineering	npm run ci, 100/100 gates, stack
decisions.md	Settled engineering decisions

---

Contributing

AGENTS.md and docs/engineering.md. Failing test first. No merge below 100% coverage and 100% mutation. TypeScript only.

License

Apache License 2.0 © Premier Studio. See LICENSE.