Embedding Drift in Your Test Framework

┌──────────────────────────────┐
│  Your Test Framework         │
│  (Jest, Playwright, etc)     │
└──────────┬───────────────────┘
           │
           │ spawns process
           │
           ▼
┌──────────────────────────────┐
│  Drift Verifier              │
│  (CLI subprocess)            │
└──────────┬───────────────────┘
           │
           │ validates
           │
           ▼
┌──────────────────────────────┐
│  Your API Server             │
│  (Express, FastAPI, etc)     │
└──────────────────────────────┘
           │
           │ uses
           │
           ▼
┌──────────────────────────────┐
│  Shared Resources            │
│  - Database                  │
│  - Mocks/Stubs               │
│  - Test Fixtures             │
└──────────────────────────────┘

Create a utility function that spawns Drift as a subprocess and captures the exit code.

Node.js/Jest Example

Create automation/drift.js:

const { spawn } = require('child_process');
const path = require('path');

const runDrift = (options = {}) => {
  const {
    testFile = './drift.yaml',
    serverUrl = 'http://localhost:8080',
    outputDir = './output',
    logLevel = 'info'
  } = options;

  return new Promise((resolve, reject) => {
    console.log(`\n📋 Running Drift tests from: ${testFile}\n`);
    
    const child = spawn('drift', [
      'verifier',
      '--test-files', testFile,
      '--server-url', serverUrl,
      '--log-level', logLevel,
      '--output-dir', outputDir
    ], {
      stdio: 'inherit',  // Shows Drift output in test output
      shell: true
    });

    child.on('error', (err) => {
      reject(new Error(`Failed to run Drift: ${err.message}`));
    });

    child.on('close', (code) => {
      resolve(code ?? 1);
    });
  });
};

module.exports = { runDrift };

Key options:

Python/pytest Example

Create automation/drift.py:

import subprocess
import sys

def run_drift(test_file='./drift.yaml', server_url='http://localhost:8080', 
              output_dir='./output', log_level='info'):
    """Run Drift verifier and return exit code"""
    
    print(f"\n📋 Running Drift tests from: {test_file}\n")
    
    result = subprocess.run([
        'drift',
        'verifier',
        '--test-files', test_file,
        '--server-url', server_url,
        '--log-level', log_level,
        '--output-dir', output_dir
    ])
    
    return result.returncodeCreate automation/drift.py:

Create a Jest test that starts your API server, then runs Drift.

Jest Example

Create tests/api.test.js:

const express = require('express');
const { runDrift } = require('../automation/drift');

// Use in-memory database for tests (no cleanup needed)
process.env.REPOSITORY_TYPE = 'inmemory';

describe('API Contract Tests', () => {
  let server;

  // Setup: Start the API server before tests
  beforeAll(async () => {
    const app = express();
    
    // Mount your API routes
    app.use(require('../src/product/routes'));
    app.use(require('../automation/test-routes')); // State mgmt routes
    
    // Start server on port 8080
    server = app.listen(8080);
    console.log('✓ API server started on http://localhost:8080');
  });

  // Cleanup: Stop the server after tests
  afterAll(async () => {
    return new Promise((resolve) => {
      server.close(resolve);
    });
  });

  // The actual test: Run Drift
  it('Validates API conforms to OpenAPI specification', async () => {
    const exitCode = await runDrift({
      testFile: './drift.yaml',
      serverUrl: 'http://localhost:8080',
      logLevel: 'debug'
    });

    // Drift exit code 0 = all tests passed
    expect(exitCode).toBe(0);
  });
});

pytest Example

Create tests/test_api_contract.py:

import subprocess
import pytest
from your_app import create_app

@pytest.fixture(scope='module')
def api_server():
    """Start API server for the test module"""
    app = create_app(config='testing')
    app.config['REPOSITORY_TYPE'] = 'inmemory'
    
    # Run in debug mode
    server = app.run(port=8080, debug=False)
    yield server
    server.shutdown()

def test_api_conforms_to_openapi(api_server):
    """Drift validates the API against its OpenAPI spec"""
    from automation.drift import run_drift
    
    exit_code = run_drift(
        test_file='./drift.yaml',
        server_url='http://localhost:8080',
        log_level='debug'
    )
    
    assert exit_code == 0, "Drift tests failed"

The Drift tests can use the state management pattern from the managing state tutorial.

Your drift.yaml stays the same:

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

sources:
  - name: source-oas
    path: ./openapi.yaml
  - name: state-mgmt
    path: ./state-management.lua

