API AQA Flow

TL;DR

Use api-aqa-flow when backend API endpoints need automated test coverage grounded in real contracts. The workflow loads or creates a project config, collects test cases and documentation, extracts endpoint contracts from Swagger/OpenAPI or backend code, clarifies gaps with you, writes Given-When-Then specifications for your approval, implements them as executable tests with shared utilities, then stops so you can run the tests — and triages your results into evidence-backed corrections.

This is a strict sequential workflow (phases 0–7). Phases build on each other, agents/TEMP/<FEATURE>/api-aqa-state.md is updated after each phase, and the coding agent must not skip ahead. Mandatory user interaction happens in Phases 3–7; Phase 0 asks a config interview only when no project config exists yet.

When To Use This Workflow

When Not To Use This Workflow

Before You Start

Prepare the inputs this workflow explicitly depends on:

Auth answers are redacted at intake: the config records Bearer JWT from AuthHelper; credentials in env vars ... style descriptions — literal tokens or passwords are never persisted.

How To Start

Typical prompts:

/api-aqa-flow Write backend API tests for TC-1234. Swagger: https://api.example.com/swagger.json

/api-aqa-flow Automate backend tests for PROJ-123 with Swagger from refsrc/my-backend/docs/openapi.json

/api-aqa-flow Create API tests for the user registration endpoint (no ticket, direct description).

/api-aqa-flow Write contract tests for the auth endpoints (login / refresh / logout). Swagger: https://api.example.com/v2/openapi.yaml; Jira: PROJ-789.

How Rosetta Shapes This Workflow

Rosetta provides the instructions. The coding agent executes them.

Workflow At A Glance

Phase What you provide What the coding agent does What you get Mandatory workflow stop
0. Project Config Loading Test case reference; config interview answers on first run Derives {IDENTIFIER}, creates plans/api-aqa-{IDENTIFIER}/, loads or creates the project config, seeds state api-aqa-project-config.md, initial-data.md, state file Config interview only if no config exists
1. Data Collection Access to TMS/docs sources per config Collects test cases + documentation via config-resolved vendor bindings; scans existing test patterns and backend source plans/api-aqa-{IDENTIFIER}/raw-data.md None
2. API Spec Analysis Swagger URL/path or backend source Extracts per-endpoint contracts, reconciles spec vs code, documents auth and data dependencies plans/api-aqa-{IDENTIFIER}/api-analysis.md None
3. Gap & Requirements Clarification Answers to Critical / Important / Optional questions Cross-references cases, docs, and contracts; surfaces gaps, contradictions, ambiguities plans/api-aqa-{IDENTIFIER}/analysis.md with resolutions Mandatory user answers before Phase 4
4. Test Case Specification Explicit approval (approved / approve / yes) Writes Given-When-Then ATC-NNN specs with file mapping, shared utilities, execution order plans/api-aqa-{IDENTIFIER}/test-specs.md Approval gate before Phase 5
5. Test Implementation Nothing new; then you run the tests Implements every approved ATC + shared utilities (auth helper, data factory, validators), lint-clean, with ATC↔test traceability Test files + hand-off summary Mandatory user execution before Phase 6
6. Execution & Report Analysis Test execution report or output Triages each failure into one taxonomy category with root cause + evidence label plans/api-aqa-{IDENTIFIER}/execution-report.md Mandatory user handoff of results
7. Test Corrections Explicit approval per proposed fix Prepares before/after proposals tied to ERR-N report entries; applies approved changes with lint checks Corrected test files and re-test guidance Explicit approval required before changes

Workflow Overview

flowchart TD
    A[Start API AQA request] --> B[Phase 0 Project Config Loading]
    B --> B1{Config exists?}
    B1 -- No --> B2[Config interview with user]
    B2 --> C[Phase 1 Data Collection]
    B1 -- Yes --> C
    C --> D[Phase 2 API Spec Analysis]
    D --> E[Phase 3 Gap and Requirements Clarification]
    E --> E1{User answered?}
    E1 -- No --> E2[Wait for answers]
    E2 --> E1
    E1 -- Yes --> F[Phase 4 Test Case Specification]
    F --> F1{Specs approved with exact token?}
    F1 -- No --> F
    F1 -- Yes --> G[Phase 5 Test Implementation]
    G --> G1[Stop - user runs the tests]
    G1 --> H[Phase 6 Execution and Report Analysis]
    H --> H1{Tests passed?}
    H1 -- Yes --> J[Finish]
    H1 -- No --> I[Phase 7 Test Corrections]
    I --> I1{User approved fixes?}
    I1 -- Yes --> I2[Apply approved changes]
    I2 --> G1
    I1 -- No --> H

Interaction Flow

sequenceDiagram
    autonumber
    participant U as User
    participant R as Rosetta Instructions
    participant A as Coding Agent
    participant X as External Systems
    participant F as Workspace Files

    U->>A: Request backend API test automation
    R-->>A: Enforce sequential phases, no assumptions, state tracking
    A->>F: Create plans/api-aqa-IDENTIFIER/ and state file
    opt Config missing
        A->>U: Ask the project config interview
        U->>A: Answer sources, spec, framework, auth (scheme + source)
    end
    A->>X: Collect test cases and documentation
    A->>F: Write raw-data.md
    A->>F: Extract endpoint contracts into api-analysis.md
    A->>U: Ask gap and clarification questions
    U->>A: Provide answers
    A->>F: Write analysis.md with resolutions
    A->>F: Write test-specs.md with ATC-NNN scenarios
    A-->>U: Present spec summary for approval
    U->>A: approved
    A->>F: Implement tests and shared utilities
    A->>U: Stop and ask user to run the tests
    U->>A: Provide execution report
    A->>F: Write execution-report.md with ERR-N root causes
    A-->>U: Present proposed corrections for approval
    U->>A: Approve with exact token
    A->>F: Apply approved changes and update state

Phases

Phase 0: Project Config Loading

Goal:

What you provide:

What the agent does:

What to watch for:

Phase 1: Data Collection

Goal:

What you provide:

What the agent does:

What to watch for:

Phase 2: API Spec Analysis

Goal:

What you provide:

What the agent does:

What to watch for:

Phase 3: Gap & Requirements Clarification

Goal:

What you provide:

What the agent does:

What to watch for:

Phase 4: Test Case Specification

Goal:

What you provide:

What the agent does:

What to watch for:

Phase 5: Test Implementation

Goal:

What you provide:

What the agent does:

What to watch for:

Phase 6: Execution & Report Analysis

Goal:

What you provide:

What the agent does:

What to watch for:

Phase 7: Test Corrections

Goal:

What you provide:

What the agent does:

What to watch for:

How To Review Results

Workflow-Specific Customization

Artifacts You Will Get

Per session, under plans/api-aqa-{IDENTIFIER}/:

Plus: agents/TEMP/<FEATURE>/api-aqa-state.md (phase status, metrics, approvals) and the implemented test files + shared utilities.

Common Mistakes

Source Files

Authoritative source workflow and phases:

Shared skills: qa-knowledge, qa-structure, data-collection