Skip to main content

Quick Start

In this guide, you will run your first Drift test suite against the live Swagger Petstore API. This requires zero local server setup and demonstrates how Drift validates an implementation against its OpenAPI contract.

Testing your own API?

drift init is an interactive terminal UI that guides you through authentication, endpoint selection, and configuration — and runs your first test for you.

Go to the drift init tutorial

1. Install Drift​

The simplest way to try Drift without installing anything globally is with npx:

npx @pactflow/drift --help

If you prefer a global install (available across shells), install from npm:

npm install -g @pactflow/drift
drift --help

Need more options? See Installation for manual installation, verification steps, and troubleshooting.

2. Authenticate​

Drift requires a PactFlow account to run. Log in with:

drift auth login

Enter your PactFlow workspace URL and API token when prompted. Your session is cached for 7 days — you will not need to log in again for subsequent runs.

Find your API token in your PactFlow workspace under Settings → API Tokens. If you do not have an account, sign up for a free trial.

3. Create your test suite​

Create a file named drift.yaml. This points Drift at the Petstore OpenAPI definition and defines a few operations to verify.

# yaml-language-server: $schema=https://download.pactflow.io/drift/schemas/drift.testcases.v1.schema.json
drift-testcase-file: v1
title: "Petstore API Verification"

sources:
  - name: petstore-oas
    uri: https://petstore3.swagger.io/api/v3/openapi.yaml

plugins:
  - name: oas
  - name: json
  - name: http-dump

operations:
  createPet_Success:
    target: petstore-oas:addPet
    description: "Create a new pet with a valid payload"
    sequence: 0
    parameters:
      request:
        body:
          id: 99
          name: "bluey"
          photoUrls:
            - "https://example.com/pets/bluey.jpg"
          status: "available"
          tags:
          - id: 6
            name: bluey
    expected:
      response:
        statusCode: 200
  
  findPetsByTags_Success:
    target: petstore-oas:findPetsByTags
    description: "Find pets by tags"
    sequence: 1
    parameters:
      query:
        tags:
          - "bluey"
    expected:
      response:
        statusCode: 200

  getPetById_Success:
    target: petstore-oas:getPetById
    description: "Fetch details for pet ID 99"
    sequence: 1
    parameters:
      path:
        petId: 99
    expected:
      response:
        statusCode: 200
  
  getInventory_Success:
    target: petstore-oas:getInventory
    description: "Check if store inventory is accessible"
    sequence: 1
    expected:
      response:
        statusCode: 200
  
  updatePet_Success:
    target: petstore-oas:updatePet
    description: "Update an existing pet with a valid payload"
    sequence: 2
    parameters:
      request:
        body:
          id: 99
          name: "bluey wheeler"
          photoUrls:
            - "https://example.com/pets/bluey.jpg"
          status: "pending"
    expected:
      response:
        statusCode: 200

  deletePet_Success:
    target: petstore-oas:deletePet
    description: "Delete an existing pet"
    sequence: 3
    parameters:
      path:
        petId: 99
    expected:
      response:
        statusCode: 200

  getPetById_NotFound:
    target: petstore-oas:getPetById
    description: "Fetch details for a pet that does not exist"
    sequence: 4
    parameters:
      path:
        petId: 99
    expected:
      response:
        statusCode: 404

IDE tip: The yaml-language-server comment at the top enables auto-completion and inline validation as you type.

4. Run the verifier​

drift verify --test-files drift.yaml --server-url https://petstore.swagger.io/v2/

Viewing test results​

Drift displays a summary table showing every operation, its target, and whether it passed:

─[ Summary ]──────────────────────────────────────────────────────────────────

Executed 1 test case (1 passed, 0 failed)
Executed 7 operations (7 passed, 0 failed, 0 skipped)
Execution time 2.96938775s

┌───────────────────────────┬────────────────────────┬─────────────────────────────┬────────┐
│ Testcase                  ┆ Operation              ┆ Target                      ┆ Result │
╞═══════════════════════════╪════════════════════════╪═════════════════════════════╪════════╡
│ Petstore API Verification ┆ createPet_Success      ┆ petstore-oas:addPet         ┆ OK     │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│                           ┆ findPetsByTags_Success ┆ petstore-oas:findPetsByTags ┆ OK     │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│                           ┆ getInventory_Success   ┆ petstore-oas:getInventory   ┆ OK     │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│                           ┆ getPetById_NotFound    ┆ petstore-oas:getPetById     ┆ OK     │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│                           ┆ getPetById_Success     ┆ petstore-oas:getPetById     ┆ OK     │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│                           ┆ removePet_Success      ┆ petstore-oas:deletePet      ┆ OK     │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│                           ┆ updatePet_Success      ┆ petstore-oas:updatePet      ┆ OK     │
└───────────────────────────┴────────────────────────┴─────────────────────────────┴────────┘
note

Some tests may fail due to schema mismatches or stale test data in the shared Petstore environment. This is expected behaviour — Drift is correctly identifying a deviation from the contract. For reliable, deterministic tests, run Drift against a local or controlled environment.

If a test fails, see Debugging for how to interpret and fix failures.

What happened​

  1. Source loading — Drift fetched the OpenAPI definition from the remote URL.
  2. Contract mapping — It matched each operation ID to the corresponding endpoint in the spec (for example, getInventory_Success → GET /store/inventory).
  3. Deep validation — Drift sent the HTTP request, checked the response status code and headers, and performed a full JSON schema validation on the response body.

5. Next steps​