Welcome to the Tusk Drift demo! This repository demonstrates how Tusk Drift automatically generates API tests from real traffic, helping you catch regressions before they reach production.
π Get started in under 2 minutes
This demo includes a simple Express.js API service that integrates with external APIs. You'll:
- β Run realistic API tests in seconds (no setup needed!)
- π See how Tusk catches bugs by detecting API behavior changes
- π Learn how to record your own tests from real traffic
- βοΈ Discover Tusk Cloud's intelligent test suite management
Both use the same open-source CLI and SDK. This demo shows the standalone workflow.
Record traces locally, save them to .tusk/traces/, and replay with tusk run. You manage which traces to keep.
Saves time vs. writing API tests manually.
Record from dev/production (at low sampling rates), and Cloud handles trace curation automatically. When you run tusk run in CI, it pulls your curated suite from Cloud and reports results. If tests fail, you get PR comments showing what changed and suggested fixes.
A self-maintaining API test suite based on actual traffic.
- Node.js v22.18.0+ (we recommend using nvm)
- npm
Open this demo repo in a new GitHub Codespace. Wait 2 minutes for the setup script to automatically install the Tusk CLI and all dependencies.
Alternatively, you can clone the repo and install dependencies manually:
# Clone the repository
git clone https://github.com/Use-Tusk/drift-node-demo.git
cd drift-node-demo
# Install Node.js version (if using nvm)
nvm use
# Install dependencies
npm installNote
Skip this step if you created a GitHub Codespace for this demo repo.
macOS/Linux:
curl -fsSL https://raw.githubusercontent.com/Use-Tusk/tusk-drift-cli/main/install.sh | shWindows:
Download the latest release from Tusk CLI Releases
Full installation guide: Tusk CLI Installation
This repository includes pre-recorded test traces from real API traffic (in .tusk/traces/), so you can see Tusk Drift in action immediately without recording anything yourself.
# Run all pre-recorded API tests
tusk runYou should see output showing tests running against the Express server with deterministic mocks.
π Success! You just replayed real API tests with zero setup.
Note: These tests were recorded from actual API calls made to this service. Later in this guide, we'll show you how to record your own tests from scratch.
This demo repo includes:
- Express.js Server (
server.ts) - API service with multiple external integrations - Pre-recorded Traces (
.tusk/traces/) - Real API call recordings in JSONL format - Tusk Configuration (
.tusk/config.yaml) - Service configuration for test replay
When you run tusk run, the CLI:
- Starts your Express server (using configuration in
.tusk/config.yaml) - Replays the recorded inbound HTTP requests
- Mocks all outbound requests (external APIs or database calls) using recorded responses
- Compares actual vs. expected API responses
- Reports any deviations
Want to see Tusk catch a bug? Open this new codespace or switch to buggy-branch in the repo:
git checkout buggy-branch
tusk runThis branch introduces a subtle bug by converting the temperature from Celsius to Fahrenheit without updating the temperature thresholds used to determine activity recommendations.
Tusk Drift will detect the deviation in the /api/weather-activity endpoint and mark the test as failed.
Changes to server.ts in buggy-branch:
@@ -8,6 +8,10 @@ const PORT = 3000;
app.use(express.json());
+const convertCelsiusToFahrenheit = (celsius: number) => {
+ return (celsius * 9/5) + 32;
+};
+
// GET /api/weather-activity - Get location from IP, weather, and activity recommendations
app.get('/api/weather-activity', async (req: Request, res: Response) => {
try {
@@ -24,6 +28,8 @@ app.get('/api/weather-activity', async (req: Request, res: Response) => {
);
const weather = weatherResponse.data.current_weather;
+ weather.temperature = convertCelsiusToFahrenheit(weather.temperature);
+
// Business logic: Recommend activity based on weather
let recommendedActivity = 'Play a board game';
if (weather.temperature > 40) {Tusk Drift consists of three components:
The SDK instruments your application to record all inbound and outbound traffic:
- Inbound requests: HTTP requests to your service (headers, body, query params)
- Outbound requests: External API calls, database queries, etc.
- Deterministic Replay: Records responses for exact replay during testing
- Minimal Overhead: Low sampling rates for production use
- PII Protection: Redact sensitive data and blacklist endpoints
See full list of supported packages β
The CLI replays recorded traces against your service:
- Spins up your service locally
- Sends the recorded inbound requests
- Intercepts outbound calls and returns mocked responses
- Detects deviations in API responses
Key Commands:
tusk init- Initialize Tusk for a new servicetusk list- List available tracestusk run- Replay local traces
Tusk Cloud adds automated trace curation and failure analysis on top of the open-source CLI/SDK.
Features include:
- Automatic Test Suite Creation: Intelligently selects representative traces from user traffic
- CI/CD Integration: Run tests in GitHub Actions, GitLab CI, etc. with PR comments showing test results
- Deviation Classification: AI-powered classification of failing tests as either intended or unintended + auto-fixes
- Test Maintenance: Automatically updates/removes outdated tests
This demo uses pre-recorded traces, but you can record new ones for this service from real traffic:
git checkout main
npm run start:recordThis sets TUSK_DRIFT_MODE=record and starts the server.
# Make some API calls
curl http://localhost:3000/api/weather-activity
curl http://localhost:3000/api/user/1
curl http://localhost:3000/api/post/5Wait a few seconds and then stop the server with Ctrl+C. Your newly recorded traces are now in .tusk/traces/!
View the newly recorded tests:
tusk listReplay the tests:
tusk run- Initialize a service using the Tusk CLI: Follow the Tusk CLI quick start guide
- Install the Tusk Drift SDK: Follow the Node SDK setup guide
- Record traces: Capture traffic locally or in dev/staging environments to let Tusk automatically create a test suite
- Replay in CI: Add
tusk runto your test pipeline - Catch regressions: Get notified via PR comments when API behavior changes
Sign up at usetusk.ai to unlock:
- Intelligent test suite curation
- AI-powered deviation classification
- Team collaboration features
- PR integration with GitHub/GitLab
Minimal changes - just initialize the SDK at startup and call TuskDrift.markAppAsReady() when your app is ready to accept requests.
Tusk supports PII and sensitive data masking. You can:
- Blacklist specific endpoints
- Configure custom redaction rules based on request/response patterns
- Keep all data local (no cloud export)
Yes! Use a low sampling rate (e.g., 1-5%) to minimize overhead. Most teams start by recording in staging/dev environments and then switch to production traffic to capture representative traffic.
Tusk has built-in rules for dynamic fields. You can customize these in .tusk/config.yaml to handle application-specific dynamic data.
Traditional mocking requires:
- Manual mock creation and maintenance
- Keeping mocks in sync with real APIs
- Guessing at edge cases
Tusk Drift:
- Automatically captures real API behavior
- Updates tests based on actual traffic
- Finds edge cases you didn't know existed
Join our open source community on Slack.
Questions? Reach out:
- π§ Email: [email protected]
- π Issues: GitHub Issues
- π Twitter: @usetusk
Ready to catch bugs before production? Get started with Tusk Drift β