GitHub - deicon/httprunner: A Go-based command-line tool for running multiple, parallel HTTP requests

A Go-based command-line tool for running multiple, parallel HTTP requests.

Installation

Using `go install`

Prerequisites: Go 1.20+ and a working internet connection.

Install the CLI tools directly from the module:

go install github.com/deicon/httprunner/cmd/httprunner@latest
go install github.com/deicon/httprunner/cmd/harparser@latest

Ensure your install bin directory is on PATH:

export PATH="$(go env GOPATH)/bin:$PATH"   # if GOBIN not set

Verify installation and version:

httprunner -version
harparser -version

Notes:

Replace @latest with a specific tag (e.g., @vX.Y.Z) to pin a version.
To upgrade later, rerun the same go install ...@latest commands.

Homebrew (macOS/Linux)

Once a release is published, prebuilt bottles are provided via Formula files in this repo. Install directly from the raw formula URLs:

# httprunner
brew install --formula https://raw.githubusercontent.com/deicon/httprunner/refs/heads/main/Formula/httprunner.rb

# harparser
brew install --formula https://raw.githubusercontent.com/deicon/httprunner/refs/heads/main/Formula/harparser.rb

Notes:

Homebrew supports macOS and Linux; Windows users can download the ZIP asset from Releases.
The CI release job updates these formulas with per-platform URLs and SHA256 checksums automatically on every tagged release.

Project Structure

github.com/deicon/httprunner/
├── cmd/
│   ├── httprunner/       # Main CLI entry point
│   └── harparser/        # HAR to .http converter
├── src/
│   ├── http/
│   │   └── requests.go   # HTTP request data structure
│   ├── parser/
│   │   ├── parser.go     # .http file parsing logic
│   │   └── parser_test.go # Parser tests
│   ├── runner/
│   │   └── runner.go     # Request execution and concurrency management
│   ├── reporting/        # Report generation and formatters
│   ├── metrics/          # Metrics collection
│   ├── template/         # Template processing
│   └── converter/        # Format converters (e.g., K6)
├── tests/
│   ├── e2e/              # End-to-end test scenarios
│   ├── unit/             # Unit test scenarios
│   └── examples/         # Example .http files
├── testapi/              # Test API service
└── docs/
    └── specs/
        └── requirements.md  # Project requirements and specifications

Usage

./httprunner -u <virtualuser> -i <iterations> -d <delay> -f <file>

Parameters

-u n: Number of parallel virtualusers (default: 1)
-i n: Number of iterations (default: 1)
-r n: Runtime in seconds. Overwrites iterations
-d n: Delay between iterations in milliseconds (default: 0)
-offset n: Max random startup delay between virtual users in milliseconds (default: 0)
-f filename: .http file containing HTTP requests (required)
-e filename: .env file containing environment variables (optional)
--experimental-node-runtime: Execute JavaScript via a managed Node.js worker (requires Node on PATH); enables native npm packages and async helpers.

Reporting and Output Parameters

-report format: Report format: console, html, csv, json (default: html)
-output directory: Output directory for streaming results and reports (enables streaming mode)
-detail level: Report detail level: summary, goroutine, iteration, full (default: full)
-stream: Enable streaming mode to reduce memory usage (default: true, requires -output)

Examples

Basic usage (with new defaults)

# Simple run with defaults (streaming=true, report=html, detail=full)
./httprunner -f requests.http -output test_results

# Traditional usage
./httprunner -t 20 -i 10 -d 1000 -f requests.http -output results

# Console output with summary detail
./httprunner -f requests.http -report console -detail summary -stream false

# CSV export with full detail
./httprunner -f requests.http -report csv -output reports

HTTP Request File Format

Requests are separated by ### and follow this format:

### 
# @name <Request Name>
<HTTP_VERB> <URL>
<Header-Name>: <Header-Value>
<Header-Name>: <Header-Value>

<JSON_BODY>

> {%
<JavaScript_Code>
%}

### 
<HTTP_VERB> <URL>

Template Support

URLs, headers, and request bodies support Go template syntax using {{.VARIABLE_NAME}}. All environment variables are available as template variables.

