Generating and Updating Tests with AI

Use provider-specific instruction files (custom agents or skills) to generate Drift tests consistently, validate coverage, and maintain tests as your OpenAPI spec evolves.

Install Provider Instructions

Choose one of the templates based on your AI provider:

If your setup supports repository-level agent instructions, use the custom agent format. If your setup is skill-based, use the skill format instead.

  1. Custom agent format

    • Download <a href={useBaseUrl('/downloads/drift.agent.md')} download>drift.agent.md

    • Place it in your provider's supported agent location (for example, .github/agents/)

  2. Skill format

    • Download <a href={useBaseUrl('/downloads/SKILL.md')} download&>SKILL.md

    • Place it in your provider's supported skill location (for example, Claude-compatible setups)

The instruction body is intentionally aligned across both formats.

Use the instructions iteratively

The Drift instructions work best when you run them in small, verifiable steps.

Getting started when you have zero tests

If you are starting from scratch, this is a good first prompt:

Create a comprehensive drift test suite for this project, based on this OpenAPI document.

Note

Attach the relevant OpenAPI document as context to the prompt.

Expected outcome:

  • A broad test suite across your OpenAPI operations

  • A dataset file with starter data structures

  • A Lua script template with lifecycle hooks ready to populate

The generated suite is a strong starting point, but it may not pass out of the box. Most teams need to add state and data setup (seed data, auth tokens, teardown, or environment-specific values) before tests become stable.

Recommended Bootstrap Loop (red/green/refactor)

  1. Red: Run one operation and observe failures.

  2. Green: Add only the minimum setup/data needed to make that operation pass.

  3. Refactor: Move repeated setup into dataset entries, globals, or lifecycle hooks.

  4. Repeat operation-by-operation until the full suite is stable.

Use single-operation execution while bootstrapping:

drift verifier --test-files path/to/testcase.yaml --server-url http://localhost:8080 --operation <operationId>

Once your initial suite exists, use this same operation-by-operation loop to expand and harden coverage.

Existing Suite

Once your initial suite exists, use this same operation-by-operation loop to expand and harden coverage.

  1. Ask for a coverage plan and TODO file. Prompt your AI assistant:

    Analyze this OpenAPI document and create a comprehensive plan to reach 100% Drift test coverage.
Create a DRIFT_TODO.md file that lists tests by operation, status code, and media type.
Use checkboxes to track progress.
Then scaffold the initial Drift setup (test case YAML, dataset YAML, and Lua script), and implement only the first test from the plan.

  2. Get the first test passing. Run only the first planned operation:

    drift verifier --test-files path/to/testcase.yaml --server-url http://localhost:8080 --operation <first-test-operationId>

    If it fails, update only the minimum setup/data needed and re-run that same operation.

  3. Progress through DRIFT_TODO.md one test at a time. Prompt your AI assistant:

    Continue with the next unchecked item in DRIFT_TODO.md.
Implement exactly one test operation.
Do not move to the next item until I confirm this operation passes.

  4. Repeat until coverage goals are met. After each passing operation, ask the assistant to:

    • Mark the completed item in DRIFT_TODO.md

    • Implement the next unchecked test

    • Keep naming and structure consistent with existing tests

    Recommended audit prompt:

    Audit DRIFT_TODO.md and the current test files.
List any remaining coverage gaps by operation, status code, and media type.

Maintain Tests Over Time

When your API changes, use this update loop:

  1. Diff spec changes (new/changed/removed operations and response codes).

  2. Regenerate only impacted tests (avoid broad rewrites).

  3. Run changed operations first using --operation.

  4. Run full verifier only after targeted checks pass.

  5. Keep datasets and Lua minimal; avoid custom helpers unless explicitly needed.

Recommended maintenance prompt:

Update only the tests affected by this OpenAPI diff.
Preserve existing operation IDs where possible.
Show a checklist of added/updated/removed tests.

Example Prompts

New Endpoint

Create a new set of Drift tests for the new <x> endpoint.
Update DRIFT_TODO.md and include happy-path, validation, and auth scenarios where applicable.

Update Existing Endpoint Behavior

Update the Drift test case for the <x> endpoint, <y> status code, and <z> media type.
Only modify impacted tests and preserve existing operation IDs where possible.

Adapt Instructions Across Providers

If your platform uses a different instruction format, keep the same instruction body and map only wrapper fields and file placement:

  • Role + objective: Keep the Drift testing mission unchanged.

  • Workflow: Keep phased generation (start simple, then expand, then audit).

  • Guardrails: Keep constraints (no unnecessary Lua complexity, prefer datasets, verify schema compliance).

  • Execution guidance: Keep single-operation validation flow with drift verifier --operation.

Download and Reference

In this section:
© 2026
Publication date: