Configuring Drift

Drift is flexible: you can configure the engine and its plugins via command-line parameters, environment variables, or configuration files (TOML, YAML, JSON, INI, JSON5, or RON).

1. Configuration Priority

If a value is defined in multiple places, Drift uses this precedence order:

1. Command-line parameters (highest priority)
2. Environment variables
3. Configuration files (lowest priority)

2. Configuration Files

Drift supports these configuration file formats:

• TOML: drift.config.toml (Tom's Obvious Minimal Language)
• YAML: drift.config.yaml (YAML Ain't Markup Language)
• JSON: drift.config.json (JavaScript Object Notation)
• INI: drift.config.ini (Windows INI format)
• JSON5: drift.config.json5 (JSON for Humans)
• RON: drift.config.ron (Rusty Object Notation)

Search Order

Drift searches for configuration files in the following order (for any supported format above):

1. OS Config Directory:
   • Linux: $XDG_CONFIG_HOME or $HOME/.config/drift.config.{ext}
   • macOS: $HOME/Library/Application Support/drift.config.{ext}
   • Windows: %APPDATA%\drift.config.{ext}
2. User Home: $HOME/.drift/drift.config.{ext}
3. Application Home: The home_dir identified in the next section

Example Configuration File (TOML)

log_level = "info" # default the logging to INFO level
plugin_dir = "~/.drift/plugins" # override directory where the plugins are installed

[log_filters]
hyper_util = "info"
wasmtime_wasi = "info"

[plugin_config.json]
content_types = ["application/thrift"]

3. The Application Home Directory (home_dir)

The home_dir is the central location where Drift looks for executables, plugins, and configuration files. It is determined in the following order:

1. The --drift-home-dir command-line parameter
2. The DRIFT_HOME_DIR environment variable
3. The directory where the Drift executable is run from
4. The current working directory

4. Environment Variables

Any simple, non-collection configuration value can be specified as an environment variable using the prefix DRIFT_ followed by the setting name in SCREAMING_SNAKE_CASE.

• Example: To set the logging level, use LOG_LEVEL=DEBUG.

PactFlow Authentication (Required)

Drift requires authentication to PactFlow or a Pact Broker to manage contracts and test workflows. Set these credentials as environment variables:

export PACT_BROKER_BASE_URL="https://your-workspace.pactflow.io"
export PACT_BROKER_TOKEN="your-api-token"

Where to get your token: Navigate to Settings → API Tokens in your PactFlow workspace.

Token types:

• Read-only tokens: Suitable for local development and CI/CD pipelines that only read contracts
• System account tokens: For CI/CD pipelines that publish contracts; requires appropriate permissions

See Authentication for more details on token types and PactFlow documentation for roles and permissions.

5. Core Configuration Values

Value	Default	Description
log_level	INFO	The logging level: TRACE, DEBUG, INFO, WARN, ERROR.
log_filters		Filter log entries based on target or spans.
home_dir	See Section 3	Drift application home directory.
output_dir		Directory where output files (like reports) are written.
plugin_dir	home_dir/plugins	Directory where plugins are loaded from.
core_plugins		A list of plugins that are always loaded automatically.
servers		Server authentication configuration (see Section 7).

6. Plugin Directory Logic

If not explicitly configured, the plugin_dir defaults to a folder named plugins within your home_dir. This is where standard plugins (OAS, JSON, Data, etc.) are expected to reside.

7. Server Authentication for Remote Sources

Drift allows you to manage credentials for remote URIs outside of your testcase files for improved security.

Using a Configuration File

Define server credentials in your config file. Drift uses a longest-match algorithm to find the correct credentials based on the source URL.

[servers.0]
url = "http://localhost:8000"
username = "lloyd"
secret = "chimps"

[servers.1]
url = "http://localhost:8000/secret"
username = "lloyd2"
secret = "monkeys"

Each server entry supports:

• url (required): The base URL for the server
• scheme: Authentication scheme - basic (default), bearer, or api-key
• header: Header to use (defaults to authorization for most schemes, x-api-key for api-key)
• username: Username for basic authentication
• secret (required): Password (basic), token (bearer), or API key (api-key)