JavaScript Scripting

JavaScript code can be embedded using > {% and %} blocks in two locations:

Pre-request scripts: Placed before the HTTP verb/URL line (separated by blank lines). These scripts execute before the request is sent and have access to:
- client.global.set(key, value): Store values in global variables
- client.global.get(key): Retrieve values from global variables
Post-request scripts: Placed after the request body. These scripts execute after the request is sent and have access to:
- response.body: The response body (parsed as JSON if valid, otherwise as string)
- client.global.set(key, value): Store values in global variables
- client.global.get(key): Retrieve values from global variables
- client.check(name, checkHandler, failureMessage): Perform validation checks (see Check Functions section)
- client.metrics: Access to performance and execution metrics (see Metrics Access section)
- sleep(millis): Sleep execution for millis
- assert(function() -> bool, message, status_code ): assert using function returning bool and fail request if false

Request helpers and `await`

Any request annotated with # @name <Name> can be invoked from JavaScript through client.<name>(). Even though the default Goja runtime resolves these helpers synchronously, always await the result (e.g. const res = await client.create_user()). The experimental Node.js runtime returns a Promise for each helper; if it is not awaited the worker emits a warning and the HTTP call may finish later than expected.

Experimental Node.js runtime

By default scripts run inside the embedded Goja engine. Passing --experimental-node-runtime to the CLI starts a dedicated node worker per virtual user, enabling modern JavaScript features and loading native npm packages. The worker communicates with httprunner over stdio, mirrors global state, and supports the same helper surface (client.global, checks, assertions, named requests). Node.js must be available on PATH; if it is missing or crashes, the CLI falls back to reporting an execution error.

When the flag is enabled, httprunner automatically adds any node_modules directories found next to the .http file (and up to two parent directories) to Node's resolution paths. For custom layouts, you can still extend NODE_PATH before launching the runner. See tests/examples/external-node-runtime for a complete walkthrough.

Example requests.http

Basic requests (backward compatible):

### 
POST http://localhost:8080/api/v3/tarifrechner
Content-Type: application/json

{
  "tarifrechnerModus": {
    "modus": "TARIFRECHNER",
    "mandant": "ORGA",
    "haushaltsId": 48296349
  },
  "kundennummern": [87468640],
  "produktKonfigurationId": "investmentanlage",
  "vertragsId": 7007787476
}

### 
GET http://example.com
Accept: application/json

###

Template and scripting example:

### 
# @name Ressource anlegen
> {%
// Pre-request script: Set up dynamic values before the request
client.global.set("currentTimestamp", Date.now().toString())
client.global.set("requestId", "req_" + Math.random().toString(36).substring(7))
%}

POST {{.BASEURL}}/api/{{.APIVERSION}}/ressource
Authorization: Bearer {{.TOKEN}}
Content-Type: application/json
X-Request-ID: {{.requestId}}

{
"modus": {
"modus": "{{.MODUS}}",
"mandant": "ORGA",
"partnerID": "{{.PARTNERID}}"
},
"timestamp": "{{.currentTimestamp}}"
}

> {%
// Post-request script: Extract values from response
var jsonData = response.body
client.global.set("ID", jsonData.id)
%}

### 
# @name Get Tarifrechner
GET {{.BASEURL}}/api/{{.APIVERSION}}/ressource/{{.ID}}
Authorization: Bearer {{.TOKEN}}
Accept: application/json

###

Metrics Access

The client.metrics object provides access to real-time performance and execution metrics during script execution. This enables performance monitoring, trend analysis, and data-driven test validation.

Available Metrics

httprunner automatically collects these built-in metrics:

http_reqs (Counter): Total number of HTTP requests made
http_req_duration (Histogram): Duration of HTTP requests in milliseconds
http_req_failed (Rate): Rate of failed HTTP requests (0.0 to 1.0)
iterations (Counter): Number of completed iterations
checks (Rate): Success rate of validation checks

Metrics API

`client.metrics.getCurrent(metricName)`

Returns the latest/current value for a metric:

