API Reference - HTTP File Runner

Command Line Interface

Synopsis

httprunner [OPTIONS] [FILE...]
httprunner [OPTIONS] --discover

Arguments

FILE

string[]

One or more .http files to process

Options

--discover

flag

Recursively discover and process all .http files from current directory

--verbose

flag

Show detailed HTTP request and response information

--pretty-json

flag

Pretty-print JSON payloads in verbose output (requires --verbose)

--log [filename]

string?

Log output to a file (defaults to 'log' if no filename specified)

--report [format]

string?

Generate summary report in markdown or html format. Defaults to markdown if no format specified

--env <environment>

string

Specify environment from http-client.env.json

--version, -v

flag

Show version information and exit

--help, -h

flag

Show help information and exit

Examples

                        # Basic usage
httprunner api-tests.http

# Multiple files
httprunner auth.http users.http posts.http

# Verbose mode with pretty-printed JSON
httprunner api-tests.http --verbose --pretty-json

# Discovery mode with logging
httprunner --discover --verbose --log test-results.log

# Generate summary report (defaults to markdown)
httprunner api-tests.http --report

# Generate HTML summary report
httprunner api-tests.http --report html

# Generate markdown summary report (explicit)
httprunner api-tests.http --report markdown

# Environment-specific testing with formatted JSON output and HTML report
httprunner api-tests.http --env production --verbose --pretty-json --log prod-test.log --report html
                    

HTTP File Syntax

File Structure

[comments]
[variables]
[request-block]
[assertions]

[request-block]
[assertions]
...

Request Block Format

METHOD URL [HTTP-VERSION]
[Header-Name: Header-Value]
...

[request-body]

Supported HTTP Methods

GET

Retrieve data from server

POST

Send data to server

PUT

Update resource on server

DELETE

Delete resource from server

PATCH

Partially update resource

Comments

                        # This is a comment
# Comments start with # and continue to end of line

GET https://api.example.com/users  # Inline comments are also supported
                    

Headers

                        GET https://api.example.com/users
Authorization: Bearer token123
Accept: application/json
Content-Type: application/json
X-Custom-Header: custom-value
                    

Request Body

                        # JSON body
POST https://api.example.com/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

# Form data
POST https://api.example.com/upload
Content-Type: application/x-www-form-urlencoded

name=John&email=john@example.com

# Text body
POST https://api.example.com/notes
Content-Type: text/plain

This is a plain text note.
                    

Variables

Variable Definition

@variable-name=value

Variable Usage

{{variable-name}}

Variable Scoping Rules

Variables must be defined before they can be used
Variables are file-scoped (each .http file has its own variable namespace)
Later variable definitions override earlier ones with the same name
Variables can reference other variables that were defined earlier

Variable Composition

                        @protocol=https
@hostname=api.example.com
@port=443
@version=v1
@baseUrl={{protocol}}://{{hostname}}:{{port}}/{{version}}

GET {{baseUrl}}/users
                    

Valid Variable Names

Must start with a letter or underscore
Can contain letters, numbers, underscores, and hyphens
Case-sensitive
No spaces allowed

Variable Usage Locations

URLs
Header names and values
Request body content
Other variable definitions

Built-in Functions

Function List

Function	Description	Example Output
`guid()`	Generate UUID v4 (32 hex chars)	a1b2c3d4e5f67890a1b2c3d4e5f67890
`string()`	Random alphanumeric string (20 chars)	aB3xK9mP2q
`number()`	Random number (0-100)	42
`base64_encode('text')`	Base64 encode a string	dGV4dA==

Usage Notes

All functions are case-insensitive
Can be used in URLs, headers, and request bodies
Values are generated dynamically for each request
Can be combined with variables
base64_encode() requires single-quoted string argument

Example

                        POST https://api.example.com/test
Content-Type: application/json

{
  "id": "guid()",
  "key": "string()",
  "value": "number()",
  "auth": "base64_encode('user:pass')"
}
                    

Request Variables

Syntax Pattern

{{<request_name>.(request|response).(body|headers).(*|JSONPath|XPath|<header_name>)}}

Component Breakdown

