# openqa-labs/openqa architecture

> Architecture diagram of the GitHub repository openqa-labs/openqa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openqa-labs/openqa
- Repository: https://github.com/openqa-labs/openqa

## Overview

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.

Main entry points: [`src/agent/Orchestrator.js`](https://github.com/openqa-labs/openqa/blob/main/src/agent/Orchestrator.js) (Orchestrator), [`src/index.js`](https://github.com/openqa-labs/openqa/blob/main/src/index.js) (Package API), [`examples`](https://github.com/openqa-labs/openqa/tree/main/examples) (Examples), [`src/cli/templates`](https://github.com/openqa-labs/openqa/tree/main/src/cli/templates) (Templates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_src_index["Package API<br/>entry surface<br/>[index.js]"]
  node_agent_index["Agent API<br/>module entry<br/>[index.js]"]
  node_orchestrator["Orchestrator<br/>runtime coordinator<br/>[Orchestrator.js]"]
  node_session_manager["Session state<br/>conversation state<br/>[SessionManager.js]"]
  node_logger["Logger<br/>step logging<br/>[Logger.js]"]
  node_mcp_server["MCP server<br/>browser bridge<br/>[createMcpServer.js]"]
  node_system_prompt["System prompt<br/>model instructions<br/>[systemPrompt.js]"]
  node_providers["Provider adapters<br/>ai integrations"]
  node_claude_adapter["Claude Code<br/>provider adapter<br/>[claudeCode.js]"]
  node_opencode_adapter["OpenCode<br/>provider adapter<br/>[openCode.js]"]
end

subgraph group_cli["CLI scaffolding"]
  node_cli_bin["CLI entry<br/>command entry<br/>[bin.js]"]
  node_init_cmd["Init command<br/>scaffolder<br/>[init.js]"]
  node_generate_cmd["Generate command<br/>generator command<br/>[generate.js]"]
  node_template_suite["Templates<br/>starter layouts"]
  node_template_bdd["BDD template<br/>starter template"]
  node_template_cucumber["Cucumber template<br/>starter template"]
  node_template_yaml["YAML template<br/>starter template"]
end

subgraph group_yaml["YAML pipeline"]
  node_yaml_schema["YAML schema<br/>spec schema<br/>[schema.js]"]
  node_yaml_generator["YAML generator<br/>artifact generator<br/>[generator.js]"]
end

subgraph group_delivery["Docs & release"]
  node_docs["Docs site<br/>documentation"]
  node_release["Release workflow<br/>publishing automation<br/>[release.yml]"]
end

node_examples["Examples<br/>reference projects"]

node_src_index -->|"re-exports"| node_agent_index
node_src_index -->|"exposes"| node_cli_bin
node_agent_index -->|"uses"| node_orchestrator
node_orchestrator -->|"tracks"| node_session_manager
node_orchestrator -->|"logs"| node_logger
node_orchestrator -->|"spins up"| node_mcp_server
node_orchestrator -->|"instructs"| node_system_prompt
node_orchestrator -->|"delegates to"| node_providers
node_providers -->|"includes"| node_claude_adapter
node_providers -->|"includes"| node_opencode_adapter
node_claude_adapter -->|"connects"| node_mcp_server
node_opencode_adapter -->|"connects"| node_mcp_server
node_cli_bin -->|"dispatches"| node_init_cmd
node_cli_bin -->|"dispatches"| node_generate_cmd
node_init_cmd -->|"copies"| node_template_suite
node_template_suite -->|"contains"| node_template_bdd
node_template_suite -->|"contains"| node_template_cucumber
node_template_suite -->|"contains"| node_template_yaml
node_template_yaml -->|"aligns with"| node_yaml_schema
node_template_yaml -->|"uses"| node_yaml_generator
node_yaml_generator -->|"validates against"| node_yaml_schema
node_examples -->|"exercise"| node_src_index
node_examples -.->|"mirror"| node_template_bdd
node_examples -.->|"mirror"| node_template_cucumber
node_examples -.->|"mirror"| node_template_yaml
node_docs -.->|"documents"| node_src_index
node_release -.->|"publishes"| node_src_index

click node_src_index "https://github.com/openqa-labs/openqa/blob/main/src/index.js"
click node_agent_index "https://github.com/openqa-labs/openqa/blob/main/src/agent/index.js"
click node_orchestrator "https://github.com/openqa-labs/openqa/blob/main/src/agent/Orchestrator.js"
click node_session_manager "https://github.com/openqa-labs/openqa/blob/main/src/agent/SessionManager.js"
click node_logger "https://github.com/openqa-labs/openqa/blob/main/src/agent/Logger.js"
click node_mcp_server "https://github.com/openqa-labs/openqa/blob/main/src/agent/createMcpServer.js"
click node_system_prompt "https://github.com/openqa-labs/openqa/blob/main/src/agent/systemPrompt.js"
click node_providers "https://github.com/openqa-labs/openqa/tree/main/src/agent/providers"
click node_claude_adapter "https://github.com/openqa-labs/openqa/blob/main/src/agent/providers/claudeCode.js"
click node_opencode_adapter "https://github.com/openqa-labs/openqa/blob/main/src/agent/providers/openCode.js"
click node_cli_bin "https://github.com/openqa-labs/openqa/blob/main/src/cli/bin.js"
click node_init_cmd "https://github.com/openqa-labs/openqa/blob/main/src/cli/init.js"
click node_generate_cmd "https://github.com/openqa-labs/openqa/blob/main/src/cli/generate.js"
click node_template_suite "https://github.com/openqa-labs/openqa/tree/main/src/cli/templates"
click node_template_bdd "https://github.com/openqa-labs/openqa/tree/main/src/cli/templates/playwright-bdd"
click node_template_cucumber "https://github.com/openqa-labs/openqa/tree/main/src/cli/templates/cucumber"
click node_template_yaml "https://github.com/openqa-labs/openqa/tree/main/src/cli/templates/playwright-yaml"
click node_yaml_schema "https://github.com/openqa-labs/openqa/blob/main/src/yaml/schema.js"
click node_yaml_generator "https://github.com/openqa-labs/openqa/blob/main/src/yaml/generator.js"
click node_examples "https://github.com/openqa-labs/openqa/tree/main/examples"
click node_docs "https://github.com/openqa-labs/openqa/tree/main/docs"
click node_release "https://github.com/openqa-labs/openqa/blob/main/.github/workflows/release.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_index,node_agent_index,node_orchestrator,node_session_manager,node_logger,node_mcp_server,node_system_prompt,node_providers,node_claude_adapter,node_opencode_adapter toneBlue
class node_cli_bin,node_init_cmd,node_generate_cmd,node_template_suite,node_template_bdd,node_template_cucumber,node_template_yaml toneAmber
class node_yaml_schema,node_yaml_generator toneMint
class node_docs,node_release toneRose
class node_examples toneNeutral
```

## Components

### Agent runtime

Natural-language browser execution over Playwright and MCP

- [Package API](https://github.com/openqa-labs/openqa/blob/main/src/index.js): entry surface · Main export surface for consumers · `src/index.js`
- [Agent API](https://github.com/openqa-labs/openqa/blob/main/src/agent/index.js): module entry · Agent subsystem exports · `src/agent/index.js`
- [Orchestrator](https://github.com/openqa-labs/openqa/blob/main/src/agent/Orchestrator.js): runtime coordinator · Coordinates a full agent run · `src/agent/Orchestrator.js`
- [Session state](https://github.com/openqa-labs/openqa/blob/main/src/agent/SessionManager.js): conversation state · Maintains per-browser-context continuity · `src/agent/SessionManager.js`
- [Logger](https://github.com/openqa-labs/openqa/blob/main/src/agent/Logger.js): step logging · Verbose output and secret redaction · `src/agent/Logger.js`
- [MCP server](https://github.com/openqa-labs/openqa/blob/main/src/agent/createMcpServer.js): browser bridge · Creates the Playwright MCP endpoint · `src/agent/createMcpServer.js`
- [System prompt](https://github.com/openqa-labs/openqa/blob/main/src/agent/systemPrompt.js): model instructions · Instruction set for the AI provider · `src/agent/systemPrompt.js`
- [Provider adapters](https://github.com/openqa-labs/openqa/tree/main/src/agent/providers): ai integrations · Thin wrappers for external model toolchains · `src/agent/providers`
- [Claude Code](https://github.com/openqa-labs/openqa/blob/main/src/agent/providers/claudeCode.js): provider adapter · Claude Code SDK integration · `src/agent/providers/claudeCode.js`
- [OpenCode](https://github.com/openqa-labs/openqa/blob/main/src/agent/providers/openCode.js): provider adapter · OpenCode SDK integration · `src/agent/providers/openCode.js`

### CLI scaffolding

Project initialization and template generation

- [CLI entry](https://github.com/openqa-labs/openqa/blob/main/src/cli/bin.js): command entry · Package executable entry point · `src/cli/bin.js`
- [Init command](https://github.com/openqa-labs/openqa/blob/main/src/cli/init.js): scaffolder · Creates a new OpenQA harness in a target project · `src/cli/init.js`
- [Generate command](https://github.com/openqa-labs/openqa/blob/main/src/cli/generate.js): generator command · Runs generation tasks · `src/cli/generate.js`
- [Templates](https://github.com/openqa-labs/openqa/tree/main/src/cli/templates): starter layouts · Starter harnesses copied into user projects · `src/cli/templates`
- [BDD template](https://github.com/openqa-labs/openqa/tree/main/src/cli/templates/playwright-bdd): starter template · Playwright BDD harness layout · `src/cli/templates/playwright-bdd`
- [Cucumber template](https://github.com/openqa-labs/openqa/tree/main/src/cli/templates/cucumber): starter template · Cucumber harness layout · `src/cli/templates/cucumber`
- [YAML template](https://github.com/openqa-labs/openqa/tree/main/src/cli/templates/playwright-yaml): starter template · Playwright YAML harness layout · `src/cli/templates/playwright-yaml`

### YAML pipeline

Schema and generator for YAML-authored tests

- [YAML schema](https://github.com/openqa-labs/openqa/blob/main/src/yaml/schema.js): spec schema · Structure of YAML test files · `src/yaml/schema.js`
- [YAML generator](https://github.com/openqa-labs/openqa/blob/main/src/yaml/generator.js): artifact generator · Turns YAML specs into executable tests · `src/yaml/generator.js`

### Docs & release

Documentation and publishing automation

- [Docs site](https://github.com/openqa-labs/openqa/tree/main/docs): documentation · Product documentation and quickstart guides · `docs`
- [Release workflow](https://github.com/openqa-labs/openqa/blob/main/.github/workflows/release.yml): publishing automation · GitHub Actions release pipeline · `.github/workflows/release.yml`

### Other components

- [Examples](https://github.com/openqa-labs/openqa/tree/main/examples): reference projects · End-to-end usage samples for all supported styles · `examples`

## Connections

- Package API → Agent API: re-exports · Package surface exposes agent runtime APIs
- Package API → CLI entry: exposes · Package also ships the CLI entry
- Agent API → Orchestrator: uses · Agent API centers on orchestration
- Orchestrator → Session state: tracks · Keeps scenario state across steps
- Orchestrator → Logger: logs · Emits step-by-step trace output
- Orchestrator → MCP server: spins up · Creates the browser MCP bridge
- Orchestrator → System prompt: instructs · Feeds the model its operating instructions
- Orchestrator → Provider adapters: delegates to · Uses provider-specific AI client adapters
- Provider adapters → Claude Code: includes · Claude Code integration
- Provider adapters → OpenCode: includes · OpenCode integration
- Claude Code → MCP server: connects · Provider client talks to the MCP endpoint
- OpenCode → MCP server: connects · Provider client talks to the MCP endpoint
- CLI entry → Init command: dispatches · CLI entry routes to init
- CLI entry → Generate command: dispatches · CLI entry routes to generate
- Init command → Templates: copies · Initializes a project from a template
- Templates → BDD template: contains · BDD starter layout
- Templates → Cucumber template: contains · Cucumber starter layout
- Templates → YAML template: contains · YAML starter layout
- YAML template → YAML schema: aligns with · Template matches YAML test structure
- YAML template → YAML generator: uses · Generated harness executes YAML tests
- YAML generator → YAML schema: validates against · Generator consumes the YAML spec shape
- Examples → Package API: exercise · Examples demonstrate the core runtime
- Examples → BDD template: mirror · Example projects reflect generated harnesses
- Examples → Cucumber template: mirror · Example projects reflect generated harnesses
- Examples → YAML template: mirror · Example projects reflect generated harnesses
- Docs site → Package API: documents · Docs explain the main package flow
- Release workflow → Package API: publishes · Workflow packages and releases the library