Quick Start

Prepare the target repository

The easiest way to create the Testonaut project structure is to run the init command from a terminal:

testonaut init --repo <path-to-target-repo>

# Or, from inside the target repository:
testonaut init

# Recreate generated files intentionally:
testonaut init --repo <path-to-target-repo> --force

This scaffolds the Testonaut files in the repository, including:

• AGENTS.md
• .agents/testonaut.config.json
• .agents/test-architecture.md
• .agents/test-conventions.json

The command is safe to run on an existing repository — it refuses to overwrite existing Testonaut files by default. After scaffolding, run the readiness check and adjust the generated config for the project stack:

testonaut check --repo <path-to-target-repo>

Minimal repository config

{
  "schemaVersion": "1.0.0",
  "product": "desktop-tenant",
  "testDesign": {
    "outputMode": "gherkin",
    "language": "en"
  },
  "stacks": [
    {
      "id": "playwright-bdd-ts",
      "root": ".",
      "verifyCommand": "npm test",
      "featureGlob": "**/*.feature"
    }
  ],
  "policy": {
    "gates": {
      "acCoverage": "required",
      "riskCoverage": "warn",
      "humanReviewBeforeUpload": true,
      "humanReviewBeforePr": false
    },
    "budgets": {
      "maxCostPerRunUsd": 5,
      "maxCostPerDayUsd": 25
    },
    "redactPatterns": []
  },
  "pr": {
    "mention": "@testonaut",
    "maxIterationsPerPr": 5
  }
}

Why the repository config matters:

• Testonaut scans existing .feature files and step definitions so it can reuse existing Gherkin wording instead of creating near-duplicate steps.
• implement and both need a repository because the agent writes test code, commits on a branch, pushes, and raises a PR.
• The stack tells Testonaut how to verify the work.
• Docker settings make the implementation phase environment-aware instead of writing tests blindly.

Docker-backed stacks

For repositories that can start a local app with Docker Compose, configure the stack so Phase 3 can spin up the environment, explore it, verify the tests, and self-heal failures:

{
  "id": "playwright-bdd-ts",
  "root": ".",
  "kind": "ui",
  "setupCommand": "docker compose up -d",
  "teardownCommand": "docker compose down -v",
  "appUrl": "http://localhost:4200",
  "healthCheck": "http://localhost:4200/health",
  "readinessTimeoutMs": 480000,
  "verifyCommand": "npm test",
  "featureGlob": "**/*.feature"
}

Your first runs

# Phase 1 + 2: research the ticket and design tests, upload to Xray
testonaut design-tests --issue FINT-1056 --repo ./my-app

# Add the bounded LLM retrieval loop for large tickets
testonaut design-tests --issue FINT-1056 --repo ./my-app --deep

# Phase 3: implement from the linked Xray tests and raise a PR
testonaut implement-tests --issue FINT-1056 --repo ./my-app --pr

# Phase 4: respond to PR feedback
testonaut respond-to-pr --repo ./my-app --pr 42 --issue FINT-1056

What a run produces

Every run writes bounded artifacts under out/<KEY>/ — a machine-readable JSON source of truth plus a human-readable Markdown companion:

Ready to run unattended? Continue with the Jira Integration guide.