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 not supported.
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).

[Image of Drift source loading workflow from local and remote URIs]

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).