var currentDuration = client.metrics.getCurrent("http_req_duration");
var totalRequests = client.metrics.getCurrent("http_reqs");
console.log("Request #" + totalRequests + " took " + currentDuration + "ms");

`client.metrics.get(metricName)`

Returns a complete metric summary object with statistical data:

var durationStats = client.metrics.get("http_req_duration");
if (durationStats) {
    console.log("Average: " + durationStats.average + "ms");
    console.log("Min: " + durationStats.min + "ms");
    console.log("Max: " + durationStats.max + "ms");
    console.log("P95: " + durationStats.p95 + "ms");
}

Metric Summary Object Properties:

name: Metric name
type: Metric type ("counter", "histogram", "rate")
count: Number of data points
sum: Total sum of all values
average: Average value
min: Minimum value
max: Maximum value
p50: 50th percentile
p90: 90th percentile
p95: 95th percentile
p99: 99th percentile
latest_value: Most recent value

`client.metrics.getAll()`

Returns all metrics as an object:

var allMetrics = client.metrics.getAll();
Object.keys(allMetrics).forEach(function(name) {
    var metric = allMetrics[name];
    console.log(name + ": " + metric.type + " (" + metric.count + " samples)");
});

Performance Monitoring Examples

Response Time Validation

> {%
// Check individual request performance
var duration = client.metrics.getCurrent("http_req_duration");
client.check("Response Time", function() {
    return duration < 2000; // Under 2 seconds
}, "Request should complete within 2 seconds");

// Check performance trends
var durationStats = client.metrics.get("http_req_duration");
if (durationStats && durationStats.count >= 5) {
    client.check("Average Performance", function() {
        return durationStats.average < 1500;
    }, "Average response time should be under 1.5 seconds");
}
%}

Error Rate Monitoring

> {%
// Monitor failure rates
var failureStats = client.metrics.get("http_req_failed");
var totalReqs = client.metrics.getCurrent("http_reqs");

if (failureStats && totalReqs > 10) {
    var failureRate = failureStats.average * 100;
    console.log("Current failure rate: " + failureRate.toFixed(2) + "%");
    
    client.check("Error Rate Threshold", function() {
        return failureRate < 5; // Less than 5%
    }, "Error rate should be under 5%");
}
%}

Throughput Analysis

> {%
// Calculate throughput
var durationStats = client.metrics.get("http_req_duration");
if (durationStats) {
    var avgDurationSec = durationStats.average / 1000;
    var throughput = 1 / avgDurationSec;
    console.log("Throughput: " + throughput.toFixed(2) + " req/s");
    
    client.check("Throughput Target", function() {
        return throughput >= 2.0; // At least 2 requests per second
    }, "Should meet minimum throughput requirement");
}
%}

Performance Regression Detection

> {%
// Store baseline for comparison
var currentDuration = client.metrics.getCurrent("http_req_duration");
var baseline = client.global.get("performance_baseline");

if (!baseline) {
    client.global.set("performance_baseline", currentDuration);
} else {
    var regression = ((currentDuration - baseline) / baseline) * 100;
    console.log("Performance change: " + regression.toFixed(1) + "%");
    
    client.check("No Performance Regression", function() {
        return Math.abs(regression) < 50; // Within 50%
    }, "Performance should not regress significantly");
}
%}

Complete Metrics Dashboard Example

See tests/examples/metrics-showcase.http for a comprehensive example demonstrating:

Performance baseline establishment
Load pattern analysis
Error rate monitoring
Throughput calculations
Comprehensive metrics reporting

Check Functions

The client.check() function allows you to perform validation checks on HTTP responses. These checks are tracked and reported in the final test results.

Syntax

client.check(name, checkHandler, failureMessage)

Parameters

name (string): A unique identifier for the check
checkHandler (function): A function that returns true for success, false for failure
failureMessage (string): Message displayed when the check fails

Examples

### 
# @name API Response Validation
POST {{.BASEURL}}/api/users
Content-Type: application/json

{
  "username": "testuser",
  "email": "test@example.com"
}

