Hepi is a command-line tool for testing REST APIs using YAML-based configurations. It supports environment management, dynamic data generation, and response chaining, allowing you to build complex test scenarios where results/state from one request is used in subsequent ones.
Installation
go install github.com/mitjafelicijan/hepi@latest
Basic example
environments:
local:
host: http://localhost:8080
requests:
login:
method: POST
url: "{{host}}/v1/auth/login"
description: "Authenticate and get a token"
headers:
Content-Type: "application/json"
json:
username: "admin"
password: "secret-password"
get_profile:
method: GET
url: "{{host}}/v1/profile"
description: "Fetch user profile using the token from login"
headers:
Authorization: "Bearer {{login.token}}"
Accept: "application/json"
groups:
auth_flow:
- login
- get_profile
CLI Usage
Basic Usage
# Execute a single request
hepi -env staging -file test.yaml -req create_user
# Execute multiple requests
hepi -env staging -file test.yaml -req login,get_profile
# Use a specific environment
hepi -env staging -file test.yaml -req get_status
Executing Groups
# Execute a group of requests defined in the YAML
hepi -env staging -file test.yaml -group auth_flow
Overriding Variables
You can override variables defined in the environments section by passing them as system environment variables. This is useful for CI/CD or quick testing.
# Override the 'host' variable from the command line
host=https://httpbin.org go run main.go generators.go -env test -file test.yaml -group all
Variable Precedence
When resolving {{variable}} placeholders, Hepi follows a strict lookup sequence. The first source to return a value wins.
- System Environment: Variables set in your shell or passed as command-line prefixes (e.g.,
HOST=... go run ...). - Local
.envFile: Variables loaded from a.envfile in the current directory. These provide defaults that can be overridden by the system environment. - YAML Environment: Variables defined within the specific
environmentsblock selected via the-envflag. - Persistent State: Key-value pairs stored in
.hepi.jsonfrom previous request executions (accessed via{{request_name.path.to.key}}).
Rationale
This hierarchy (System > .env > YAML > State) is designed for dynamic runtime overrides:
- Non-destructive testing: Override values from the CLI without modifying the static YAML configuration.
- Secret Management: Keep sensitive credentials in the environment or
.envfiles to avoid committing them to version control. - CI/CD Integration: Automated pipelines can inject configuration via environment variables which seamlessly take precedence.
Options
-env: The environment to use.-file: Path to the YAML configuration file.-req: Comma-separated list of request names to execute.-group: The name of a request group to execute.-headers: Show response headers in the output.-timeout: Request timeout duration (default: 10s).-state: Path to state file (default: .hepi.json).
Core Concepts
Environments
Environments allow you to define variables that change based on the target (e.g., local development vs. production). Each environment is a map of key-value pairs.
Requests
Requests are the individual API calls you want to perform. Each request specifies its method, URL, headers, and body (json, form, or files).
Groups
Groups are ordered lists of requests. Executing a group runs the requests in the specified sequence.
Configuration Syntax
The configuration is defined in a YAML file (e.g., test.yaml).
Substitution Syntax
Hepi uses two types of placeholders:
{{variable}}: Used for substituting values from:- Environment Variables: Values from a
.envfile (loaded automatically if present) or system environment variables. - Config Variables: Variables defined in the
environmentssection of the YAML. - Request State: Values captured from previous request responses (e.g.,
{{login_req.token}}). For arrays, use index notation (e.g.,{{setup_project.members.0.name}}).
- Environment Variables: Values from a
[[generator]]: Used for generating dynamic data (e.g.,[[email]],[[name]]).[[oneof: a, b, c]]: Randomly selects one of the provided values.
State Chaining (Persistence)
When a request is executed, its response (if it's JSON) is stored in a local .hepi.json file. This allows subsequent requests to reference any field from the response using the {{request_name.path.to.field}} syntax.
Data Generators (Fakers)
Hepi includes a wide range of generators for dynamic data. You can use these by wrapping the tag in double brackets, e.g., [[email]].
| Tag | Description |
|---|---|
name |
Random full name |
first_name |
Random first name |
last_name |
Random last name |
email |
Random email address |
username |
Random username |
password |
Random password |
url |
Random URL |
phone |
Random phone number |
int |
Random integer (0 - 1,000,000) |
datetime |
Random time string |
date |
Random date string |
timestamp |
Random timestamp |
uuid_hyphenated |
Random hyphenated UUID |
jwt |
Random JWT token |
ipv4 |
Random IPv4 address |
amount |
Random currency amount |
word |
Random word |
sentence |
Random sentence |
real_address |
Random real-world address |
cc_number |
Random credit card number |
cc_type |
Random credit card type |
domain_name |
Random domain name |
ipv6 |
Random IPv6 address |
mac_address |
Random MAC address |
unix_time |
Random Unix timestamp |
currency |
Random currency code |
Refer to generators.go for the latest implementation of these functions.
State File
Hepi stores response data in .hepi.json in the current directory. This file is updated after every successful request that returns a JSON response. You can inspect this file or delete it to clear the "memory" of previous requests.
Examples
1. Basic Request with Environments
This example shows how to define multiple environments and a simple GET request that uses the host variable.
environments:
local:
host: http://localhost:8080
api_key: "dev-key-123"
staging:
host: https://api.staging.example.com
api_key: "staging-key-456"
requests:
get_status:
method: GET
url: "{{host}}/v1/status"
description: "Check API health status"
headers:
X-API-Key: "{{api_key}}"
Accept: "application/json"
To execute this request:
hepi -env local -file test.yaml -req get_status
2. Request with Dynamic Data
Demonstrating the use of various generators to create a new resource with randomized data.
environments:
local:
host: http://localhost:8080
requests:
create_user:
method: POST
url: "{{host}}/v1/users"
description: "Create a new user with random profile data"
headers:
Content-Type: "application/json"
json:
name: "[[name]]"
email: "[[email]]"
username: "[[username]]"
password: "[[password]]"
profile:
bio: "[[sentence]]"
age: "[[int]]"
website: "[[url]]"
phone: "[[phone]]"
To execute this request:
hepi -env local -file test.yaml -req create_user
3. State Chaining (Persistence)
This scenario shows a full authentication flow where the token from the login response is reused in a subsequent request.
environments:
local:
host: http://localhost:8080
requests:
login:
method: POST
url: "{{host}}/v1/auth/login"
description: "Authenticate and get a token"
headers:
Content-Type: "application/json"
json:
username: "admin"
password: "secret-password"
get_profile:
method: GET
url: "{{host}}/v1/profile"
description: "Fetch user profile using the token from login"
headers:
Authorization: "Bearer {{login.token}}"
Accept: "application/json"
groups:
auth_flow:
- login
- get_profile
To execute this group:
hepi -env local -file test.yaml -group auth_flow
4. Form Data and Query Parameters
Example of a complex search request using both query parameters and URL-encoded form data.
environments:
local:
host: http://localhost:8080
requests:
search_items:
method: POST
url: "{{host}}/v1/search"
description: "Search items with filters and pagination"
params:
q: "[[word]]"
page: "1"
limit: "20"
sort: "[[oneof: asc, desc]]"
form:
category: "[[oneof: electronics, books, clothing]]"
include_out_of_stock: "true"
min_price: "[[int]]"
To execute this request:
hepi -env local -file test.yaml -req search_items
5. Nested JSON, Arrays, and Header Subscriptions
Showing how to handle complex data structures and reuse specific nested fields from previous state.
environments:
local:
host: http://localhost:8080
requests:
setup_project:
method: POST
url: "{{host}}/v1/projects"
description: "Create a complex project structure"
headers:
Content-Type: "application/json"
json:
title: "Project [[word]]"
settings:
visibility: "[[oneof: public, private]]"
notifications:
email: true
push: false
tags: ["active", "[[word]]", "[[word]]"]
members:
- name: "[[name]]"
role: "owner"
- name: "[[name]]"
role: "editor"
verify_project:
method: GET
url: "{{host}}/v1/projects/{{setup_project.id}}"
description: "Verify the project creation using the ID from the previous request"
headers:
X-Project-Owner: "{{setup_project.members.0.name}}"
Accept: "application/json"
To execute these requests:
hepi -env local -file test.yaml -req setup_project,verify_project
6. File Uploads (Multipart)
Hepi supports uploading files using multipart/form-data. You can combine form fields and files in the same request.
environments:
local:
host: http://localhost:8080
requests:
upload_document:
method: POST
url: "{{host}}/v1/upload"
description: "Upload a document with metadata"
form:
category: "financial"
priority: "high"
files:
document: "path/to/report.pdf"
thumbnail: "path/to/image.png"
To execute this request:
hepi -env local -file test.yaml -req upload_document
7. CRUD Operations (PUT, PATCH, DELETE)
Hepi supports all standard HTTP methods. This example shows how to update and delete resources.
requests:
update_user:
method: PUT
url: "{{host}}/v1/users/{{create_user.id}}"
json:
name: "[[name]]"
active: true
patch_settings:
method: PATCH
url: "{{host}}/v1/users/{{create_user.id}}/settings"
form:
theme: "dark"
notifications: "enabled"
delete_user:
method: DELETE
url: "{{host}}/v1/users/{{create_user.id}}"
params:
force: "true"
To execute these requests:
hepi -env local -file test.yaml -req update_user,patch_settings,delete_user