User Guide - HTTP File Runner

Getting Started

HTTP File Runner is a command-line tool that executes HTTP requests defined in .http files. It's perfect for API testing, automation, and development workflows.

Basic Usage

                        # Run a single .http file
httprunner requests.http

# Run multiple files
httprunner file1.http file2.http

# Discover and run all .http files recursively
httprunner --discover
                    

Output Modes

Default: Shows request results with colored status indicators
Verbose (--verbose): Shows detailed request/response information
Logging (--log): Saves output to a file for analysis
Report (--report [format]): Generates summary report in markdown or html format. Defaults to markdown if no format specified
Export (--export): Saves individual HTTP requests and responses to separate timestamped log files

GUI Application

HTTP File Runner includes a native graphical user interface (GUI) application for a visual, interactive experience.

⚠️ Note

The GUI and TUI (Terminal UI) applications are experimental and subject to change. The CLI is the primary, stable interface.

GUI Features

Visual File Browser: Browse and select .http files from a directory tree
Request Execution: Run individual requests or all requests in a file
Response Viewer: View status codes, headers, and formatted response bodies
Environment Management: Easily switch between different environments
State Persistence: Automatically saves and restores your workspace
Font Size Control: Zoom in/out for comfortable viewing

State Persistence

The GUI automatically saves your workspace state and restores it when you restart. This includes:

Last opened directory
Currently selected .http file
Active environment selection
Font size preference
Window size
Last run results - Your previous request execution results

💾 State File Location

Windows: %APPDATA%\httprunner\httprunner-gui-state.json
macOS: ~/Library/Application Support/httprunner/httprunner-gui-state.json
Linux: ~/.config/httprunner/httprunner-gui-state.json

Keyboard Shortcuts

                        F5               Run all requests in selected file
Ctrl+O / Cmd+O   Open directory
Ctrl+Q / Cmd+Q   Quit application
Ctrl+E / Cmd+E   Cycle through environments
Ctrl++ / Cmd++   Zoom in (increase font size)
Ctrl+- / Cmd+-   Zoom out (decrease font size)
Ctrl+0 / Cmd+0   Reset font size to default
                    

Automatic State Saving

State is automatically saved when you:

Open a new directory
Select a different file
Switch environments
Change font size
Resize the window
Execute requests (results are captured)
Quit the application

Just close the application and your workspace will be exactly as you left it when you return. No manual saving required!

Terminal UI (TUI)

HTTP File Runner includes a Terminal User Interface (TUI) for an interactive, text-based experience directly in your terminal.

⚠️ Note

The TUI application is experimental and subject to change. The CLI is the primary, stable interface.

Features

Interactive File Browser: Navigate and select .http files using keyboard
Request Execution: Run individual requests or all requests in a file
Response Viewer: View status codes, headers, and formatted response bodies in the terminal
Environment Management: Switch between different environments
Keyboard Navigation: Full keyboard control for efficient workflow

Running the TUI

                        # Start the Terminal UI
httprunner-tui
                    

The TUI provides a rich, interactive experience while staying within your terminal, making it perfect for remote sessions, SSH connections, or workflows that prefer staying in the terminal.

HTTP File Format

HTTP files use a simple, readable format that's compatible with many tools and editors.

Basic Structure

                        # Comments start with #

# Simple GET request
GET https://api.example.com/users

# Request with headers
GET https://api.example.com/data
Authorization: Bearer your-token
Accept: application/json

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

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

Supported HTTP Methods

GET
POST
PUT
DELETE
PATCH

Headers and Body

Headers are specified as key-value pairs separated by colons. The request body comes after a blank line following the headers.

Variables

Variables make your HTTP files flexible and reusable across different environments and scenarios.

Defining Variables

                        # Define variables with @ syntax
@hostname=localhost
@port=8080
@version=v1
@baseUrl=https://{{hostname}}:{{port}}/api/{{version}}
                    

Using Variables

                        # Use variables with double curly braces
GET {{baseUrl}}/users

# Variables in headers
GET {{baseUrl}}/protected
Authorization: Bearer {{token}}

