Phase 3: Code Agent

Inputs and outputs

Design source: file or Xray

The implementation phase can start from either a local design file or directly from the story's linked Xray tests. The --issue path is important for pipelines — it makes implementation stateless: the design step can upload tests to Xray, and a later implementation rule can reconstruct the work from Xray without needing a local artifact hand-off.

Why configuration exists

The Code Agent cannot safely guess how a repository should be tested. Different repositories have different frameworks, folder layouts, verify commands, Docker commands, application URLs, and MCP tools. testonaut init --repo <path> scaffolds the .agents folder; stack detection can pre-fill basic entries, and teams then tune the config with the real commands and URLs for their app. A typical stack config:

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

Environment-aware Docker flow

When a stack has setupCommand and the user did not pass --no-env, Testonaut attempts an environment-aware run.

Start environment

The environment manager runs setupCommand from the target repository root — usually docker compose up -d --build — then waits until the application is reachable. Readiness is checked against healthCheck when configured, otherwise appUrl. Any non-5xx response means the server is up and listening.

Readiness timeout

The default readiness timeout is 120 seconds. Some frontend stacks — especially monorepos or Nx apps that compile on startup — may need several minutes. That is why readinessTimeoutMs exists: if the app is slow, increase the timeout instead of letting the Code Agent implement tests against an app that never actually came up.

Teardown

After the implementation attempt, Testonaut runs teardownCommand if configured (best-effort, typically docker compose down -v). Teardown matters because these runs happen in CI and should not leave containers, networks, or volumes behind.

Why the Docker path matters

Explore before implementing

After the environment is ready, Testonaut tries to produce an exploration brief. This brief is injected into the implementation prompt so the Code Agent grounds its work in the real app.

• UI stacks: Playwright MCP opens the running app and reports concrete navigation paths, stable locators, labels, visible copy, and UI states.
• API stacks: openApiUrl fetches the OpenAPI/Swagger document and summarizes endpoints, HTTP methods, operation names, request/response schemas, and payload shapes.

Implementation prompt composition

The Code Agent receives a structured prompt, not a vague instruction to write tests:

This structure keeps the Code Agent focused on implementing tests in the repository's style instead of inventing a parallel automation framework.

Verification and healing loop

Verification runs the stack's verifyCommand, unless the user passes --no-verify or overrides it with --verify. The verifier captures command, exit code, duration, stdout, and stderr.

If verification fails, the Healer receives a narrow prompt containing the failing output and the changed files from the previous attempt. It is explicitly told to repair only the failing tests or test-support code — not to restart the implementation, change product code, weaken assertions, skip scenarios, or disable retries just to get green. The default healing budget is one attempt, controlled by --max-heal-attempts.

Graceful fallback behavior

The Docker path is best-effort — Testonaut still produces a useful PR when the environment cannot run:

Branch, commit, push, and PR

After implementation, Testonaut can create a branch, commit changes, push, and raise a pull request. For unattended pipeline runs, the VCS token authenticates both REST operations and git push — injected as a redacted http.extraHeader, never written into the remote URL. The PR platform is resolved from the repository remote and can use Azure DevOps or GitHub adapters.

Crash rescue

The implementation agent can occasionally exit non-zero after making valid changes — for example, if an agent transport drops near the end. If the agent reports failure but verification passed and files changed, the final status becomes partial instead of failed, so the branch and PR can proceed for human review rather than discarding working verified code.

ImplementationPack

CI requirements for Docker-backed verification