WebSpec

Browser automation for the agent era. Describe a web flow in plain language — your AI agent writes the spec and runs it.

WebSpec is a YAML-spec + Playwright runtime designed to be driven by AI agents (Claude Code, Codex, OpenCode). You almost never touch the YAML.

How it works

You:   /webspec:draft "test that login shows an error on bad credentials"
Agent: Drafting spec...
       ✓ tests/specs/login-error.spec.yaml written

You:   /webspec:run tests/specs/login-error.spec.yaml
Agent: Running spec against https://app.example.com ...
       ✓ navigate /login
       ✓ fill Email — [email protected]
       ✓ fill Password — wrongpassword
       ✓ click Sign in
       ✓ assertVisible "Invalid email or password"
       Passed in 1.3s

Quick start

Install globally:

npm install -g @nicoavanzdev/webspec
playwright install chromium

Initialise a project:

cd your-project
webspec init

Install agent harness files (SKILL.md + slash commands):

webspec install

Then tell your agent: /webspec:draft "describe the flow you want to test"

Agent setup

webspec install writes everything your AI agent needs into the repo — a reference guide and four slash commands — for whichever harnesses you choose:

| Harness | Slash commands | |---------|---------------| | Claude Code | /webspec:draft /webspec:run /webspec:validate /webspec:inspect | | OpenCode | /webspec-draft /webspec-run /webspec-validate /webspec-inspect | | Codex | webspec-draft webspec-run webspec-validate webspec-inspect |

Non-interactive install:

webspec install --tools all                  # all harnesses
webspec install --tools claude,opencode      # specific harnesses

Slash commands

| Command | What it does | |---------|-------------| | /webspec:draft | Draft a new spec from a plain-language description | | /webspec:run | Run a spec against a browser | | /webspec:validate | Validate a spec for schema and syntax errors | | /webspec:inspect | Inspect a live URL and suggest a spec |

What the agent writes

Specs are YAML files that the agent generates — you read them for review, not to author them.

name: Login error on bad credentials
baseUrl: https://app.example.com
env:
  PASSWORD: ${TEST_PASSWORD}

steps:
  - navigate: /login
  - fill:
      label: Email
      value: [email protected]
  - fill:
      label: Password
      value: wrongpassword
  - click:
      role: button
      name: Sign in
  - assertVisible:
      text: Invalid email or password

See docs/spec-format.md for the full format reference.

CLI reference

webspec install   Install agent harness files into this repo
webspec init      Scaffold project config and example spec
webspec run       Run one or more specs
webspec validate  Validate specs without running
webspec inspect   Inspect a URL and suggest a spec
webspec generate  Write a spec file from YAML content (agent-facing)
webspec doctor    Check Playwright and environment
webspec archive   Archive a spec with its metadata

See docs/cli.md for full documentation.

Web-only

WebSpec automates browsers via Playwright. It does not support native mobile apps (iOS, Android, React Native). The agent harness is trained to refuse mobile requests and explain why.

Docs

• Getting started / agent setup
• Spec format reference
• CLI reference
• Configuration
• Examples
• Limitations

License

MIT