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

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
                    

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

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

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

--log

Save output to 'log' file

--log filename.txt

Save output to specified file

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
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
    # Process test results...
                    

Performance Considerations

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