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"

Tip

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.

Tip

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.

In this section: