A command-line tool built with Bun to compare API responses between reference and target environments. Perfect for testing API migrations, version upgrades, or comparing different deployment stages.
- 🔍 Compare API responses between two environments
- 📊 Status code comparison
- 📝 Normalized JSON body comparison
- ⏱️ Response time tracking
- 📄 Detailed JSON and static, self-contained HTML report generation with diff-view of changed response content
- 🌓 Dark mode support in HTML reports
- 📋 Support input files in generic JSON format (default) and Restfox export format
bun installbun run dev -- compare \
--input-file example-requests.json \
--reference-base-url https://api-current.example.com \
--target-base-url https://api-next.example.comAdd headers to all reference and/or target requests:
bun run dev -- compare \
--input-file example-requests.json \
--reference-base-url https://api-current.example.com \
--target-base-url https://api-next.example.com \
--reference-headers "API-Key: xyz123, User-Agent: TestApp" \
--target-headers "API-Key: abc456"If you already have a JSON comparison report, you can generate just the HTML report:
bun run dev -- report \
--input-file comparison-report-example-requests.jsonThe HTML report will be generated in the same directory as the JSON file with the same filename (just .html extension instead of .json).
| Action | Description |
|---|---|
compare |
Compare API responses and generate both JSON and HTML reports |
report |
Generate HTML report from an existing JSON comparison report |
For compare action:
| Option | Description | Required |
|---|---|---|
--input-file <file> |
Path to the JSON request file | ✅ Yes |
--input-file-type <type> |
Type of input file: generic (default) or restfox |
No |
--reference-base-url <url> |
Base URL for the current/reference API | ✅ Yes |
--target-base-url <url> |
Base URL for the next/target API | ✅ Yes |
--reference-headers <headers> |
Headers to add to all reference requests (format: "Header1: value1, Header2: value2") | No |
--target-headers <headers> |
Headers to add to all target requests (format: "Header1: value1, Header2: value2") | No |
--limit <number> |
Limit the number of URLs to compare | No |
--output-file <file> |
Output filename for reports (without extension) | No |
--output-dir <dir> |
Output directory for reports (default: current directory) | No |
--no-timestamp-in-report-filenames |
Omit timestamp from report filenames | No |
--normalized-json-comparison |
Use normalized JSON comparison (ignore key order) | No (default: false/strict) |
For report action:
| Option | Description | Required |
|---|---|---|
--input-file <file> |
Path to the JSON comparison report | ✅ Yes |
--output-file <file> |
Output filename for HTML report (with or without .html extension) | No |
--output-dir <dir> |
Output directory for HTML report (default: same as input file) | No |
General options:
| Option | Description |
|---|---|
--help, -h |
Show help message |
The tool supports two input formats for defining requests. For complete documentation with examples, see REQUEST_FORMAT.md.
Structured Format (Recommended) - Define variables and headers with environment-specific overrides:
{
"configuration": {
"variables": {
"apiVersion": "v1"
},
"headers": {
"User-Agent": "API-Comparator/1.0"
},
"referenceConfiguration": {
"variables": { "apiKey": "ref-key" }
},
"targetConfiguration": {
"variables": { "apiKey": "target-key" }
}
},
"requests": [
{
"url": "{{baseUrl}}/api/{{apiVersion}}/users",
"method": "GET"
}
]
}Legacy Array Format - Still supported for backward compatibility:
[
{
"url": "{{baseUrl}}/users/123",
"method": "GET"
}
]Key Features:
- Variable replacement: Use
{{variableName}}in URLs, headers, and body - Environment-specific config: Different variables/headers for reference vs target
- Automatic JSON handling: Object bodies are automatically stringified with
Content-Type: application/json - Flexible headers: Define globally or per-request, with CLI override support
2. Restfox Export Format
Use --input-file-type restfox to parse Restfox export files. The tool reads the exported JSON file and extracts all HTTP requests with the following:
- Request method (GET, POST, PUT, PATCH, DELETE, etc.)
- URL with
{{baseUrl}}placeholder support - Request headers (with placeholder support)
- Request body (for POST/PUT/PATCH requests)
- Query parameters
Example Restfox export structure:
{
"exportedFrom": "Restfox-1.0.0",
"collection": [
{
"_type": "request",
"name": "Get User",
"method": "GET",
"url": "{{baseUrl}}/api/users/123",
"body": {
"mimeType": "No Body"
}
},
{
"_type": "request",
"name": "Create User",
"method": "POST",
"url": "{{baseUrl}}/api/users",
"body": {
"mimeType": "application/json",
"text": "{\"name\":\"John Doe\",\"email\":\"john@example.com\"}"
}
}
]
}The compare action generates two reports:
- JSON Report - Machine-readable detailed comparison data
- HTML Report - Static, self-contained, beautiful, interactive visual report
By default, both reports are timestamped (e.g., comparison-report-Restfox_2025-11-11-2025-11-11T10-30-45-123Z.json and .html). Use --no-timestamp-in-report-filenames to generate reports without timestamps in file names.
A detailed JSON report is saved with a timestamp filename (e.g., comparison-report-example-requests.json).
An interactive HTML report is also generated with the same timestamp. Features include:
- Visual Dashboard - Summary cards showing total, passed, and failed requests
- Filter Tabs - View all results, only passed, or only failed
- Side-by-side Comparison - Expected vs actual values for failures
- Response Duration - Duration shown for both reference and target
- Pretty JSON - Formatted JSON diffs when applicable
Simply open the HTML file in any browser to view the interactive report.
The tool compares the following aspects:
Direct comparison of HTTP status codes between reference and target responses.
Strict JSON Comparison (default):
- JSON responses are converted to strings and compared exactly
- Key order matters (e.g.,
{"a":1,"b":2}is different from{"b":2,"a":1}) - Useful when exact JSON structure must match
Normalized JSON Comparison (with --normalized-json-comparison flag):
- JSON responses are compared using deep structural equality
- Ignores key order (e.g.,
{"a":1,"b":2}equals{"b":2,"a":1}) - Detects differences in values, nested objects, and arrays
- Uses the
fast-deep-equallibrary
- Ignores key order (e.g.,
Other comparisons:
- String responses (plain text, HTML, XML, etc.) use direct string comparison
- Mixed types are flagged as a type mismatch error
- Requests are executed sequentially (reference first, then target)
- This prevents potential conflicts or performance measurement issues when both APIs share the same backend
To build the project:
bun run buildThis creates a distributable version in the dist/ directory.
After building:
bun run start -- compare \
--input-file example-requests.json \
--reference-base-url https://api-current.example.com \
--target-base-url https://api-next.example.com0: All comparisons passed1: One or more comparisons failed or an error occurred
This makes the tool suitable for CI/CD pipelines.
This project uses release-it for automated releases.
# Patch release (1.0.0 -> 1.0.1)
export GITHUB_TOKEN=$(gh auth token)
bun run release
# Minor release (1.0.0 -> 1.1.0)
bun run release:minor
# Major release (1.0.0 -> 2.0.0)
bun run release:majorThe release script will create a git tag, push to GitHub, create a GitHub Release with assets (binary, JavaScript bundle, templates), and automatically bump to the next development version.
MIT
The HTML reports are generated using Eta. Templates are located in the templates/ directory.