Reference

Configuration

Repository-specific behavior lives in .agents/testonaut.config.json; secrets and service endpoints come from the runtime environment. The config is itself Zod-validated — invalid JSON or fields fail fast with readable errors.

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
  }
}

Field	Purpose
`testDesign.outputMode`	gherkin (Cucumber tests) or plain-english (Manual tests).
`testDesign.language`	Language for authored scenarios.
`pr.mention`	PR mention handle the responder listens for.
`pr.maxIterationsPerPr`	Response-cycle budget per pull request.

Stack configuration

A stack tells Testonaut how a repository is tested — and, when Docker settings are present, how to bring the app up for environment-aware implementation:

{
  "id": "ui-playwright",
  "root": ".",
  "kind": "ui",
  "verifyCommand": "npm run test:e2e",
  "featureGlob": "features/**/*.feature",
  "setupCommand": "docker compose up -d --build",
  "teardownCommand": "docker compose down -v",
  "appUrl": "http://localhost:4200",
  "healthCheck": "http://localhost:4200/health",
  "openApiUrl": "http://localhost:8080/swagger.json",
  "readinessTimeoutMs": 480000
}

Field	Purpose
`id`	Stack identifier selected by --stack, or the default first stack.
`root`	Stack root inside the repository.
`kind`	ui or api — chooses Playwright MCP vs OpenAPI exploration.
`verifyCommand`	Command used to verify the generated tests.
`featureGlob`	Where Cucumber feature files live.
`setupCommand`	Starts the Docker/app environment.
`teardownCommand`	Stops the environment after the run.
`appUrl`	Running app URL for UI exploration and readiness.
`healthCheck`	Readiness URL; defaults to appUrl if omitted.
`openApiUrl`	OpenAPI/Swagger URL for API exploration.
`readinessTimeoutMs`	Max time to wait for setup and readiness (default 120 s).

Policy: gates and budgets

Setting	Purpose
`policy.gates.acCoverage`	AC coverage enforcement: required, warn, or off. Required by default.
`policy.gates.riskCoverage`	Risk/edge coverage gate: required, warn, or off. Defaults to warn.
`policy.gates.humanReviewBeforeUpload`	Requires confirmation (--yes) before Xray upload.
`policy.gates.humanReviewBeforePr`	Requires confirmation before raising a PR.
`policy.design.deriveRequirements`	Enables implied requirement mining (default on).
`policy.design.adversarialCritique`	Enables the design critique pass (default on).
`policy.budgets.maxCostPerRunUsd`	Per-run LLM spend limit.
`policy.budgets.maxCostPerDayUsd`	Per-day LLM spend limit.
`policy.redactPatterns`	Project-specific regex patterns redacted from logs, telemetry, audit, and comments.

MCP servers

Configured MCP servers are passed to the code-agent phases — Playwright MCP for live UI exploration, Figma MCP for design context. Transports: stdio, http, and sse. Secrets are never stored inline — values reference environment placeholders expanded at runtime:

{
  "mcpServers": {
    "playwright": {
      "transport": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "figma": {
      "transport": "http",
      "url": "https://mcp.figma.example",
      "headers": { "Authorization": "Bearer ${FIGMA_TOKEN}" }
    }
  }
}

Environment variables

Variable	Purpose
Jira / Confluence credentials	Base URLs and tokens for Phase 1 context gathering.
Xray credentials	Enable creation and linking of Cucumber/Manual tests.
`AZURE_DEVOPS_PAT` / `GITHUB_TOKEN`	VCS token for clone, push, and PR operations.
`TESTONAUT_REPO_ROOTS`	JSON map of repository name → local checkout path for dev-section resolution.
`TESTONAUT_AGENT_REPO`	Local Testonaut checkout, required for @update-agent learning proposals.
`TESTONAUT_AUDIT_LOG`	Audit log path override.
`TESTONAUT_COST_LEDGER`	Cost ledger path override.
`TESTONAUT_MODEL_PRICES`	JSON price table for custom or Azure deployment names.
`OTEL_ENABLED`, `OTEL_PROVIDER`, `OTEL_PUBLIC_KEY`, `OTEL_SECRET_KEY`, `OTEL_ENDPOINT`, `OTEL_PROJECT_NAME`	Langfuse telemetry configuration.
`OTEL_SESSION_ID`, `OTEL_USER_ID`	Optional telemetry attribution; sessions default to jira:<ISSUE-KEY>.

Where secrets live

In pipelines, secrets come from the testonaut-secrets variable group. Locally they can live in .env. Repository config files never contain secrets — MCP and adapter configs reference ${ENV_VAR} placeholders instead.