Architecture
Architecture
A Jira automation rule starts a containerized Testonaut run. Work flows through four agent phases, each emitting a Zod-validated artifact that the next phase consumes, governed by a cross-cutting control plane.
Architecture diagram
Architecture at a glance
| Stage | Agent / component | Responsibilities | Output |
|---|---|---|---|
| Trigger | Jira automation + Azure pipeline | Starts a containerized Testonaut run with mode = design, implement, both, or coverage. | Pipeline run |
| Context | Researcher | Reads Jira, Confluence, linked tickets, comments, attachments, branches, PRs, and already-linked Xray tests. Builds retrieval context and an evidence graph. | ContextPack |
| Test design | Test Architect | Extracts acceptance criteria, authors Gherkin or Manual scenarios, applies AC and risk coverage gates, reuses existing repository Gherkin steps, and uploads tests to Xray. | TestDesignPack + Xray test keys |
| Implementation | Code agent | Reconstructs the design from Xray, spins up Docker when configured, explores the live app or API, implements missing automation, verifies, self-heals failures, commits, and raises a PR. | ImplementationPack + pull request |
| Feedback and learning | Responder / Learning engine | Acts on @testonaut PR comments, applies scoped fixes, replies with results, and proposes durable rule updates via separate human-reviewed PRs. | Replies, learning records, guideline PRs |
The bounded artifacts
Every hand-off between phases is a Zod-validated artifact with schema version, provenance, and warnings — never free-form model text:
| Artifact | Produced by | Used for |
|---|---|---|
ContextPack | Researcher | The validated evidence set for the ticket. |
TestDesignPack | Test Architect | Scenario design, coverage matrix, Xray upload, and implementation input. |
ImplementationPack | Code agent / verifier / healer | Changed files, verification result, PR metadata, and run outcome. |
LearningRecordSet | Learning engine | Durable lessons proposed through human-reviewed guideline PRs. |
Key architectural ideas
- Xray becomes the hand-off point between design and implementation. After design, implementation can run statelessly from
--issue <KEY>by reading the linked Xray tests and reconstructing the scenarios. - Design is repository-aware. Testonaut scans existing
.featurefiles and reuses established Gherkin step phrasings instead of creating near-duplicate steps. - Implementation is environment-aware when the target stack supports it. A configured Docker setup command lets Testonaut start the app, explore real UI locators or API contracts, verify against the running system, and self-heal failing tests.
- Every mutating action is governed. Xray uploads, PR creation, learning proposals, and budget breaches are written to a redacted audit log.
- Every run is observable. LLM calls and agentic phases are traced with OpenTelemetry and grouped into one session per Jira issue in Langfuse or Phoenix.
The control plane
The cross-cutting layer constrains every boundary with validated artifacts, provenance, audit events, cost governance, redaction, and telemetry — agents may reason freely inside a phase, but every consequential action leaves a structured trail.
The four phases in depth
Each phase has its own detailed documentation page:
- Phase 1 · Researcher — turns a raw Jira issue key into a rich, validated
ContextPack. - Phase 2 · Test Design — repository-aware scenario design with coverage gates and Xray upload.
- Phase 3 · Code Agent — environment-aware implementation, verification, healing, and the PR.
- Phase 4 · Feedback & Learning — PR review collaboration and human-reviewed learning proposals.