Tutorials

Getting Started

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.

Note

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.

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 our Installation Guide for manual installation, verification steps, and troubleshooting.

Authenticate

Drift requires a Swagger Contract Testing account to run. Log in with:

drift auth login

Enter your Swagger Contract Testing 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 Swagger Contract Testing workspace under Settings > API Tokens. If you do not have an account, sign up for a free trial.

Create Test Suite

Create a file named drift.yaml. This points Drift to the Petstore OpenAPI definition and define a few simple 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

Tip

Tip: The yaml-language-server comment at the top enables auto-completion and validation in your editor. As you type, you'll see suggestions for property names and valid values.

Run the Verifier

Run the drift verifier command. We will use the Petstore virtual server as our target URL.

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

Drift displays results in a clear table format:

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

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

┌───────────────────────────┬────────────────────────┬─────────────────────────────┬────────┐
│ 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 the schema or other mismatches due to bad test data entered into the system. In this case - Drift is highlighting a problem. This also highlights why Drift is best run against a local, or controllable environment, so that you can have more reliable and deterministic tests.

Each row shows an operation, its target, and the result (OK or FAILED). The summary at the top tells you how many test cases and operations passed.

If a test fails, you'll see a Failures section with details about what went wrong. See Debugging for how to interpret and fix failures.

What Happened Behind the Scenes

Source Loading: Drift fetched the oas.yaml from the remote URL.
Contract Mapping: It mapped each operation to the endpoint in the spec, for example getInventory_Success mapped to /store/inventory.
Deep Validation: Drift executed the HTTP request, checked the response status codes and headers, and performed a full JSON schema validation on the response to ensure it matches the Petstore model.

In this section:

Tutorials

Getting Started

Note

Authenticate

Create Test Suite

Tip

Run the Verifier

Note

Search results