Playwright BDD Agents — Kilo Code (fixed build)

A Playwright + Cucumber BDD TypeScript framework driven by five agents — planner, generator, healer, reviewer, runner — for VS Code Copilot, Claude Code, OpenCode, and Kilo Code.

Install into any project (npm CLI)

Like npx playwright init-agents --loop=vscode, this package ships an init command that scaffolds the agents into your project in the layout each tool expects. Pick your tool with --loop:

npx playwright-bdd-agents init --loop=vscode      # VS Code Chat (GitHub Copilot)
npx playwright-bdd-agents init --loop=claude      # Claude Code
npx playwright-bdd-agents init --loop=opencode    # OpenCode
npx playwright-bdd-agents init --loop=kilo        # Kilo Code
npx playwright-bdd-agents init --loop=all         # all four at once

Each loop drops only the files that tool reads, plus the Playwright CLI skill in that tool's location and a runnable framework skeleton (src/, playwright.config.ts, cucumber.json, …):

| --loop | Tool | Files written | |---|---|---| | vscode | VS Code Chat (Copilot) | .github/agents/*.agent.md, .github/copilot-instructions.md, skills/playwright-cli/SKILL.md | | claude | Claude Code | .claude/commands/*.md, .claude/skills/playwright-cli/SKILL.md, CLAUDE.md | | opencode | OpenCode | prompts/*.md, opencode.json, skills/playwright-cli/SKILL.md | | kilo | Kilo Code | .kilo/**, kilo.jsonc, skills/playwright-cli/SKILL.md |

Options: --force overwrite existing files · --no-shared agents only (skip the framework skeleton) · --dry-run preview · --list show loops · --help. Existing files are skipped (never clobbered) unless you pass --force, and your package.json is preserved if you already have one. Then:

npm install && npx playwright install   # deps + browser binaries
cp .env.example .env                    # set BASE_URL etc.

What's fixed in this build

• No more Cannot find module 'dotenv' (TS2307) — the scaffolder now writes dotenv into the generated package.json dependencies, and hooks.ts loads it through a guarded require so the type-check passes even before npm install. This applies to every loop (vscode / claude / opencode / kilo).
• Cleaner scaffold — removed leftover project-specific artifacts (the SurvivalCon lantern/offer checkout feature, page object, and steps) and dev-only docs so init drops only the generic framework + a single example.
• Success banner — after init finishes, the CLI prints a Playwright mask and "Hurray, you are good to go to use the agent!" so you know the scaffold succeeded.
• Agents now show up in Kilo Code — defined as .md files in .kilo/agents/ (Kilo's required format). The original project only had Claude Code / OpenCode / Copilot configs, which Kilo doesn't read.
• cucumber.json runs your tests — added the missing paths key. Without it you get 0 scenarios / 0 steps. Written without a BOM.
• No more Unexpected token BOM error — agents are instructed never to write JSON with PowerShell Set-Content (it injects a UTF-8 BOM that breaks JSON.parse).
• Runs with zero extra deps — hooks.ts no longer imports allure-cucumberjs (that was the "allure is not installed" error). Screenshots on failure go to reports/screenshots/. Allure is now opt-in.
• Real locators, not guesses — the Playwright CLI skill is pre-installed for every tool. Agents drive the live page (playwright-cli open --headed → goto → snapshot) and read one exact locator per step before writing any code.
• Runnable framework files added — package.json, tsconfig.json, playwright.config.ts, .env.example, .gitignore.

Setup

# 1. Open this folder as the workspace root in VS Code
# 2. Install dependencies
npm install
npx playwright install        # download browser binaries

# 3. Configure your environment
cp .env.example .env          # then edit BASE_URL etc.

Using the agents in VS Code Chat (built-in GitHub Copilot)

The five agents are now native custom agents for VS Code's built-in Copilot Chat — no extension build and no API key required.

1. Open this folder as the workspace root in VS Code (Copilot Chat enabled).
2. Open the Chat view and click the agent dropdown (next to Ask / Edit / Agent).
3. Pick Planner, Generator, Healer, Reviewer, or Runner. If they don't appear, run Developer: Reload Window, or Chat: Configure Chat > Modes to confirm they're detected.
4. Shared rules load automatically from .github/copilot-instructions.md; each agent adds its own role on top. Handoff buttons chain them (Planner → Generator → Runner, Reviewer → Healer).

These live in .github/agents/*.agent.md (the current VS Code "custom agents" format, which replaced .chatmode.md). VS Code reads any .md in .github/agents/ as an agent. On older VS Code builds that still use chat modes, copy them into .github/chatmodes/ and rename to *.chatmode.md — the body is identical.

Plans are saved for reuse (plans/)

Whenever the Planner designs a strategy or the Reviewer produces an automation plan, it's written to the plans/ folder as a Markdown file you can reuse or modify:

• Planner → plans/<feature-name>.md
• Reviewer → plans/<target-name>-automation-plan.md

This behaves the same across all tools — VS Code Copilot, the extension, Claude Code, Kilo Code, and OpenCode. Point the Generator at any plans/*.md to build the tests from it later. See plans/README.md for details.

Reviewing any codebase

Import this folder into another repo and switch to the Reviewer. It audits the file(s) or directory you @-mention for quality, security, and optimisation (hardcoded secrets, injection, insecure transport, N+1 calls, blocking I/O, dead code, and more), reports findings by severity, and then writes a test automation plan for that codebase into plans/.

The Playwright CLI skill is wired into every tool

So that any agent can read the real page and emit actual locators from a URL, the Playwright CLI skill (playwright-cli) is dropped into every toolchain — in the location each tool reads skills/instructions from:

| Tool | Skill location | |---|---| | Kilo Code | skills/playwright-cli/SKILL.md (referenced by .kilo/agents/*) | | Claude Code | .claude/skills/playwright-cli/SKILL.md | | OpenCode | skills/playwright-cli/SKILL.md (referenced by prompts/*) | | VS Code Copilot agents | skills/playwright-cli/SKILL.md (referenced by .github/copilot-instructions.md) |

First-run notes:

• Install the CLI once: npm install -g @playwright/cli@latest (or rely on the bundled devDependency and call npx playwright-cli …). Run npx playwright install so the browser binaries exist.
• The agents drive the live page with playwright-cli open --headed → goto <url> → snapshot, walk the flow one step at a time, and record one exact locator per step. The browser opens headed by default so you can watch; pass --headless only if you ask for it.
• No MCP server, approval prompt, or per-tool MCP config is needed any more.

Getting one exact locator per element (URL + context → verified Locator Map)

You can hand an agent a URL plus some context and get a test plan where every element has one exact, verified locator — but only because the agent reads the live page, not because it guesses from the URL. Guessing from a URL string produces locators that break; this framework is built to avoid that.

Workflow:

1. Planner (optional) — give it the feature + URL. It reads the live page with the Playwright CLI skill and writes the scenarios plus a Step → Locator table (one exact locator per step) to plans/<name>.md.

2. Generator — give it the URL. Using the Playwright CLI skill it runs playwright-cli open --headed → goto <url> → snapshot, walks the flow one step at a time, enumerates every element, and writes a Locator Map to plans/<name>-locators.md:

   | Step | Element | Role | Accessible name | Primary locator | Fallback | Confidence | |---|---|---|---|---|---|---|

   Each locator is verified (read from the live page) or guessed (flagged // TODO: verify). Ambiguous matches are scoped; elements with no stable locator are flagged with a recommendation to add a data-testid. It then builds the page objects from this map.

3. Re-snapshot after every navigation — refs go stale. Confirm a ref with playwright-cli eval "el => el.outerHTML" eX, and playwright-cli close when done.

Example prompt to the Generator:

Navigate to https://your-site.com/checkout, snapshot the page with the Playwright CLI skill, and build a verified Locator Map for every field, button, and message in the checkout flow, then generate the page object and steps from it.

Reality check: "100% exact" is achievable only for elements the agent can actually see on the live page. Anything it cannot reach (auth-walled, dynamic, or rendered only after data loads) is marked guessed and called out — it is never silently invented.

Using the agents in Kilo Code

1. Open the agent dropdown (currently shows Agent / Ask / Plan).
2. If the five agents aren't listed: Ctrl+Shift+P -> Developer: Reload Window.
3. Typical flow: planner -> generator -> runner; use healer when a locator breaks and reviewer before merging.

Getting accurate locators

The agents cannot guarantee correct locators from a URL alone — they must read the real page, which they do with the Playwright CLI skill (skills/playwright-cli/SKILL.md).

Primary — Playwright CLI skill (the agent inspects the page itself):

playwright-cli open --headed     # visible window so you can watch (default)
playwright-cli goto https://your-site.com/login
playwright-cli snapshot          # fresh refs from the real accessibility tree
playwright-cli close

Prompt the generator: "Navigate to /login, snapshot the page, and build the page object from the real accessibility tree." Install once with npm i -g @playwright/cli@latest (or use npx playwright-cli).

Manual fallback — codegen (if you can't let the agent drive the browser):

npm run codegen -- https://your-site.com/login

A browser opens, you click through the flow, Playwright writes the real locators. Paste them to the generator.

Running tests

npm test                       # all scenarios
npm run test:smoke             # @smoke only
npm run test:regression        # @regression only
npm run typecheck              # tsc --noEmit

HTML report: reports/cucumber/report.html

Your Ollama Cloud model

kilo.jsonc registers gemma4:31b-cloud with explicit context limits (fixes the cloud-model context error) and tool_call: true (agents need tool calling). To use a stronger model for just the heavy agents, add model: anthropic/claude-sonnet-4-6 to the frontmatter of .kilo/agents/generator.md and healer.md.

Other tools (optional)

• Claude Code — CLAUDE.md + .claude/commands/*.md, slash commands /plan /generate ...
• OpenCode — opencode.json + prompts/*.md, e.g. opencode --agent planner "..."

Structure

playwright-bdd-agent/
├── bin/
│   ├── cli.js             <- `playwright-bdd-agents init --loop=<tool>` scaffolder
│   └── templates/gitignore
├── .github/
│   ├── agents/            <- VS Code Copilot agents: planner, generator, healer, reviewer, runner (*.agent.md)
│   └── copilot-instructions.md  <- shared "framework brain" auto-loaded by all Copilot chats
├── .claude/
│   ├── commands/          <- Claude Code slash commands /plan /generate /heal /review /run
│   └── skills/playwright-cli/SKILL.md  <- Playwright CLI skill (Claude Code)
├── .kilo/
│   ├── agents/            <- planner, generator, healer, reviewer, runner
│   └── workflows/codegen.md  <- capture step-level locators with the Playwright CLI skill
├── skills/
│   └── playwright-cli/SKILL.md  <- Playwright CLI skill (Copilot / OpenCode / Kilo agents)
├── plans/                 <- reusable plan + locator-map files (Planner + Reviewer + Generator write here)
├── kilo.jsonc             <- model + provider config (no MCP)
├── cucumber.json          <- has paths, no BOM
├── playwright.config.ts
├── tsconfig.json
├── package.json
├── .env.example
├── CLAUDE.md
├── opencode.json          <- OpenCode agents (no MCP block)
├── prompts/
└── src/