Component	Description	Example
`request_name`	Name of a previous request (defined with `# @name`)	`authenticate`
`request\|response`	Extract from request or response	`response`
`body\|headers`	Extract from body or headers	`body`
`extraction_path`	JSONPath, XPath, header name, or `*`	`$.json.access_token`

JSONPath Patterns

$.property - Top-level property
$.nested.property - Nested property
$.json.property - Property within "json" field
* - Entire body content

Header Extraction

Content-Type - Extract Content-Type header
authorization - Extract Authorization header (case-insensitive)
x-custom-header - Extract custom header

Request Naming

                        # @name request_identifier
POST https://api.example.com/auth
Content-Type: application/json

{
  "username": "user",
  "password": "pass"
}
                    

Usage Examples

                        # Extract from response body
{{auth.response.body.$.access_token}}

# Extract from response headers
{{auth.response.headers.Content-Type}}

# Extract from request body
{{auth.request.body.$.username}}

# Extract entire response
{{auth.response.body.*}}
                    

Execution Order

Request variables can only reference requests that appear earlier in the file
Referenced requests must have been executed successfully
Named requests must use the # @name syntax
Variables are resolved at execution time

Environment Files

File Name

http-client.env.json

File Location

The environment file should be placed in:

Same directory as the .http file
Any parent directory of the .http file

JSON Schema

                        {
  "environment-name": {
    "variable-name": "value",
    "another-variable": "another-value"
  },
  "another-environment": {
    "variable-name": "different-value"
  }
}
                    

Complete Example

                        {
  "dev": {
    "BaseUrl": "https://localhost:44320",
    "ApiKey": "dev-key-123",
    "Database": "dev_db",
    "LogLevel": "debug"
  },
  "staging": {
    "BaseUrl": "https://staging-api.example.com",
    "ApiKey": "staging-key-456",
    "Database": "staging_db",
    "LogLevel": "info"
  },
  "production": {
    "BaseUrl": "https://api.example.com",
    "ApiKey": "prod-key-789",
    "Database": "prod_db",
    "LogLevel": "warn"
  }
}
                    

Variable Override Order

Environment variables from http-client.env.json (loaded first)
Variables defined in .http file (override environment variables)

Response Assertions

Assertion Types

EXPECTED_RESPONSE_STATUS

integer

Assert HTTP status code (exact match)

EXPECTED_RESPONSE_BODY

string

Assert response body contains text (substring match)

EXPECTED_RESPONSE_HEADERS

string

Assert header exists and contains value (format: "Header-Name: value")

Assertion Syntax

METHOD URL
[headers]

[body]

EXPECTED_RESPONSE_STATUS status-code
EXPECTED_RESPONSE_BODY "expected-text"
EXPECTED_RESPONSE_HEADERS "Header-Name: expected-value"

Multiple Assertions

                        GET https://api.example.com/users/1

EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_BODY "John Doe"
EXPECTED_RESPONSE_BODY "john@example.com"
EXPECTED_RESPONSE_HEADERS "Content-Type: application/json"
EXPECTED_RESPONSE_HEADERS "Cache-Control: no-cache"
                    

Assertion Matching Rules

Status Code

Exact match

200 matches only 200

Response Body

Substring match (case-sensitive)

"user" matches "username: john"

Response Headers

Header exists and value substring match

"Content-Type: json" matches "Content-Type: application/json"

Assertion Behavior

All assertions must pass for the request to be considered successful
If any assertion fails, the request is marked as failed
Assertions are evaluated in the order they appear
When assertions are present, response headers and body are always captured

Output Formats

Default Output

                        🚀 HTTP File Runner - Processing file: requests.http
==================================================
Found 3 HTTP request(s)

✅ GET https://api.example.com/users - Status: 200
❌ GET https://api.example.com/missing - Status: 404
✅ POST https://api.example.com/users - Status: 201

==================================================
File Summary: 2 Passed, 1 Failed, 0 Skipped
                    

Verbose Output

                        🚀 HTTP File Runner - Processing file: requests.http
==================================================
Found 1 HTTP request(s)

📤 Request Details:
Method: GET
URL: https://api.example.com/users
Headers:
  Authorization: Bearer token123
  Accept: application/json
------------------------------

