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:operationIdorsource:method:path). -
dataset: (Optional) The name of the dataset source to reference for this test. -
parameters: Key-value pairs forpath,query,headers, orrequestbody. -
expected: The validation values, typically specifying theresponseandstatusCode. -
sequence: (Optional, Integer) Controls the order in which operations are executed.-
Operations with a negative
sequencevalue run first, ordered by theirsequencevalue (more negative first), then by key to break ties. -
Operations with
nullor no sequence run next, ordered by key (default behavior). -
Operations with a zero or positive
sequencevalue run last, ordered by theirsequencevalue, 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 ofglobalconfiguration keys to ignore for this specific test. -
include:A list ofglobalconfiguration keys to include for this specific test. Use this for globals that are not applied by default (i.e., they haveapply: 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. |