Writing Test Cases

To test authentication failures, you need to override or exclude the global authentication:

operations:
  # Using exclude to remove global auth
  getAllProducts_Unauthorized:
    target: source-oas:getAllProducts
    description: "Get all products with invalid authorization"
    exclude:
      - auth
    parameters:
      headers:
        authorization: "Bearer invalid-token"
    expected:
      response:
        statusCode: 401

The exclude field removes globally applied configuration (like authentication headers), allowing you to test what happens when auth is missing or invalid.

Test invalid input by providing malformed data:

operations:
  getProductByID_InvalidID:
    target: source-oas:getProductByID
    description: "Get a product with invalid ID format"
    parameters:
      path:
        id: "invalid"  # Send string where integer expected
    expected:
      response:
        statusCode: 400

When testing bad requests, you're deliberately sending invalid data to verify the API rejects it. However, Drift will normally validate your request against the OpenAPI schema and report errors when you send malformed data.

To silence schema validation errors for bad request tests, use the ignore: schema field:

operations:
  createProduct_MissingRequired:
    target: source-oas:createProduct
    description: "Create product without required fields"
    parameters:
      request:
        body:
          price: 9.99  # Missing required 'name' field
      ignore:
        schema: true  # Ignore request schema validation errors
    expected:
      response:
        statusCode: 400

This prevents Drift from reporting schema validation errors for intentionally invalid requests while still validating the response schema, making it useful for testing validation errors, malformed inputs, and API error handling.

Verify the API returns 404 for non-existent resources:

operations:
  getProductByID_NotFound:
    target: source-oas:getProductByID
    description: "Get a product that does not exist"
    parameters:
      path:
        id: 99999  # ID that doesn't exist
    expected:
      response:
        statusCode: 404
        

The exclude field removes globally applied configuration (like authentication headers), allowing you to test what happens when auth is missing or invalid.

Test authorization (not authentication) by using a valid token with insufficient permissions:

operations:
  deleteProduct_Forbidden:
    target: source-oas:deleteProduct
    description: "Delete product with read-only token"
    parameters:
      headers:
        authorization: "Bearer ${functions:readonly_token}"
      path:
        id: 10
    expected:
      response:
        statusCode: 403
        

The exclude field removes globally applied configuration (like authentication headers), allowing you to test what happens when auth is missing or invalid.

global:
  auth:
    apply: true  # Automatically applies to all operations
    parameters:
      authentication:
        scheme: bearer
        token: ${functions:bearer_token}

When testing negative cases, use exclude to remove specific global settings:

operations:
  createProduct_Unauthorized:
    target: source-oas:createProduct
    description: "Create product without authentication"
    exclude:
      - auth  # Don't apply the global auth config
    parameters:
      headers:
        authorization: "Bearer invalid-token"
    expected:
      response:
        statusCode: 401

Using exclude keeps test files DRY, clearly indicates when a test intentionally differs from the default setup, and prevents unwanted configuration from being inherited.

operations:
  getAllProducts_Success:
    target: source-oas:getAllProducts
    tags:
      - smoke
      - products
      - read-only
    expected:
      response:
        statusCode: 200

  createProduct_Success:
    target: source-oas:createProduct
    tags:
      - products
      - write
    expected:
      response:
        statusCode: 201

  getProductByID_Unauthorized:
    target: source-oas:getProductByID
    tags:
      - security
      - auth
    exclude:
      - auth
    expected:
      response:
        statusCode: 401

For more details about CLI tag filtering behavior, see Debugging Test Cases.

# Run only smoke tests
drift verifier --test-files drift.yaml --tags smoke

# Run all security tests
drift verifier --test-files drift.yaml --tags security

# Run tests with multiple tags (OR logic)
drift verifier --test-files drift.yaml --tags products,write

# Exclude certain tags (NOT logic)
drift verifier --test-files drift.yaml --tags '!security'

Common tag strategies:

You can add an optional sequence field to any operation to control its execution order: negative values run first (lowest to highest), followed by unsequenced operations ordered by key, then zero or positive values in ascending order, with ties resolved alphabetically by key.

Example: Setup, Main, and Cleanup

operations:
  setupDatabase:
    target: source-oas:setupDatabase
    description: "Prepare database for tests"
    sequence: -10  # Runs first
    expected:
      response:
        statusCode: 200

  createProduct:
    target: source-oas:createProduct
    description: "Create a product"
    # No sequence: runs after negative, before positive
    expected:
      response:
        statusCode: 201

  getProduct:
    target: source-oas:getProduct
    description: "Get the created product"
    # No sequence: runs after negative, before positive
    expected:
      response:
        statusCode: 200

  cleanup:
    target: source-oas:cleanup
    description: "Clean up test data"
    sequence: 10  # Runs last
    expected:
      response:
        statusCode: 204

Grouping Operations

If you assign the same sequence number to multiple operations, they form a group. The group runs in sequence order, and within the group, operations are ordered by key:

operations:
  stepA:
    sequence: 1
    # ...
  stepB:
    sequence: 1
    # ...
  stepC:
    sequence: 2
    # ...

Here, stepA and stepB run together (ordered by key), then stepC.

Use sequence for setup or teardown steps, state-dependent tests, and cleaner ordering without numeric key prefixes; for more advanced workflows or complex dependencies, use Lua scripting or integrate with your test framework.

Consider this test that expects a product to exist:

operations:
  deleteProduct_Success:
    target: source-oas:deleteProduct
    description: "Delete an existing product"
    parameters:
      path:
        id: 10  # Assumes product ID 10 exists!
    expected:
      response:
        statusCode: 204

If product ID 10 doesn't exist the test will fail unpredictably. For scenarios requiring setup or cleanup, use lifecycle hooks in Lua scripts:

-- product.lua
local exports = {
  event_handlers = {
    ["operation:started"] = function(event, data)
      -- Create test product before the operation runs
      local res = http({
        url = "http://localhost:8080/products",
        method = "POST",
        body = json.encode({id = 10, name = "Test Product"})
      })
    end,

    ["operation:finished"] = function(event, data)
      -- Clean up after the test completes
      http({
        url = "http://localhost:8080/products/10",
        method = "DELETE"
      })
    end
  }
}

return exports