plugins:
  - name: oas
  - name: json

global:
  auth:
    apply: true
    parameters:
      authentication:
        scheme: bearer
        token: ${state-mgmt:bearer_token}

operations:
  getProductByID_Success:
    target: source-oas:getProductByID
    parameters:
      path:
        id: 10
    expected:
      response:
        statusCode: 200

The state-management.lua script (from the previous tutorial) handles setup/teardown automatically.

# Run all tests (unit + Drift contract tests)
npm test

# Run only API contract tests
npm test -- api.test.js

# Run with specific log level
LOG_LEVEL=debug npm test

Output:

PASS tests/api.test.js
  API Contract Tests
    ✓ Validates API conforms to OpenAPI specification (2345ms)

    Running Drift tests from: ./drift.yaml

    ✓ getProductByID_Success
    ✓ getProductByID_NotFound
    ✓ createProduct_Success
    ✓ deleteProduct_Success

Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total

You can run Drift against different configurations:

describe('API Contract Tests', () => {
  // Test with in-memory database
  it('Works with in-memory database', async () => {
    process.env.REPOSITORY_TYPE = 'inmemory';
    const exitCode = await runDrift();
    expect(exitCode).toBe(0);
  });

  // Test with PostgreSQL
  it('Works with PostgreSQL', async () => {
    process.env.REPOSITORY_TYPE = 'postgres';
    process.env.DATABASE_URL = 'postgres://test:test@localhost/testdb';
    
    const exitCode = await runDrift({
      testFile: './drift-postgres.yaml'
    });
    expect(exitCode).toBe(0);
  });

  // Test specific tags only
  it('Smoke tests pass', async () => {
    const exitCode = await runDrift({
      // Use --tags flag in drift command
      testFile: './drift.yaml'
      // Would need to enhance runDrift() to support --tags
    });
    expect(exitCode).toBe(0);
  });
});

If you have existing test setup (fixtures, database seeding, etc.), Drift reuses it:

describe('Product API', () => {
  let database;
  let server;

  beforeAll(async () => {
    // Your existing setup
    database = await setupTestDatabase();
    await seedTestData(database);
    
    server = startServer(database);
  });

  // Your existing tests
  it('Creates a product', async () => {
    const response = await fetch('http://localhost:8080/products', {
      method: 'POST',
      body: JSON.stringify({ name: 'Test' })
    });
    expect(response.status).toBe(201);
  });

  // Drift test - uses same database and server
  it('Validates API contract with Drift', async () => {
    const exitCode = await runDrift();
    expect(exitCode).toBe(0);
  });

  afterAll(async () => {
    server.close();
    await database.close();
  });
});

In your CI pipeline, Drift runs like any other test:

GitHub Actions

name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s

    steps:
      - uses: actions/checkout@v3
      
      - name: Install Drift
        run: |
          wget -O - https://download.pactflow.io/drift/latest/linux-x86_64.tgz | tar xz -C /usr/local/bin
          drift --version
      
      - name: Install dependencies
        run: npm install
      
      - name: Run all tests (including Drift)
        run: npm test
        env:
          NODE_ENV: test
          DATABASE_URL: postgres://postgres:test@localhost/testdb

GitLab CI

test:
  image: node:20
  services:
    - postgres:15
  script:
    - wget -O - https://download.pactflow.io/drift/latest/linux-x86_64.tgz | tar xz -C /usr/local/bin
    - drift --version
    - npm install
    - npm test
  variables:
    POSTGRES_DB: testdb
    POSTGRES_PASSWORD: test

This approach provides a single test runner with shared infrastructure, unified reporting, faster feedback on API contract issues, simpler maintenance through one repository and deployment flow, and a better developer experience with a single npm test command for all tests.

Check the most common issues.

beforeAll(async () => {
  server = app.listen(8080);
  // Give server time to start
  await new Promise(resolve => setTimeout(resolve, 100));
});Ensure the server is started before Drift tests run:

lsof -i :8080
# Kill if needed: kill -9 <PID>

which drift
# If not found, install or add to PATH
export PATH="/path/to/drift:$PATH"

console.log('NODE_ENV:', process.env.NODE_ENV);
console.log('REPOSITORY_TYPE:', process.env.REPOSITORY_TYPE);

The full implementation is available in the example repository. View the complete example project.

This includes:

Lifecycle Hooks. Learn about event handlers in Drift.

CI/CD Integration. Deploy Drift tests in your pipeline.

Debugging. Troubleshoot failing tests.

Testing with State Dependencies. The previous tutorial on state management.