openqa-labs/openqa

1. What this repository is

OpenQA is a Node.js package that combines three things in one repo: an agent runtime for browser testing, a CLI that scaffolds test harnesses, and generators/templates for multiple test styles. The core value proposition is that tests are written in natural language while Playwright still executes the browser actions.

2. Primary runtime boundary

The main execution boundary is between the test process and the agent process. User-authored BDD/YAML test code calls into openqa, and OpenQA spins up an in-process Playwright MCP server exposed over localhost HTTP/SSE. The AI provider SDK then connects to that MCP endpoint and drives the browser through MCP tools.

3. Core library entry point

src/index.js is the package surface area. It likely re-exports the agent runtime, provider factories, and YAML utilities so consumers can use OpenQA from step definitions or generated tests without reaching into internal files.

4. Agent subsystem

src/agent/ contains the orchestration layer:

- Orchestrator.js coordinates the overall agent run.

- SessionManager.js preserves conversation state per browser context so a scenario can continue across multiple steps.

- Logger.js handles verbose step-by-step output and secret redaction.

- createMcpServer.js creates the Playwright MCP server that the AI client talks to.

- systemPrompt.js defines the instruction set given to the model.

This is the heart of the “natural language to browser actions” flow.

5. Provider adapters

src/agent/providers/claudeCode.js and src/agent/providers/openCode.js are the integration boundary to external AI tooling. They wrap two different provider ecosystems:

- Claude Code SDK

- OpenCode SDK

The repo treats model/provider choice as a thin adapter layer, while the rest of OpenQA stays provider-agnostic.

6. Browser execution model

The agent does not talk to a fake browser API; it drives the real Playwright page or browser context that the test already owns. The README’s flow shows the step definition passing page or context into runAgent(...), which then routes browser actions through MCP tools like navigation and clicking. This shared-browser design is central to the architecture.

7. CLI and scaffolding subsystem

src/cli/ is responsible for project setup:

- bin.js is the command-line entry.

- init.js creates a new .openqa/ harness in a target project.

- generate.js supports generation tasks.

The CLI is not the test runner itself; it prepares a runnable harness that sits alongside the user’s project.

8. Template-driven project layout

src/cli/templates/ contains complete starter harnesses for three execution styles:

- playwright-bdd

- cucumber

- playwright-yaml

These templates include feature files, step definitions, Playwright config, package manifests, and env schema files. openqa init copies one of these templates into the user project, making the generated .openqa/ folder the user-editable boundary.

9. YAML test pipeline

src/yaml/ is the alternate test authoring path. schema.js defines the structure of the YAML test format, and generator.js turns YAML specs into executable test artifacts. This subsystem exists alongside BDD support and is exposed via the YAML template and example project.

10. Examples as integration references

examples/ demonstrates the three supported styles end-to-end:

- examples/playwright-bdd

- examples/cucumberjs

- examples/playwright-yaml

These are not just demos; they show the intended dependency graph between generated harness, Playwright config, feature/spec files, and the OpenQA runtime.

11. Docs and release tooling

docs/ is the product documentation site, while .github/workflows/release.yml handles publishing automation. These do not affect runtime architecture, but they define how the package is documented and shipped.

12. Overall data flow

The dominant flow is: user-authored feature/YAML step → OpenQA agent API → MCP server creation → provider SDK connection → Playwright browser actions → test assertion/result. The scaffolding flow is separate: CLI init → template copy → user edits generated harness → test runner executes against the core agent runtime.