Snag: Lightweight HTTP Regression Testing in Rust
A CLI tool for API testing with TOML suites and Rhai scripts
1What is Snag?
Snag is a minimal HTTP regression test runner designed for API testing. It allows developers to define test suites in TOML format and write assertions using Rhai scripting language. The tool outputs results in various formats including terminal, CI reports, and IDE test trees. Unlike many testing frameworks, Snag requires no runtime installation or project scaffolding, working as a single Rust binary.
2Key Features
The tool supports parallel test execution with configurable worker counts and includes features like fail-fast mode and deterministic test shuffling. Tests can be filtered by name, ID, or tags using substring matching or regular expressions. Snag provides timeout controls that abort both the script interpreter and HTTP client, preventing hung tests. The tool also supports suite-level and test-level variables with clear precedence rules.
3Testing Capabilities
Snag offers comprehensive HTTP request methods including GET, POST, PUT, PATCH, DELETE, and HEAD. It includes request builders for headers, bearer tokens, and JSON bodies. Response inspection covers status codes, body content, headers, and timing metrics. The assertion library includes status checks, equality tests, performance thresholds, and custom failure messages. JSON responses can be validated using dotted path notation.
4Setup and Teardown
The tool supports sophisticated test lifecycle management with suite-level and test-level setup/teardown scripts. Hooks can be configured to run always or only on success, with proper timeout budgets for cleanup operations. Shared steps can be defined in separate scripts and composed across tests. The system maintains a single shared scope between hooks and test bodies, allowing state sharing.
5Output Formats
Snag supports multiple reporting formats including human-readable output, JSON, JSON Lines, TeamCity (for IntelliJ integration), and JUnit XML. The tool can write reports to files while maintaining terminal output. Verbose mode shows additional details including printed output from scripts. Test results clearly indicate passed, failed, timed out, and skipped tests with execution times.
6Installation Options
Users can install Snag via Cargo from GitHub or download pre-built binaries for Linux, macOS, and Windows. The tool includes an in-place update command and supports shell completions. For development, the Rust project can be cloned and built with standard Cargo commands. Installation documentation covers CI pipeline setups and various deployment scenarios.
7Test Suite Structure
Suites are defined in TOML files with conventional naming patterns. Each suite can define default timeouts and shared variables. Tests within a suite have unique IDs and can override suite defaults. Tests can be tagged for selective execution and marked as parallel-safe. The format supports both simple single-file tests and complex multi-script scenarios with shared steps.
8Why It Matters
Snag addresses the need for lightweight, focused API regression testing without framework overhead. Its combination of declarative suite definitions and scriptable assertions offers flexibility while maintaining simplicity. The tool's output format support makes it viable for both local development and CI environments. As APIs become more critical in modern architectures, specialized tools like Snag help maintain reliability without complicating workflows.
Original article: Hacker News: Show HN — Snag: Lightweight HTTP Regression Testing in Rust