Command: tusk run
Relevant source files
The following files were used as context for generating this wiki page:
The tusk run command is the core execution engine for replaying recorded traces against a service. It orchestrates the entire test run, from starting the service under test and its mocked dependencies to replaying requests, comparing responses, and reporting results. This command can be run in an interactive TUI mode for local development or in a headless "print" mode suitable for CI/CD pipelines.
The command can execute tests from local trace files or from tests stored in Tusk Drift Cloud. It is a central piece of the Tusk Drift workflow, enabling developers to validate that their service behaves consistently by using realistic data captured from live environments.
Sources: README.md, cmd/short_docs/run.md
Execution Flow
The tusk run command follows a structured process to execute tests. It begins by loading configuration and tests, then sets up the test environment, runs the tests, and finally reports the results before cleaning up.
This diagram illustrates the high-level execution flow of the tusk run command.
Usage and Flags
The tusk run command supports various flags to control its behavior, such as specifying the source of traces, filtering tests, and configuring the output format.
| Flag | Description | Default |
|---|---|---|
--trace-dir | Directory to load traces from. | .tusk/traces |
--trace-file | Path to a single trace file to run. | |
--trace-id | A specific trace ID to run. | |
--cloud | Run tests from Tusk Drift Cloud. | false |
--filter | A regex pattern to filter which tests to run. | |
--concurrency | Number of tests to run in parallel. | |
--enable-service-logs | Save service logs to .tusk/logs. | false |
--save-results | Save test results to a specified directory. | false |
--results-dir | Directory to save test results. | .tusk/results |
--print | Run in headless mode and print results to stdout. | false |
--output-format | Output format for headless mode (e.g., json). | |
--debug | Enable debug output. | false |
Sources: README.md, cmd/run.go
Core Components
Test Runner (runner.Executor)
The runner.Executor is the internal component responsible for managing the test execution lifecycle. It is used by both the tusk run command and the AI agent's tusk_run tool. Its key responsibilities include:
- Loading tests from local trace files.
- Starting and stopping the test environment, which includes the user's service.
- Executing tests, which involves replaying HTTP requests and comparing the actual responses against the recorded ones.
- Managing concurrency of test runs.
Sources: internal/agent/tools/tusk.go:40-41, internal/agent/tools/tusk.go:80-81
Test Loading
Tests can be loaded from multiple sources:
- Local Directory: By default,
tusk runloads all trace files from the.tusk/tracesdirectory. This can be overridden with the--trace-dirflag or thetraces.dirsetting in.tusk/config.yaml. - Single Local File: The
--trace-fileflag allows running a single test from a specific.jsonlfile. - Tusk Drift Cloud: Using the
--cloudflag, the command fetches and runs tests stored in the Tusk Drift Cloud service.
Sources: README.md, internal/agent/tools/tusk.go:44-53, internal/tui/onboard/config.go:101-103
Test Filtering
The --filter flag allows users to select a subset of tests to run using a regular expression. The regex is matched against the test's display name, which typically includes the HTTP method and path (e.g., GET /api/users). This is useful for focusing on specific endpoints during development or debugging.
The filtering logic is implemented in the FilterTests function, which iterates through the loaded tests and returns only those that match the provided pattern.
Sources: internal/runner/filter.go, internal/agent/tools/tusk.go:127-133
Execution Modes
Interactive TUI
When run from an interactive terminal, tusk run defaults to a Terminal User Interface (TUI). This mode provides a real-time view of test progress, results, and logs. The TUI is recommended for local development and is best viewed in a terminal window of at least 150x40 characters.
Sources: README.md
Headless / Print Mode
For CI/CD environments or scripting, tusk run can be executed in a headless mode using the --print flag. In this mode, results are printed directly to standard output. The --output-format=json flag can be used to get structured JSON output, which is ideal for programmatic processing of test results.
Sources: README.md
AI Agent Integration
The experimental AI agent (tusk exp init) uses the tusk run functionality to verify its setup steps. It does not call the CLI command directly but instead uses an internal tusk_run tool that leverages the same runner.Executor.
tusk_run Tool Definition
The agent's capabilities are defined by a set of tools. The tusk_run tool allows the agent to execute tests and receive the results.
{
"name": "tusk_run",
"description": "Run 'tusk run' to replay recorded traces and verify the service behaves consistently. Returns test results.",
"input_schema": {
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Optional filter pattern for traces (regex)"
},
"debug": {
"type": "boolean",
"description": "Enable debug logging for troubleshooting"
}
}
}
}
Sources: internal/agent/executor.go:343-361
Agent Execution Sequence
The following diagram shows how the AI agent uses the tusk_run tool to test the service configuration.
Summary
The tusk run command is the primary mechanism for validating service behavior in the Tusk Drift ecosystem. It provides a flexible and powerful way to replay recorded traffic, with modes suitable for both interactive local development (TUI) and automated CI/CD pipelines (headless). Its integration with the AI agent for automated setup underscores its central role in the Tusk Drift testing lifecycle.
Sources: README.md, cmd/short_docs/run.md