# Variables in request body
POST {{baseUrl}}/users
Content-Type: application/json

{
  "host": "{{hostname}}",
  "environment": "{{env}}"
}
                    

Variable Composition

Variables can reference other variables that were defined earlier:

                        @hostname=api.example.com
@protocol=https
@baseUrl={{protocol}}://{{hostname}}

GET {{baseUrl}}/status
                    

Built-in Functions

HTTP File Runner provides built-in functions for dynamic value generation. Functions are case-insensitive and work in URLs, headers, and request bodies.

Available Functions

guid() - Generate UUID

Generates a new UUID v4 (32 hex characters without dashes).

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

{
  "id": "guid()",
  "requestId": "GUID()"
}
                    

string() - Generate Random String

Generates a random alphanumeric string of 20 characters.

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

{
  "sessionKey": "string()",
  "token": "STRING()"
}
                    

number() - Generate Random Number

Generates a random number between 0 and 100 (inclusive).

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

{
  "randomValue": "number()",
  "percentage": "NUMBER()"
}
                    

base64_encode() - Base64 Encoding

Encodes a string to Base64 format. The string must be enclosed in single quotes.

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

{
  "credentials": "base64_encode('username:password')",
  "token": "BASE64_ENCODE('Hello, World!')"
}
                    

upper() - Convert to Uppercase

Converts a string to uppercase. The string must be enclosed in single quotes.

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

{
  "code": "upper('hello, world')",
  "shout": "UPPER('quiet text')"
}
                    

lower() - Convert to Lowercase

Converts a string to lowercase. The string must be enclosed in single quotes.

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

{
  "normalized": "lower('HELLO, WORLD')",
  "lowercase": "LOWER('Mixed Case Text')"
}
                    

name() - Generate Full Name

Generates a random full name (first name + last name).

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

{
  "fullName": "name()",
  "displayName": "NAME()"
}
                    

first_name() - Generate First Name

Generates a random first name.

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

{
  "firstName": "first_name()",
  "givenName": "FIRST_NAME()"
}
                    

last_name() - Generate Last Name

Generates a random last name.

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

{
  "lastName": "last_name()",
  "surname": "LAST_NAME()"
}
                    

address() - Generate Address

Generates a random full mailing address (street, city, postal code, country).

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

{
  "streetAddress": "address()",
  "mailingAddress": "ADDRESS()"
}
                    

email() - Generate Email Address

Generates a random email address in the format firstname.lastname@domain.com.

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

{
  "email": "email()",
  "contactEmail": "EMAIL()"
}
                    

job_title() - Generate Job Title

Generates a random job title.

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

{
  "title": "job_title()",
  "position": "JOB_TITLE()"
}
                    

lorem_ipsum(N) - Generate Lorem Ipsum Text

Generates Lorem Ipsum placeholder text with N words. The function is case-insensitive.

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

{
  "description": "lorem_ipsum(50)",
  "summary": "LOREM_IPSUM(20)",
  "content": "Lorem_Ipsum(100)"
}
                    

Note: The parameter specifies the number of words to generate. If the requested count exceeds the available word list (approximately 285 words), words will be repeated cyclically.

getdate() - Get Current Date

Returns the current local date in YYYY-MM-DD format.

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

{
  "eventDate": "getdate()",
  "createdDate": "GETDATE()"
}
                    

gettime() - Get Current Time

Returns the current local time in HH:MM:SS format (24-hour).

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

{
  "timestamp": "gettime()",
  "logTime": "GETTIME()"
}
                    

getdatetime() - Get Current Date and Time

Returns the current local date and time in YYYY-MM-DD HH:MM:SS format.

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

{
  "createdAt": "getdatetime()",
  "timestamp": "GETDATETIME()"
}
                    

getutcdatetime() - Get Current UTC Date and Time

Returns the current UTC date and time in YYYY-MM-DD HH:MM:SS format.

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

{
  "utcTimestamp": "getutcdatetime()",
  "serverTime": "GETUTCDATETIME()"
}
                    

Function Features

