https://github.com/use-tusk/tusk-drift-cli
Record traces from your live traffic and replay them as API tests
https://github.com/use-tusk/tusk-drift-cli
api-testing mock test-automation test-automation-framework test-generation testing testing-library traffic-replay
Last synced: 4 days ago
JSON representation
Record traces from your live traffic and replay them as API tests
- Host: GitHub
- URL: https://github.com/use-tusk/tusk-drift-cli
- Owner: Use-Tusk
- License: apache-2.0
- Created: 2025-09-29T22:45:55.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-12-07T21:11:31.000Z (about 1 month ago)
- Last Synced: 2025-12-08T05:50:09.661Z (about 1 month ago)
- Topics: api-testing, mock, test-automation, test-automation-framework, test-generation, testing, testing-library, traffic-replay
- Language: Go
- Homepage: https://www.usetusk.ai/tusk-drift
- Size: 9.45 MB
- Stars: 60
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
Tusk Drift is an API test record/replay system that lets you run realistic tests generated from real traffic. This CLI orchestrates local and CI test runs, coordinating with a Tusk Drift SDK and Tusk Drift Cloud.
[](https://github.com/Use-Tusk/tusk-drift-cli/actions/workflows/main.yml)
[](https://www.bestpractices.dev/projects/11340)
[](https://securityscorecards.dev/viewer/?uri=github.com/Use-Tusk/tusk-drift-cli)
[](https://goreportcard.com/report/github.com/Use-Tusk/tusk-drift-cli)
[](https://opensource.org/licenses/Apache-2.0)
[](https://x.com/usetusk)
[](https://join.slack.com/t/tusk-community/shared_invite/zt-3fve1s7ie-NAAUn~UpHsf1m_2tdoGjsQ)
SDKs:
- [Node.js](https://github.com/Use-Tusk/drift-node-sdk)
- ...more to come!
## Features
- Replay recorded traces against your service under test
- Deterministic outbound I/O via local mock server
- JSON response comparison with dynamic field rules (UUIDs, timestamps, dates, etc.)
- Tusk Drift Cloud: fetch and replay tests stored with Tusk, and upload test results for intelligent classification of regressions in CI/CD checks
## Install
### Quick install (recommended)
**Linux/macOS:**
Install the latest version:
```bash
curl -fsSL https://cli.usetusk.ai/install.sh | sh
```
To install a specific version:
```bash
curl -fsSL https://cli.usetusk.ai/install.sh | sh -s -- v1.2.3
```
Linux additional dependencies (for replay sandboxing):
- Debian/Ubuntu: `sudo apt install bubblewrap socat`
- Fedora/RHEL: `sudo dnf install bubblewrap socat`
- Arch: `sudo pacman -S bubblewrap socat`
Without these, sandboxing is disabled and replays run without network isolation. See [Architecture - Sandboxing](docs/architecture.md#sandboxing-with-fence).
**Homebrew:**
Coming soon.
**Windows:**
We recommend using [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) for the best experience on Windows. With WSL, you can use the Linux/macOS installation steps above and avoid Windows-specific configuration. For native Windows installation without WSL, expand below to see the steps.
Installation steps
Download the latest release from [GitHub Releases](https://github.com/Use-Tusk/tusk-drift-cli/releases/latest):
1. Download `tusk-drift-cli_*_Windows_x86_64.zip` (or `arm64` for ARM-based Windows)
2. Extract the ZIP file
3. Move `tusk.exe` to a directory in your PATH (e.g., `C:\tools\`), or add the extracted directory to your PATH:
**Option A: Add to PATH via PowerShell (run as Administrator):**
```powershell
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\path\to\tusk", "User")
```
**Option B: Add to PATH via System Settings:**
- Press `Win + R`, type `sysdm.cpl`, press Enter
- Click "Environment Variables"
- Under "User variables", select `Path` and click "Edit"
- Click "New" and add the folder containing `tusk.exe`
- Click OK to save
4. Restart your terminal and verify:
```powershell
tusk --version
```
Note: Windows requires additional configuration for running tests. See [Windows Support](docs/configuration.md#windows-support) for details on TCP communication mode setup.
### Manual Download
Download pre-built binaries from [GitHub Releases](https://github.com/Use-Tusk/tusk-drift-cli/releases/latest).
### Build from source
```bash
# Go 1.25+
git clone https://github.com/Use-Tusk/tusk-drift-cli.git
cd tusk-drift-cli
make deps
make build
tusk --help
```
## Quick start
Initialize a service:
```bash
cd path/to/your/service
tusk init
```
An onboarding wizard will guide you to create your `.tusk/config.yaml` config file.
You can also create the `.tusk` directory and config file manually in your root directory of your service. See [configuration docs](/docs/configuration.md).
You will need to record traces for your service. See your respective SDK's guide for more details. Once you have traces recorded, you can replay them with the `tusk run` command.
Local traces (default):
```bash
# Run all tests from local traces
tusk run
# Or specify source
tusk run --trace-dir .tusk/traces
tusk run --trace-file path/to/trace.jsonl
tusk run --trace-id
# Common flags
tusk run --filter '^/api/users' --concurrency 10 --enable-service-logs
tusk run --save-results --results-dir .tusk/results
```
## ✨ Tusk Drift Cloud
You can use Tusk Drift as API tests in your CI/CD pipeline by running your test suite against commits in your pull requests. Tusk Drift Cloud offers storage of these tests alongside an additional layer of intelligence on deviations detected:
- Automatic recording of traces based on live traffic in your environment of choice
- Securely store these traces as test suites
- Analyze deviations (classification of intended vs unintended deviations), root cause of deviations against your code changes, and suggested fixes.
We provide an onboarding wizard to help you get started quickly:
```bash
tusk cloud-init
```
For more details, dive into [Tusk Drift Cloud docs](./docs/cloud/).
## Usage
List traces:
```bash
# Local traces
tusk list
tusk list --trace-dir .tusk/traces
# With Tusk Drift Cloud
tusk list --cloud
```
Interactive TUI (default when attached to a terminal):
```bash
tusk run
# Run against Tusk Drift Cloud
tusk run --cloud
tusk run --cloud --trace-test-id # single test from backend
tusk run --cloud --all-cloud-trace-tests # run all tests for service
```
The TUI is best viewed in a window size of at least 150 x 40.
Run headless mode with JSON output for a single test:
```bash
tusk run --trace-id --print --output-format=json
```
How this program uses your `.tusk` directory:
- Recordings of your app's traffic will be stored in `.tusk/traces` by default.
Specify `traces.dir` in your `.tusk/config.yaml` to override.
- If `--save-results` is provided, results will be stored in `.tusk/results` by default. Specify `results.dir` in your `.tusk/config.yaml` to override.
- If `--enable-service-logs` or `--debug` is used, trace replay service logs will be stored in `.tusk/logs`.
We recommend adding to your `.gitignore`:
- `.tusk/results`
- `.tusk/logs`
- `.tusk/traces` (if you primarily intend to use Tusk Drift Cloud)
## Resources
- [Architecture overview](docs/architecture.md)
- [Configuration](docs/configuration.md)
- [Troubleshooting](docs/troubleshooting.md)
## Community
Join our open source community on [Slack](https://join.slack.com/t/tusk-community/shared_invite/zt-3fve1s7ie-NAAUn~UpHsf1m_2tdoGjsQ).
## Development
See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
## License
See [`LICENSE`](./LICENSE).