Getting Started

Testonaut Documentation

Testonaut is an end-to-end AI test agent that closes the loop from a Jira requirement to tested, reviewable automation code. A QA engineer or Jira automation rule starts with a story key. Testonaut gathers the story context, designs the test coverage, uploads the resulting test cases to Xray, implements the missing automation in the target repository, verifies it, and raises a pull request for human review.

The system can run locally from the testonaut CLI, but the intended operating model is unattended execution from Jira automation through a parameterized Azure pipeline. Jira rules pass the issue key, target repository, and run mode into the pipeline.

Run modes

Mode	Purpose
`design`	Research the ticket, design tests, and upload linked Xray tests.
`implement`	Reconstruct the design from Xray, implement missing automation, verify, and raise a PR.
`both`	Run design and implementation in one pipeline execution.
`coverage`	Analyse linked tests against the story, comment gaps, and optionally create missing Xray tests.

Agentic work with bounded artifacts

The core design principle: each stage can use LLM reasoning internally, but every hand-off is a Zod-validated artifact with schema version, provenance, and warnings. This keeps the agent auditable, reproducible, and safe to operate in CI.

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.

End-to-end flow

Xray is the hand-off point between design and implementation. After design, implementation can run statelessly from --issue <KEY> by reading the linked Xray tests.
Design is repository-aware. Testonaut scans existing .feature files and reuses established Gherkin step phrasings instead of creating near-duplicate steps.
Implementation is environment-aware. 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.

New here?

Start with the Quick Start to scaffold a repository, then follow the Jira Integration guide to run Testonaut unattended from Jira automation.

Explore the documentation

Quick StartScaffold a repository, run a readiness check, and trigger your first run.Jira IntegrationWire Jira Automation to the Testonaut Azure pipeline, step by step.ArchitectureThe four agent phases, their artifacts, and the key architectural ideas.Cross-Cutting LayerZod artifacts, audit log, cost budgets, redaction, and Langfuse telemetry.Phase 1 · ResearcherTurns a Jira key into a validated ContextPack with an evidence graph.Phase 2 · Test DesignRepository-aware scenario design, coverage gates, and Xray upload.Phase 3 · Code AgentEnvironment-aware implementation, verification, healing, and the PR.Phase 4 · Feedback & LearningPR review collaboration and human-reviewed learning proposals.CLI CommandsThe testonaut CLI: init, check, design, implement, respond, audit.ConfigurationRepository config, stacks, policy gates, budgets, and environment variables.