CodexQA Jev Browser

Drive a real browser through the codexqa-jev-browser CLI (TypeScript). Do not invent CSS/XPath/coordinates or replace the engine with a host browser tool.

Choose a mode

1. Existing YAML, Markdown, or API cases → run
2. Only a natural-language goal → auto or generate
3. Unknown site / coverage → explore

Install once, from this skill directory (the directory that contains package.json and SKILL.md):

npm install

Playwright Chromium is the browser. Do not read another application's browser profile.

Commands

npx codexqa-jev-browser observe <url-or-local-html>
npx codexqa-jev-browser run cases/examples/search-docs.yaml
npx codexqa-jev-browser run cases/examples/search-docs.md
npx codexqa-jev-browser run --from-api https://qa.example.com/cases?suite=smoke
npx codexqa-jev-browser auto --url <url> --goal '<goal>'
npx codexqa-jev-browser generate --url <url> --goal '<goal>' --out generated/case.yaml --md --verify
npx codexqa-jev-browser explore --url <url> --out generated/explore

The browser window is shown by default. Set browser.headless: true to hide it. --headed forces a visible window. --no-screenshots skips images.

Model setup

Do this before live auto / generate --goal. The CLI calls Jev or an OpenAI-compatible API itself. The host Cursor/Codex session model is not the decision model. observe, run, explore, and --decisions do not need a key. Do not stop those commands to ask for one.

Keys live in a .env file, not in the chat. The CLI loads the .env next to this SKILL.md first, then a repo-root .env, and does not override variables already set in the shell.

1. Read that .env (or .env.example if .env is missing). If TYPESAFE_API_KEY or OPENAI_API_KEY is already set, run the command. Do not ask again.
2. If neither key is set, copy .env.example to .env in the skill directory and tell the user to fill that file. Do not ask them to paste a key into the chat. Show this shape:

# Each step: which control, which goal phrase to type, whether the step worked, whether the task is done.
TYPESAFE_API_KEY=
TYPESAFE_MODEL=jev-latest
TYPESAFE_BASE_URL=https://api.typesafe.ai/v1

# Task plan before the browser opens. Also the decision and the done check when TYPESAFE_API_KEY is empty.
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
TEXT_MODEL=gpt-4o-mini

3. Prefer Jev when TYPESAFE_API_KEY is set. OPENAI_MODEL is only the planner unless Jev is unset. A third-party gateway is OPENAI_BASE_URL or TYPESAFE_BASE_URL, not a separate product. Set HTTPS_PROXY in the same .env only when that gateway needs a proxy.
4. generate writes the YAML after every successful step. Do not hand-author the case step by step while the run is walking the site.
5. Never write a key into case YAML. Never commit .env.

Optional CLI overrides (never --api-key): --model, --base-url, --config. Model name and gateway may also live in codexqa-jev-browser.config.yaml as ${OPENAI_API_KEY}-style placeholders.

After every run

Open or summarize reports/<run-id>/report.html before concluding. It contains suite totals, every step, and screenshots. Exit code is non-zero on failure. report.json is the machine-readable copy; report.md is the short summary.

Hard rules

• Model output may only choose an operation plus an observed index. Never execute model-written selectors, JS, or shell.
• DONE is not success. Assertions or visible evidence decide the result.
• READ records a control Jev already sees. The control name is the fact, such as a product and its price. Jev chooses that index. It does not click, type, or ask another model to write the price. A price that is not the name of a visible control is not recorded. When the goal asks to read, list, or report those facts, READ has to record them before DONE. Text drawn only as an image is not copied.
• Secrets stay in environment variables (${PASSWORD}), never in case files.
• Confirm before explore/auto on logout, delete, pay, or other destructive controls.
• Prefer semantic targets: {role, name, nth, within}.

Business knowledge

Per-app notes live in knowledge/<app>/*.md. On live auto / generate --goal, the CLI matches the start URL and the goal against each note's hosts and keywords, then appends the hits to the planner, the decision goal, and the field-text prompt. A note with general: true is included on every run.

Notes are reference for what to type and which visible control to prefer. They do not add operations. Do not copy them into case YAML. Add a new app by adding a note. Do not put that app's fill rules back into src/policy.ts.

A failed auto or generate writes reports/<run-id>/knowledge-draft.md when the failed step names a control. The draft is not active until a person runs npx codexqa-jev-browser knowledge-accept <draft>. That copies it into knowledge/<app>/. Do not accept a draft that names a secret or invents a selector.

Case sources

• YAML is the source of truth. Markdown uses numbered Click/Type/Select/Scroll/Wait/Assert/HTTP lines.
• --from-api pulls cases; steps may also use op: http for setup or backend checks.

Schema and verbs: references/schema.md. Examples: references/examples.md.