Case-insensitive: guid(), GUID(), and Guid() all work identically
Dynamic generation: Values are generated fresh for each request
Works everywhere: Use in URLs, headers, and request bodies
Combine with variables: Functions can be used alongside variables

Request Variables

Request Variables enable powerful request chaining by allowing you to pass data from one HTTP request to another within the same .http file.

Syntax

Request variables follow this pattern:

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

Authentication Flow Example

                        # @name authenticate
POST https://httpbin.org/post
Content-Type: application/json

{
  "username": "admin@example.com",
  "password": "secure123",
  "access_token": "jwt_token_here",
  "refresh_token": "refresh_jwt_here",
  "user_id": "admin_001",
  "role": "administrator"
}

###

# @name get_admin_data
GET https://httpbin.org/get
Authorization: Bearer {{authenticate.response.body.$.json.access_token}}
X-User-Role: {{authenticate.response.body.$.json.role}}
X-User-ID: {{authenticate.response.body.$.json.user_id}}

###

# @name create_audit_log
POST https://httpbin.org/post
Content-Type: application/json

{
  "action": "admin_data_access",
  "user_id": "{{authenticate.response.body.$.json.user_id}}",
  "original_request": {
    "username": "{{authenticate.request.body.$.username}}",
    "timestamp": "2025-07-01T21:16:46Z"
  },
  "response_content_type": "{{get_admin_data.response.headers.Content-Type}}"
}
                    

Extraction Patterns

JSON Bodies

$.property_name - Extract top-level properties
$.nested.property - Extract nested properties
$.json.property - Extract from "json" field (like httpbin.org responses)
* - Extract entire body

Headers

header_name - Extract specific header value (case-insensitive)

Request Data

Same patterns as response, but extracts from the original request data

💡 Use Cases

Authentication Workflows: Extract tokens from login responses
Data Chaining: Pass IDs or data between sequential requests
Dynamic Headers: Use response headers in subsequent requests
Request Auditing: Reference original request data in follow-up calls
API Testing: Create comprehensive test flows with dependent requests

Conditional Execution

Execute HTTP requests conditionally based on previous request results using @dependsOn, @if, and @if-not directives. This enables complex integration testing scenarios and workflow automation.

@dependsOn Directive

Execute a request only if a dependent request returns HTTP 200 status.

                        # @name check-user
GET https://api.example.com/user/123

###
# Only execute if check-user succeeds (returns 200)
# @name update-user
# @dependsOn check-user
PUT https://api.example.com/user/123
Content-Type: application/json

{
  "name": "Updated Name"
}
                    

@if Directive - Status Code Check

Execute a request only if a previous request returns a specific HTTP status code.

                        # @name check-user
GET https://api.example.com/user/123

###
# Create user only if they don't exist (404)
# @name create-user
# @if check-user.response.status 404
POST https://api.example.com/user
Content-Type: application/json

{
  "username": "newuser",
  "email": "user@example.com"
}
                    

@if Directive - JSONPath Body Check

Execute a request only if a JSONPath expression in the response body matches an expected value.

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

{
  "username": "testuser",
  "role": "admin"
}

###
# Update only if user was created with admin role
# @name activate-admin
# @if create-user.response.status 200
# @if create-user.response.body.$.username testuser
# @if create-user.response.body.$.role admin
PUT https://api.example.com/user/activate
                    

@if-not Directive - Negated Conditions

Execute a request only if a condition does NOT match. Works the opposite way of @if.

                        # @name check-user
GET https://api.example.com/user/123

###
# Update only if user exists (NOT 404)
# @name update-user
# @if-not check-user.response.status 404
PUT https://api.example.com/user/123
Content-Type: application/json

{
  "name": "Updated Name"
}

###
# Create only if user does not exist (NOT 200)
# @name create-user
# @if-not check-user.response.status 200
POST https://api.example.com/user
Content-Type: application/json

{
  "id": 123,
  "name": "New User"
}

###
# Execute only if no error in response
# @name process-result
# @if create-user.response.status 200
# @if-not create-user.response.body.$.error true
PUT https://api.example.com/user/activate
                    

Multiple Conditions

Multiple @if and @if-not directives can be specified for a single request. All conditions must be met for the request to execute (AND logic).

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

