# rayanfer32/autonomous-ui-test-agent architecture

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

- Interactive diagram: https://gitdiagram.com/rayanfer32/autonomous-ui-test-agent
- Repository: https://github.com/rayanfer32/autonomous-ui-test-agent

## Overview

Autonomous UI Test Agent turns a GitHub issue or local fixture into acceptance criteria, plans scenarios, and executes them against a real application through an LLM-controlled browser. It checks proposed criterion verdicts against captured page snapshots, then emits a PASS/FAIL report and run evidence. The main execution loop and issue, guardrail, evidence, and report behavior are sampled; planner, LLM client, and browser implementation details are not, so their connections are included only where README or indexed references support them.

Main entry points: [`src/agent.py`](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/agent.py) (Execution loop), [`run_agent.py`](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/run_agent.py) (Run CLI), [`src/planner.py`](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/planner.py) (Scenario planner), [`src/report.py`](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/report.py) (Report writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Issue intake"]
  node_issue_source["Issue source<br/>[issue_loader.py]"]
end

subgraph group_planning["Planning and models"]
  node_issue_data["Issue and criteria<br/>[models.py]"]
  node_settings["Run settings<br/>[config.py]"]
  node_planner["Scenario planner<br/>[planner.py]"]
  node_prompts["Agent prompts<br/>[prompts.py]"]
  node_llm["LLM client<br/>[llm.py]"]
end

subgraph group_execution["Browser execution"]
  node_agent["Execution loop<br/>[agent.py]"]
  node_browser["MCP browser tools<br/>[browser.py]"]
end

subgraph group_verification["Verification and reporting"]
  node_guardrails["Loop and quote checks<br/>[guardrails.py]"]
  node_recorder["Run recorder<br/>[evidence.py]"]
  node_evidence_store[("Run evidence files")]
  node_report["Report writer<br/>[report.py]"]
end

node_qa(("QA engineer"))
node_cli["Run CLI<br/>[run_agent.py]"]
node_github["GitHub REST API"]
node_mcp["Playwright MCP"]
node_chromium["Browser runtime"]
node_app["Application under test"]

node_qa -->|"starts run"| node_cli
node_cli -->|"loads issue"| node_issue_source
node_issue_source -->|"fetches issue"| node_github
node_issue_source -->|"builds criteria"| node_issue_data
node_cli -->|"resolves settings"| node_settings
node_cli -->|"builds plan"| node_planner
node_planner -->|"requests scenarios"| node_llm
node_planner -.->|"uses prompt"| node_prompts
node_planner -->|"plans from issue"| node_issue_data
node_cli -->|"runs plan"| node_agent
node_agent -->|"requests tool calls"| node_llm
node_agent -->|"uses executor prompt"| node_prompts
node_agent -->|"dispatches tools"| node_browser
node_browser -->|"sends tool calls"| node_mcp
node_mcp -->|"drives browser"| node_chromium
node_chromium -->|"interacts with UI"| node_app
node_browser -->|"returns snapshots"| node_agent
node_agent -->|"checks progress and verdicts"| node_guardrails
node_agent -->|"records run events"| node_recorder
node_recorder -->|"writes artifacts"| node_evidence_store
node_agent -->|"produces results"| node_issue_data
node_cli -->|"writes reports"| node_report
node_report -->|"renders outcomes"| node_issue_data
node_report -->|"writes report files"| node_recorder
node_report -->|"stores reports"| node_evidence_store

click node_cli "https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/run_agent.py"
click node_issue_source "https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/issue_loader.py"
click node_issue_data "https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/models.py"
click node_settings "https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/config.py"
click node_planner "https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/planner.py"
click node_prompts "https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/prompts.py"
click node_llm "https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/llm.py"
click node_agent "https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/agent.py"
click node_browser "https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/browser.py"
click node_guardrails "https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/guardrails.py"
click node_recorder "https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/evidence.py"
click node_evidence_store "https://github.com/rayanfer32/autonomous-ui-test-agent/tree/main/evidence"
click node_report "https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/report.py"

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_issue_source,node_chromium toneBlue
class node_issue_data,node_settings,node_planner,node_prompts,node_llm toneAmber
class node_agent,node_browser,node_github toneMint
class node_guardrails,node_recorder,node_evidence_store,node_report toneRose
class node_qa,node_mcp,node_app toneIndigo
class node_cli toneTeal
```

## Components

### Issue intake

- [Issue source](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/issue_loader.py): `src/issue_loader.py`

### Planning and models

- [Issue and criteria](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/models.py): `src/models.py`
- [Run settings](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/config.py): `src/config.py`
- [Scenario planner](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/planner.py): `src/planner.py`
- [Agent prompts](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/prompts.py): `src/prompts.py`
- [LLM client](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/llm.py): `src/llm.py`

### Browser execution

- [Execution loop](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/agent.py): `src/agent.py`
- [MCP browser tools](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/browser.py): `src/browser.py`

### Verification and reporting

- [Loop and quote checks](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/guardrails.py): `src/guardrails.py`
- [Run recorder](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/evidence.py): `src/evidence.py`
- [Run evidence files](https://github.com/rayanfer32/autonomous-ui-test-agent/tree/main/evidence): `evidence`
- [Report writer](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/src/report.py): `src/report.py`

### Other components

- **QA engineer**
- [Run CLI](https://github.com/rayanfer32/autonomous-ui-test-agent/blob/main/run_agent.py): `run_agent.py`
- **GitHub REST API**
- **Playwright MCP**
- **Browser runtime**
- **Application under test**

## Connections

- QA engineer → Run CLI: starts run (evidence: `README.md`)
- Run CLI → Issue source: loads issue (evidence: `run_agent.py`)
- Issue source → GitHub REST API: fetches issue (evidence: `src/issue_loader.py`)
- Issue source → Issue and criteria: builds criteria (evidence: `src/issue_loader.py`)
- Run CLI → Run settings: resolves settings (evidence: `run_agent.py`)
- Run CLI → Scenario planner: builds plan (evidence: `run_agent.py`)
- Scenario planner → LLM client: requests scenarios (evidence: `README.md`)
- Scenario planner → Agent prompts: uses prompt
- Scenario planner → Issue and criteria: plans from issue (evidence: `README.md`)
- Run CLI → Execution loop: runs plan (evidence: `run_agent.py`)
- Execution loop → LLM client: requests tool calls (evidence: `README.md`)
- Execution loop → Agent prompts: uses executor prompt (evidence: `src/agent.py`)
- Execution loop → MCP browser tools: dispatches tools (evidence: `src/agent.py`)
- MCP browser tools → Playwright MCP: sends tool calls (evidence: `README.md`)
- Playwright MCP → Browser runtime: drives browser (evidence: `README.md`)
- Browser runtime → Application under test: interacts with UI (evidence: `README.md`)
- MCP browser tools → Execution loop: returns snapshots (evidence: `README.md`)
- Execution loop → Loop and quote checks: checks progress and verdicts (evidence: `src/agent.py`)
- Execution loop → Run recorder: records run events (evidence: `src/agent.py`)
- Run recorder → Run evidence files: writes artifacts (evidence: `src/evidence.py`)
- Execution loop → Issue and criteria: produces results (evidence: `src/agent.py`)
- Run CLI → Report writer: writes reports (evidence: `run_agent.py`)
- Report writer → Issue and criteria: renders outcomes (evidence: `src/report.py`)
- Report writer → Run recorder: writes report files (evidence: `src/report.py`)
- Report writer → Run evidence files: stores reports (evidence: `README.md`)