> {%
// Post-request validation checks
client.check("Status Code Check", function() {
    return response.body.status === "success";
}, "API should return success status");

client.check("User ID Present", function() {
    return response.body.user && response.body.user.id;
}, "Response should contain user ID");

client.check("Valid Email Format", function() {
    var email = response.body.user.email;
    return email && email.includes("@");
}, "Email should be in valid format");

// Store user ID for subsequent requests
if (response.body.user && response.body.user.id) {
    client.global.set("userId", response.body.user.id);
}
%}

### 
# @name Get User Details
GET {{.BASEURL}}/api/users/{{.userId}}
Authorization: Bearer {{.TOKEN}}

> {%
client.check("User Details Retrieved", function() {
    return response.body && response.body.id == client.global.get("userId");
}, "Should retrieve correct user details");

client.check("Response Time Check", function() {
    var duration = client.metrics.getCurrent("http_req_duration");
    return duration && duration < 2000; // Should be under 2 seconds
}, "Response time should be under 2 seconds");
%}

###

Check Results in Reports

Check results are included in all report formats:

Console: Shows check summary with total/successful/failed counts and breakdown by check name
HTML: Displays check metrics in the summary section and detailed results
JSON: Includes checkSummaries object with detailed check statistics
CSV: Individual check results are included in request details

Failed checks do not stop test execution but are counted and reported for analysis.

Building and Testing

# Build the project
go build

# Run tests
go test ./parser

# Run with sample requests (using new defaults)
./httprunner -f requests.http -output test_results

# Run without streaming for console output
./httprunner -f requests.http -stream=false

Features

Streaming Mode

Memory efficient: Processes results as they come in, reducing memory usage for large workloads
Real-time results: Results are written to files immediately as requests complete
Automatic activation: Automatically enabled for workloads > 10,000 total operations
Output formats: Raw results in JSONL format + formatted reports

Multiple Report Formats

HTML: Rich, interactive reports with charts and detailed statistics (default)
Console: Simple text output for terminal viewing
CSV: Spreadsheet-compatible format for data analysis
JSON: Machine-readable format for integration with other tools

Report Detail Levels

Summary: High-level overview of performance metrics
Goroutine: Per-goroutine breakdown of performance
Iteration: Detailed per-iteration results
Full: Complete detailed breakdown including all request/response data (default)

Architecture

main.go: Handles CLI flag parsing and coordinates the parser and runner
http/requests.go: Defines the Request struct containing Name, Verb, URL, Headers, Body, and Script
parser/parser.go: Parses .http files into Request structs, handling template syntax and script blocks
runner/runner.go: Manages concurrent execution using goroutines and sync.WaitGroup, with template rendering and script execution
reporting/: Handles multiple output formats and streaming results
template/template.go: Provides template rendering using Go's text/template and JavaScript execution using Goja

Each goroutine executes all requests in the file for the specified number of iterations, with the configured delay between iterations. Before each request execution, templates are rendered using global variables and environment variables. After each request, any associated JavaScript scripts are executed with access to the response data.

Dependencies

github.com/dop251/goja: JavaScript engine for script execution
Go standard library for template rendering and HTTP requests

Installation

Using go install

Homebrew (macOS/Linux)

Project Structure

Usage

Parameters

Reporting and Output Parameters

Examples

Basic usage (with new defaults)

HTTP Request File Format

Template Support

JavaScript Scripting

Request helpers and await

Experimental Node.js runtime

Example requests.http

Basic requests (backward compatible):

Template and scripting example:

Metrics Access

Available Metrics

Metrics API

client.metrics.getCurrent(metricName)

client.metrics.get(metricName)

client.metrics.getAll()

Performance Monitoring Examples

Response Time Validation

Error Rate Monitoring

Throughput Analysis

Performance Regression Detection

Complete Metrics Dashboard Example

Check Functions

Syntax

Parameters

Examples

Check Results in Reports

Building and Testing

Features

Streaming Mode

Multiple Report Formats

Report Detail Levels

Architecture

Dependencies

Using `go install`

Request helpers and `await`

`client.metrics.getCurrent(metricName)`

`client.metrics.get(metricName)`

`client.metrics.getAll()`