{
  "username": "admin",
  "password": "secret"
}

###
# Only execute if login succeeded AND returned admin role
# @name admin-dashboard
# @if login.response.status 200
# @if login.response.body.$.role admin
GET https://api.example.com/admin/dashboard
Authorization: Bearer {{login.response.body.$.token}}
                    

💡 Use Cases

Progressive User Setup: Check if user exists → Create only if 404 → Verify → Update
Error Handling: Try primary API → Use fallback if primary fails
Conditional Updates: Update resources only when specific conditions are met
Role-Based Testing: Execute admin-only requests based on user role
Data Validation: Proceed only if response data matches expectations
Negative Conditions with @if-not: Execute actions when something does NOT match (e.g., no errors, not 404, user does not exist)

📝 Notes

Conditional directives support both # and // comment styles
Requests can have both @dependsOn and multiple @if or @if-not directives
@if-not works as the opposite of @if - condition must NOT match to execute
Conditions can only reference requests that appear earlier in the .http file
All request names used in conditions must be defined with # @name
Skipped requests show: ⏭️ request-name - Skipped: conditions not met

Environment Files

Environment files allow you to define different variable values for different environments (dev, staging, production).

Creating Environment Files

Create a file named http-client.env.json in the same directory as your .http files:

                        {
  "dev": {
    "HostAddress": "https://localhost:44320",
    "ApiKey": "dev-api-key-123",
    "Database": "development"
  },
  "staging": {
    "HostAddress": "https://staging.example.com",
    "ApiKey": "staging-api-key-456",
    "Database": "staging"
  },
  "prod": {
    "HostAddress": "https://api.example.com",
    "ApiKey": "prod-api-key-789",
    "Database": "production"
  }
}
                    

Using Environment Variables

                        # Use environment variables in .http files
GET {{HostAddress}}/api/users
Authorization: Bearer {{ApiKey}}
X-Database: {{Database}}
                    

Specifying Environment

                        # Use specific environment
httprunner requests.http --env dev
httprunner requests.http --env prod
                    

Variable Override Priority

Environment variables (loaded first)
Variables in .http file (override environment variables)

Response Assertions

Assertions allow you to validate HTTP responses automatically, making your tests more reliable.

Assertion Types

                        # Status code assertion
GET https://api.example.com/users
EXPECTED_RESPONSE_STATUS 200

# Response body content assertion
GET https://api.example.com/users/1
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_BODY "John Doe"

# Response header assertion
GET https://api.example.com/data
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_HEADERS "Content-Type: application/json"
                    

Multiple Assertions

                        GET https://api.example.com/users
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_BODY "users"
EXPECTED_RESPONSE_HEADERS "Content-Type: application/json"
EXPECTED_RESPONSE_HEADERS "Cache-Control: no-cache"
                    

Assertion Behavior

Status Code: Exact match required
Response Body: Substring match (response must contain the expected text)
Response Headers: Header must exist and contain the expected value
Request Success: All assertions must pass for the request to be considered successful

Timeout Configuration

Customize request timeouts for better control over HTTP operations. You can set both connection timeouts (for establishing connections) and read timeouts (for waiting for responses).

Default Timeouts

Connection timeout: 30 seconds (time to establish a connection)
Read timeout: 60 seconds (time to wait for response data)

Timeout Directives

Read Timeout (@timeout)

Sets the maximum time to wait for response data from an established connection:

                        # @timeout 600
GET https://example.com/api/long-running
                    

Connection Timeout (@connection-timeout)

Sets the maximum time to establish a connection with the server:

                        // @connection-timeout 10
GET https://example.com/api
                    

Time Units

By default, timeout values are in seconds, but you can specify explicit units:

ms - milliseconds (supports sub-second precision like 999ms or 1500ms)
s - seconds
m - minutes

Examples with Units

                        # Timeout in seconds (default)
# @timeout 30
GET https://example.com/api

###

# Timeout in minutes
# @timeout 2 m
GET https://example.com/api/slow

###

# Timeout in milliseconds (full precision supported)
# @timeout 5000 ms
GET https://example.com/api/fast

