# bug0inc/qa-agent architecture

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

- Interactive diagram: https://gitdiagram.com/bug0inc/qa-agent
- Repository: https://github.com/bug0inc/qa-agent

## Overview

Bug0 AI is a Playwright library for natural-language regression tests. The principal workflow starts at runSteps: it resolves dynamic inputs and per-step AI settings, executes browser actions through snapshot-based models or optional CUA, waits and extracts values, then validates assertions (including optional video review). Redis-backed caching, email extraction, script safety, and telemetry are supporting capabilities. Edges reflect imports/calls visible in the excerpts or SOURCE INDEX; README-only feature links are labeled as documented.

Main entry points: [`src/index.ts`](https://github.com/bug0inc/qa-agent/blob/main/src/index.ts) (Step runner), [`src/cua/loop.ts`](https://github.com/bug0inc/qa-agent/blob/main/src/cua/loop.ts) (Computer-use loop), [`src/config.ts`](https://github.com/bug0inc/qa-agent/blob/main/src/config.ts) (AI configuration), [`src/models.ts`](https://github.com/bug0inc/qa-agent/blob/main/src/models.ts) (Model routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Test workflow"]
  node_runner["Step runner<br/>[index.ts]"]
  node_placeholders["Dynamic placeholders<br/>[data-cache.ts]"]
  node_wait["AI wait conditions<br/>[index.ts]"]
  node_extract["Page data extraction<br/>[extract.ts]"]
  node_script["Safe script execution"]
  node_tabs["Tab management<br/>[tab-manager.ts]"]
end

subgraph group_ai["AI execution"]
  node_models["Model routing<br/>[models.ts]"]
  node_config["AI configuration<br/>[config.ts]"]
  node_snapshot["Snapshot actions<br/>[tools.ts]"]
  node_cua["Computer-use loop<br/>[loop.ts]"]
  node_cuaactions["CUA actions<br/>[actions.ts]"]
  node_cuaclient["OpenAI CUA client<br/>[client.ts]"]
end

subgraph group_assert["Assertions and evidence"]
  node_assertions["Assertion consensus<br/>[assertion.ts]"]
  node_video["Video assertions<br/>[video.ts]"]
end

subgraph group_state["Test data and integrations"]
  node_redis[("Redis cache<br/>[redis.ts]")]
  node_email["Email extraction<br/>[email.ts]"]
  node_emailsink["Emailsink provider<br/>[emailsink.ts]"]
end

subgraph group_support["Runtime support"]
  node_instrumentation["AI telemetry<br/>[instrumentation.ts]"]
  node_logger["Logging<br/>[logger.ts]"]
  node_secureerrors["Runtime errors<br/>[errors.ts]"]
end

node_playwright(("Playwright test"))

node_playwright -->|"invokes"| node_runner
node_runner -->|"resolves inputs"| node_placeholders
node_runner -->|"runs scripts"| node_script
node_runner -->|"checks conditions"| node_wait
node_runner -->|"applies extraction"| node_extract
node_runner -->|"manages tabs"| node_tabs
node_runner -.->|"executes steps"| node_snapshot
node_runner -->|"dispatches CUA"| node_cua
node_cua -->|"executes actions"| node_cuaactions
node_cua -->|"uses client"| node_cuaclient
node_runner -->|"resolves AI"| node_config
node_runner -.->|"runs assertions"| node_assertions
node_runner -.->|"records and evaluates"| node_video
node_assertions -->|"resolves models"| node_models
node_assertions -->|"evaluates video"| node_video
node_wait -->|"resolves model"| node_models
node_extract -->|"uses models"| node_models
node_placeholders -->|"reads and writes"| node_redis
node_placeholders -->|"extracts email"| node_email
node_email -.->|"uses provider"| node_emailsink
node_models -->|"reads settings"| node_config
node_config -->|"initializes telemetry"| node_instrumentation
node_instrumentation -->|"logs"| node_logger
node_cua -->|"logs"| node_logger
node_cua -->|"reads settings"| node_config
node_cuaclient -->|"checks gateway type"| node_config

click node_runner "https://github.com/bug0inc/qa-agent/blob/main/src/index.ts"
click node_placeholders "https://github.com/bug0inc/qa-agent/blob/main/src/data-cache.ts"
click node_wait "https://github.com/bug0inc/qa-agent/blob/main/src/utils/index.ts"
click node_extract "https://github.com/bug0inc/qa-agent/blob/main/src/extract.ts"
click node_script "https://github.com/bug0inc/qa-agent/blob/main/src/utils/secure-script-runner.ts"
click node_tabs "https://github.com/bug0inc/qa-agent/blob/main/src/utils/tab-manager.ts"
click node_models "https://github.com/bug0inc/qa-agent/blob/main/src/models.ts"
click node_config "https://github.com/bug0inc/qa-agent/blob/main/src/config.ts"
click node_snapshot "https://github.com/bug0inc/qa-agent/blob/main/src/tools.ts"
click node_cua "https://github.com/bug0inc/qa-agent/blob/main/src/cua/loop.ts"
click node_cuaactions "https://github.com/bug0inc/qa-agent/blob/main/src/cua/actions.ts"
click node_cuaclient "https://github.com/bug0inc/qa-agent/blob/main/src/cua/client.ts"
click node_assertions "https://github.com/bug0inc/qa-agent/blob/main/src/assertion.ts"
click node_video "https://github.com/bug0inc/qa-agent/blob/main/src/video.ts"
click node_redis "https://github.com/bug0inc/qa-agent/blob/main/src/redis.ts"
click node_email "https://github.com/bug0inc/qa-agent/blob/main/src/email.ts"
click node_emailsink "https://github.com/bug0inc/qa-agent/blob/main/src/providers/emailsink.ts"
click node_instrumentation "https://github.com/bug0inc/qa-agent/blob/main/src/instrumentation.ts"
click node_logger "https://github.com/bug0inc/qa-agent/blob/main/src/logger.ts"
click node_secureerrors "https://github.com/bug0inc/qa-agent/blob/main/src/errors.ts"

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_runner,node_placeholders,node_wait,node_extract,node_script,node_tabs toneBlue
class node_models,node_config,node_snapshot,node_cua,node_cuaactions,node_cuaclient toneAmber
class node_assertions,node_video toneMint
class node_redis,node_email,node_emailsink toneRose
class node_instrumentation,node_logger,node_secureerrors,node_playwright toneIndigo
```

## Components

### Test workflow

- [Step runner](https://github.com/bug0inc/qa-agent/blob/main/src/index.ts): `src/index.ts`
- [Dynamic placeholders](https://github.com/bug0inc/qa-agent/blob/main/src/data-cache.ts): `src/data-cache.ts`
- [AI wait conditions](https://github.com/bug0inc/qa-agent/blob/main/src/utils/index.ts): `src/utils/index.ts`
- [Page data extraction](https://github.com/bug0inc/qa-agent/blob/main/src/extract.ts): `src/extract.ts`
- [Safe script execution](https://github.com/bug0inc/qa-agent/blob/main/src/utils/secure-script-runner.ts): `src/utils/secure-script-runner.ts`
- [Tab management](https://github.com/bug0inc/qa-agent/blob/main/src/utils/tab-manager.ts): `src/utils/tab-manager.ts`

### AI execution

- [Model routing](https://github.com/bug0inc/qa-agent/blob/main/src/models.ts): `src/models.ts`
- [AI configuration](https://github.com/bug0inc/qa-agent/blob/main/src/config.ts): `src/config.ts`
- [Snapshot actions](https://github.com/bug0inc/qa-agent/blob/main/src/tools.ts): `src/tools.ts`
- [Computer-use loop](https://github.com/bug0inc/qa-agent/blob/main/src/cua/loop.ts): `src/cua/loop.ts`
- [CUA actions](https://github.com/bug0inc/qa-agent/blob/main/src/cua/actions.ts): `src/cua/actions.ts`
- [OpenAI CUA client](https://github.com/bug0inc/qa-agent/blob/main/src/cua/client.ts): `src/cua/client.ts`

### Assertions and evidence

- [Assertion consensus](https://github.com/bug0inc/qa-agent/blob/main/src/assertion.ts): `src/assertion.ts`
- [Video assertions](https://github.com/bug0inc/qa-agent/blob/main/src/video.ts): `src/video.ts`

### Test data and integrations

- [Redis cache](https://github.com/bug0inc/qa-agent/blob/main/src/redis.ts): `src/redis.ts`
- [Email extraction](https://github.com/bug0inc/qa-agent/blob/main/src/email.ts): `src/email.ts`
- [Emailsink provider](https://github.com/bug0inc/qa-agent/blob/main/src/providers/emailsink.ts): `src/providers/emailsink.ts`

### Runtime support

- [AI telemetry](https://github.com/bug0inc/qa-agent/blob/main/src/instrumentation.ts): `src/instrumentation.ts`
- [Logging](https://github.com/bug0inc/qa-agent/blob/main/src/logger.ts): `src/logger.ts`
- [Runtime errors](https://github.com/bug0inc/qa-agent/blob/main/src/errors.ts): `src/errors.ts`

### Other components

- **Playwright test**

## Connections

- Playwright test → Step runner: invokes (evidence: `README.md`)
- Step runner → Dynamic placeholders: resolves inputs (evidence: `src/index.ts`)
- Step runner → Safe script execution: runs scripts (evidence: `src/index.ts`)
- Step runner → AI wait conditions: checks conditions (evidence: `src/index.ts`)
- Step runner → Page data extraction: applies extraction (evidence: `src/index.ts`)
- Step runner → Tab management: manages tabs (evidence: `src/index.ts`)
- Step runner → Snapshot actions: executes steps (evidence: `src/index.ts`)
- Step runner → Computer-use loop: dispatches CUA (evidence: `src/index.ts`)
- Computer-use loop → CUA actions: executes actions (evidence: `src/cua/loop.ts`)
- Computer-use loop → OpenAI CUA client: uses client (evidence: `src/cua/loop.ts`)
- Step runner → AI configuration: resolves AI (evidence: `src/index.ts`)
- Step runner → Assertion consensus: runs assertions (evidence: `src/index.ts`)
- Step runner → Video assertions: records and evaluates (evidence: `src/index.ts`)
- Assertion consensus → Model routing: resolves models (evidence: `src/assertion.ts`)
- Assertion consensus → Video assertions: evaluates video (evidence: `src/assertion.ts`)
- AI wait conditions → Model routing: resolves model (evidence: `src/utils/index.ts`)
- Page data extraction → Model routing: uses models (evidence: `src/extract.ts`)
- Dynamic placeholders → Redis cache: reads and writes (evidence: `src/data-cache.ts`)
- Dynamic placeholders → Email extraction: extracts email (evidence: `src/data-cache.ts`)
- Email extraction → Emailsink provider: uses provider
- Model routing → AI configuration: reads settings (evidence: `src/models.ts`)
- AI configuration → AI telemetry: initializes telemetry (evidence: `src/config.ts`)
- AI telemetry → Logging: logs (evidence: `src/instrumentation.ts`)
- Computer-use loop → Logging: logs (evidence: `src/cua/loop.ts`)
- Computer-use loop → AI configuration: reads settings (evidence: `src/cua/loop.ts`)
- OpenAI CUA client → AI configuration: checks gateway type (evidence: `src/cua/client.ts`)
