Trace File Format
Relevant source files
The following files were used as context for generating this wiki page:
Trace files are the core data artifact for Tusk Drift's record-and-replay testing system. They are structured recordings of a service's behavior, capturing live interactions such as HTTP requests, database queries, and other external calls. These recordings are then used by the tusk run command to execute deterministic, high-fidelity tests without needing live external dependencies.
Traces are stored locally as JSON Lines (.jsonl) files, typically within the .tusk/traces directory. They can also be fetched from and managed by Tusk Drift Cloud for CI/CD integration.
Sources: README.md, internal/agent/prompts/system.md
Trace Generation
Traces are generated by the Tusk Drift SDK when the service is running in RECORD mode, which is activated by setting the TUSK_DRIFT_MODE=RECORD environment variable.
The SDK automatically captures interactions, but it is selective about what it records. By default, it will only create traces for requests with a content type of application/json or text/plain. Other content types, such as text/html, are excluded from recording.
Sources: internal/agent/prompts/system.md
File Structure
Trace files use the JSON Lines format, where each line is a self-contained JSON object representing a single trace. This format is efficient for streaming and processing large numbers of traces.
By default, the CLI looks for trace files in the .tusk/traces directory.
Sources: README.md
Data Encoding and Decoding
Values within a trace are encoded to ensure they can be safely stored in JSON. The CLI uses a schema-driven approach to decode these values during replay and comparison. The primary function for this process is DecodeValueBySchema.
The decoding logic depends on two key schema properties: EncodingType and DecodedType.
Sources: internal/runner/value_decoder_test.go
Decoding Flow
The following diagram illustrates how a value from a trace file is decoded based on its associated schema.
This diagram shows the process of decoding a value from a trace, starting with checking its type and then applying decoding rules based on the provided schema's EncodingType and DecodedType.
Sources: internal/runner/value_decoder_test.go
EncodingType
The EncodingType specifies how the raw string value is encoded.
| Type | Description |
|---|---|
ENCODING_TYPE_BASE64 | The value is a Base64 encoded string. This is the default behavior if the encoding type is not specified. |
ENCODING_TYPE_UNSPECIFIED | The value is a plain text string with no additional encoding. |
Sources: internal/runner/value_decoder_test.go
DecodedType
The DecodedType informs the decoder how to interpret the data after the EncodingType has been handled. This determines the final data type for comparison.
| Type | Description | Parsed As |
|---|---|---|
DECODED_TYPE_JSON | The decoded data is a JSON object or array. | map[string]any or []any |
DECODED_TYPE_PLAIN_TEXT | The data is plain text. | string |
DECODED_TYPE_HTML, CSS, XML, JAVASCRIPT, YAML, MARKDOWN, CSV, SQL, GRAPHQL, SVG, FORM_DATA | Specific text-based formats. | string |
DECODED_TYPE_PNG, JPEG, PDF | Binary data formats. The system returns the original Base64 string for comparison, as the raw binary is not directly comparable as text. | string (original Base64) |
DECODED_TYPE_UNSPECIFIED | The type is not specified. The system first attempts to parse the data as JSON. If that fails, it falls back to treating it as a plain string. | map[string]any, []any, or string |
Sources: internal/runner/value_decoder_test.go
Trace Management via CLI
The tusk CLI provides commands to manage and execute tests using trace files. The AI Agent also uses these tools internally to verify setup.
Sources: README.md, internal/agent/executor.go
Commands and Flags
| Command/Flag | Description |
|---|---|
tusk list | Lists available recorded traces from the local trace directory. |
tusk list --cloud | Lists available tests stored in Tusk Drift Cloud. |
tusk run | Replays all recorded traces from the local trace directory. |
tusk run --trace-dir <path> | Specifies a custom directory containing trace files. |
tusk run --trace-file <path> | Specifies a single .jsonl trace file to run. |
tusk run --trace-id <id> | Runs a single test by its trace ID. |
tusk run --filter '<regex>' | Filters which traces to run based on a regular expression. |
tusk run --cloud | Fetches and replays tests from Tusk Drift Cloud. |
Sources: README.md, internal/agent/executor.go
Trace Comparison
During a tusk run, the CLI replays the recorded request against the service under test and compares the actual response with the response stored in the trace. For JSON data, this involves a deep comparison of the structured data. The CLI can generate a git-style unified diff to highlight discrepancies between the expected and actual JSON bodies.
Sources: internal/utils/text.go
Summary
The trace file format is the foundation of Tusk Drift's testing methodology. By capturing real-world interactions in a structured .jsonl format with schema-aware encoding, it enables the CLI to perform robust, deterministic, and high-fidelity replay testing. The flexibility of the format, supporting various data types from JSON to binary, ensures that a wide range of application behaviors can be accurately recorded and verified.