###

# Sub-second timeout (1.5 seconds)
# @timeout 1500 ms
GET https://example.com/api/quick

###

# Both timeouts customized
# @timeout 120
// @connection-timeout 10
GET https://example.com/api/data
                    

Practical Use Cases

                        # Long-running operations - wait up to 10 minutes
# @timeout 600
POST https://example.com/api/process
Content-Type: application/json

{"data": "large_dataset"}

###

# Quick health checks
# @timeout 5
// @connection-timeout 2
GET https://example.com/health

###

# Slow network conditions - allow more time
# @timeout 2 m
// @connection-timeout 30
GET https://dev.example.com/api
                    

💡 Tips

Both # and // comment styles are supported
Timeout directives must appear before the HTTP request they apply to
Can be combined with other directives (@name, @dependsOn, etc.)

Command Line Options

Basic Options

httprunner file.http

Run a single .http file

httprunner file1.http file2.http

Run multiple .http files

--discover

Recursively find and run all .http files

Output Options

--verbose

Show detailed request and response information

--pretty-json

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

--log

Save output to 'log' file

--log filename.txt

Save output to specified file

--report [format]

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

--export

Export individual HTTP requests and responses to separate timestamped log files

--no-banner

Run without displaying the donation banner

Request Control Options

--delay <milliseconds>

Add a delay between consecutive requests (in milliseconds). Example: --delay 500

--insecure

Accept invalid/self-signed SSL certificates for HTTPS connections (useful for development environments)

Environment Options

--env dev

Use 'dev' environment from http-client.env.json

--version, -v

Show version information

Examples

API Testing

                        # Test user registration and login flow
@baseUrl=https://api.example.com

# Register new user
POST {{baseUrl}}/auth/register
Content-Type: application/json

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

EXPECTED_RESPONSE_STATUS 201
EXPECTED_RESPONSE_BODY "user created"

# Login
POST {{baseUrl}}/auth/login
Content-Type: application/json

{
  "email": "test@example.com",
  "password": "securepass123"
}

EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_BODY "token"
                    

Health Checks

                        # Monitor service health
GET https://api.example.com/health
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_BODY "healthy"

# Check database connectivity
GET https://api.example.com/health/db
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_HEADERS "X-DB-Status: connected"
                    

CRUD Operations

                        @baseUrl=https://jsonplaceholder.typicode.com

# Create
POST {{baseUrl}}/posts
Content-Type: application/json

{
  "title": "Test Post",
  "body": "This is a test post",
  "userId": 1
}

EXPECTED_RESPONSE_STATUS 201

# Read
GET {{baseUrl}}/posts/1
EXPECTED_RESPONSE_STATUS 200

# Update
PUT {{baseUrl}}/posts/1
Content-Type: application/json

{
  "id": 1,
  "title": "Updated Post",
  "body": "This post has been updated",
  "userId": 1
}

EXPECTED_RESPONSE_STATUS 200

# Delete
DELETE {{baseUrl}}/posts/1
EXPECTED_RESPONSE_STATUS 200
                    

Best Practices

File Organization

Group related requests in the same .http file
Use descriptive file names (e.g., user-auth.http, health-checks.http)
Keep environment-specific files separate
Use comments to document complex requests

Variable Management

Define variables at the top of your .http files
Use descriptive variable names
Keep sensitive data in environment files, not in .http files
Use variable composition for complex URLs

Testing Strategy

Always include assertions for critical responses
Test both success and error scenarios
Use the --verbose flag when debugging
Generate reports with --report markdown or --report html for test documentation and CI/CD integration
Use --export to create file-based documentation of API requests and responses
Combine --export --pretty-json for well-formatted API documentation files
Save logs for CI/CD integration with --log

CI/CD Integration

                        # Example GitHub Actions step
- name: Run API Tests
  run: |
    httprunner --discover --env staging --log test-results.log --report html --export
    # Process test results, HTML report, and exported request/response files...
                    

Performance Considerations

Use --discover for comprehensive testing
Consider request timing when testing rate limits
Monitor response times with --verbose output