Skip to main content
Swagger
All documentation pages

Drift YAML Reference

The drift.yaml file is the primary declarative manifest for your test suite. It is defined as a V1TestCaseDocument and coordinates your sources, plugins, and operations.

IDE Auto-completion & Validation

Drift test case files support JSON Schema validation in IDEs and editors. This provides:

  • Auto-completion for property names and values

  • Inline validation with error highlighting

  • Hover documentation for each field

  • Type checking to catch errors before running tests

Enabling Schema Support

Add a YAML Language Server comment directive at the top of your drift.yaml file:

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

sources:
  - name: api-spec
    path: ./openapi.yaml

operations:
  getProduct_Success:
    target: api-spec:getProduct
    expected:
      response:
        statusCode: 200

Supported Editors:

  • VS Code (with YAML extension)

  • IntelliJ IDEA / PyCharm / WebStorm

  • Neovim with yaml-language-server

  • Any editor with YAML Language Server Protocol support

Alternative: $schema Property

Some editors also support the $schema property, though this is less commonly used:

$schema: https://download.pactflow.io/drift/schemas/drift.testcases.v1.schema.json
drift-testcase-file: v1
title: "My API Tests"

The YAML Language Server comment directive is the most widely supported method and works across virtually all modern editors with YAML support.

Root Properties

Property Type Description
drift-testcase-file String Required. Must be v1. Expressions are not supported here.
title String A descriptive name for the test suite. Supports expressions.
sources Array List of files (OpenAPI, Lua, Datasets) or URIs. Supports expressions in paths, URIs, and names.
plugins Array List of enabled plugins (e.g., oas, json). Supports expressions in config.
global Object Shared config applied to all operations. Supports expressions in parameters and values.
operations Object Required. The individual test case definitions. Supports expressions except in operation keys.

Expression Support: Most string values support expressions like ${env:VARIABLE}, ${functions:name}, or ${dataset:path}. See Data Expressions for details on where and how to use them.

Sources

Sources define where Drift retrieves specifications, data, and scripts.

Property Type Description
name String Required. A unique identifier (e.g., product-oas).
path String Local filesystem path to the file.
uri String Remote URL to the file (Not supported for Lua scripts).
auth Object Credentials for remote URIs (username and secret).

Remote Source Authentication

You can provide credentials directly in the sources block using plain text or environment variable injection.

sources:
  - name: product-oas
    uri: http://localhost:8000/openapi.yaml
    auth:
      username: ${env:LOCAL_USERNAME}
      secret: ${env:LOCAL_PASSWD}

Operations

Each key in the operations block is a unique test identifier.

  • target: Points to a specific endpoint (Format: source:operationId or source:method:path).

  • dataset: (Optional) The name of the dataset source to reference for this test.

  • parameters: Key-value pairs for path, query, headers, or request body.

  • expected: The validation values, typically specifying the response and statusCode.

  • sequence: (Optional, Integer) Controls the order in which operations are executed.

    • Operations with a negative sequence value run first, ordered by their sequence value (more negative first), then by key to break ties.

    • Operations with null or no sequence run next, ordered by key (default behavior).

    • Operations with a zero or positive sequence value run last, ordered by their sequence value, then by key to break ties.

    • When two operations have the same sequence, the key is used as a deterministic tie-breaker for stable ordering.

    • Useful for setup/teardown or stateful test scenarios. See How to Control Test Execution Order.

  • tags: (Optional, Array of Strings) Tag names to apply to this operation. Tags allow you to group and filter tests (e.g., smoke, security). No punctuation or whitespace allowed. See Organizing Tests with Tags.

  • ignore: (Optional, Object) Validation errors to ignore for this operation. Useful for negative testing (e.g., ignoring schema errors when sending invalid requests). See Testing Negative Scenarios.

  • description: (Optional, String) A human-readable description of what this test validates. Helps document intent and is shown in test output.

  • exclude: A list of global configuration keys to ignore for this specific test.

  • include: A list of global configuration keys to include for this specific test. Use this for globals that are not applied by default (i.e., they have apply: false).

Async operation fields

The following operation fields apply to AsyncAPI operations. See Using Triggers and Probes.

Field Type Description
trigger HookSpec Hook that causes the system under test to produce a message. Used by async-observe and async-inject-capture.
probe HookSpec Hook executed after the operation to interrogate system state. Used by async-inject.
publish-trigger HookSpec Hook that publishes the message in place of the transport plugin. Used by async-inject only. Must return JSON containing a correlation identifier.

HookSpec

A hook specification describes a command or Lua function that Drift runs at a defined point in an async operation.

Field Type Required Description
executable-type string Yes Selects the runtime. command spawns an external process. lua-function calls an exported Lua function.
value string Yes The executable path for command, or the function name for lua-function.
timeout-ms integer No Maximum time to wait for the hook. Falls back to the operation’s parameters.timeout-ms.
parameters map No Executor-specific parameters. For command, parameters.args is the argument list.
trigger:
  executable-type: command
  value: python3
  parameters:
    args:
      - ../hooks/trigger-send.py
      - --correlation-id
      - ${parameters.correlation-id}
  timeout-ms: 2000

Paths are resolved relative to the test case file. A command that exits non-zero fails the operation. Binding expressions are resolved in value and in parameters.

AsyncAPI parameters

Parameter Type Description
payload map The message payload Drift publishes
headers map Message headers Drift sets on publish
correlation-id string Identifies the message for this test
timeout-ms integer The capture window in milliseconds. Defaults to 30000.
probe-topic string Selects async-inject-capture and names the topic to capture from
execution-mode string Overrides automatic mode selection. One of async-observe, async-inject, async-inject-capture, async-request-reply.
reply-channel string Names a reply channel when the AsyncAPI document does not declare one
region string AWS region. aws-messaging plugin only.
aws.endpoint-url string Endpoint override for LocalStack or another emulator. aws-messaging plugin only.

Was this page helpful?