✅ GET https://api.example.com/users - Status: 200 - 145ms

📥 Response Details:
Status: 200
Duration: 145ms
Headers:
  content-type: application/json
  content-length: 1234
  server: nginx/1.18.0
Body:
[{"id":1,"name":"John Doe","email":"john@example.com"}]
------------------------------
                    

Report Formats (--report)

The --report flag generates timestamped reports in either markdown or HTML format. Defaults to markdown if no format is specified.

Markdown Report Example

                        # HTTP File Runner - Test Report

**Generated:** 2025-12-19 09:34:12

## Overall Summary

- **Total Requests:** 15
- **Passed:** ✅ 12
- **Failed:** ❌ 2
- **Skipped:** ⏭️ 1
- **Success Rate:** 80.0%

---

## File: `api-tests.http`

| Method | URL | Status | Duration | Result |
|--------|-----|--------|----------|--------|
| GET | https://api.example.com/users | 200 | 145ms | ✅ |
| POST | https://api.example.com/users | 201 | 203ms | ✅ |
| GET | https://api.example.com/missing | 404 | 98ms | ❌ |

**File Summary:** 2 Passed, 1 Failed, 0 Skipped
                    

HTML Report Features

HTML reports (--report html) include all the same information with additional features:

Responsive Design: Works on mobile and desktop devices
Light/Dark Mode: Automatic theme switching based on system preferences
Color-Coded Statistics: Visual cards showing pass/fail/skip counts
Modern Styling: Clean, professional UI with proper spacing
Syntax Highlighting: Formatted code blocks for request/response bodies

Report files are named:

Markdown: httprunner-report-YYYYMMDD-HHMMSS.md
HTML: httprunner-report-YYYYMMDD-HHMMSS.html

Discovery Mode Output

                        🔍 Discovering .http files recursively...
Found 4 .http file(s):
  📄 .\tests\auth.http
  📄 .\tests\users.http
  📄 .\examples\simple.http
  📄 .\api\health.http

🚀 HTTP File Runner - Processing file: .\tests\auth.http
==================================================
Found 2 HTTP request(s)
...

🎯 Overall Summary:
Files processed: 4
Total requests: 12 Passed, 2 Failed, 1 Skipped
                    

Assertion Output

                        ✅ GET https://api.example.com/users - Status: 200 - 123ms

🔍 Assertion Results:
  ✅ Status code: Expected 200, Got 200
  ✅ Response body contains: "John Doe"
  ❌ Response header: Expected "Cache-Control: no-cache", Got "Cache-Control: max-age=3600"

❌ Request failed due to assertion failures
                    

Status Indicators

✅

Successful request (2xx status, all assertions pass)

❌

Failed request (non-2xx status or assertion failure)

⏭️

Skipped request (conditions not met)

🚀

Processing information

🔍

Discovery or assertion information

📤

Request details (verbose mode)

📥

Response details (verbose mode)

📄

File information

🎯

Summary information

Exit Codes

0

Success

All requests passed (2xx status, all assertions passed). Skipped requests don't affect exit code.

1

General Error

One or more requests failed, file not found, or invalid arguments

2

Invalid Usage

Invalid command-line arguments or options

Success Criteria

A request is considered successful when:

HTTP status code is in 2xx range (200-299)
All assertions (if any) pass
No network or connection errors occur

Failure Scenarios

HTTP status code is not 2xx (4xx, 5xx)
Any assertion fails
Network connection error
DNS resolution failure
Timeout
Invalid URL format

Version Information

Version Command

                        httprunner --version
httprunner -v
                    

Version Output Format

                        HTTP File Runner v1.2.3
Git Tag: v1.2.3
Git Commit: a1b2c3d4e5f6789
Build Time: 2025-06-19 10:30:45 UTC
                    

Version Components

Version

Semantic Version

Application version following semver (MAJOR.MINOR.PATCH)

Git Tag

Git Reference

Git tag from which the build was created

Git Commit

Commit Hash

Short commit hash of the build

Build Time

ISO 8601 DateTime

UTC timestamp when the binary was built

Build Information

Version information is automatically generated at build time using:

Git repository metadata
Build system timestamp
Semantic versioning from git tags