API Testing with Hurl

API Testing with Hurl

You can use Hurl to test your API endpoints effectively and integrate testing into your development workflow.

Hurl is a command-line tool that runs HTTP requests defined in a simple plain text format.

It can perform requests, capture values, and evaluate queries on headers and body responses. Hurl is very versatile: it can be used for both fetching data and testing HTTP sessions.

Quick Start with Taskfile (Recommended)

The easiest way to run your API tests is using the built-in Taskfile command:

# Run all API tests
task test

This command automatically:

• Uses the correct variables file (tests/hurl/.vars)
• Runs all tests in the tests/hurl/ directory
• Provides clear output about test results

Test Structure

Test Files Location

Tests are located in the tests/hurl/ directory:

tests/
├── hurl/
│   ├── .vars           # Variables file
│   ├── hello.hurl      # Basic endpoint test
│   └── users.hurl      # User management tests

Variables File (tests/hurl/.vars)

Contains environment-specific variables for your tests:

URL=http://localhost:8529/_db/foxx-sandbox/api-dev

Basic Test Example (hello.hurl)

GET {{URL}}/

HTTP 200
[Asserts]
jsonpath "$.info.name" == "foxx-service"

Running Tests

1. Using Taskfile (Recommended)

# Run all tests
task test

# First ensure your service is deployed
task deploy-docker

2. Manual Hurl Execution

If you have hurl installed locally (Installation instructions):

# Run all tests
hurl --test --variables-file tests/hurl/.vars tests/hurl/*.hurl

# Run specific test
hurl --test --variables-file tests/hurl/.vars tests/hurl/hello.hurl

# Run with JUnit output for CI
hurl --test --report-junit test-results/results.xml --variables-file tests/hurl/.vars tests/hurl/*.hurl

3. Docker-based Hurl Testing

Testing with hurl running in a Docker container:

# Run all tests
docker run --network host --rm -it -v "$(pwd)/tests/hurl":/app "orangeopensource/hurl:latest" --test --variables-file /app/.vars /app/*.hurl

# Run specific test
docker run --network host --rm -it -v "$(pwd)/tests/hurl":/app "orangeopensource/hurl:latest" --test --variables-file /app/.vars /app/hello.hurl

Writing Test Cases

Basic Structure

# Request
GET {{URL}}/endpoint

# Expected Response
HTTP 200

# Optional: Response body assertions
[Asserts]
jsonpath "$.status" == "success"
header "Content-Type" contains "application/json"

Advanced Example with POST

# Create a new user
POST {{URL}}/users
Content-Type: application/json
{
  "username": "testuser",
  "email": "test@example.com"
}

HTTP 201
[Asserts]
jsonpath "$.user.username" == "testuser"
jsonpath "$.user.email" == "test@example.com"

# Capture user ID for subsequent tests
[Captures]
userId: jsonpath "$.user._key"

Using Captured Variables

# Get the created user
GET {{URL}}/users/{{userId}}

HTTP 200
[Asserts]
jsonpath "$.user.username" == "testuser"

GitHub Actions Integration

The project automatically runs Hurl tests in GitHub Actions:

• On every push: Tests run against a fresh ArangoDB instance
• Pull requests: Tests must pass before merging
• Test reports: Results are uploaded as artifacts

CI Configuration

The GitHub Actions workflow:

1. Sets up ArangoDB in Docker
2. Deploys the Foxx service
3. Runs Hurl tests with proper variables
4. Uploads test results

Test Environment Setup

Local Development

Ensure your environment is set up correctly:

# 1. Start ArangoDB and deploy service
task docker-db-setup
task deploy-docker

# 2. Verify service is running
curl http://localhost:8529/_db/foxx-sandbox/api-dev/

# 3. Run tests
task test

Custom Variables

You can override variables for different environments:

# Development
URL=http://localhost:8529/_db/foxx-sandbox/api-dev

# Staging
URL=https://staging-api.example.com/api

# Production (use with caution)
URL=https://api.example.com/api

Best Practices

1. Test Organization

• Keep tests focused and atomic
• Use descriptive file names (user-management.hurl, authentication.hurl)
• Group related tests in the same file

2. Variable Usage

• Use variables for all environment-specific values
• Keep sensitive data out of test files
• Use meaningful variable names

3. Assertions

• Test both success and error cases
• Verify response structure and data types
• Check important headers (Content-Type, etc.)

4. Test Data

• Use predictable test data
• Clean up after tests when possible
• Avoid dependencies between test files

Troubleshooting

Common Issues

1. Tests fail with connection errors:

   # Verify service is running
   task list-services
   curl http://localhost:8529/_db/foxx-sandbox/api-dev/

2. Variable not found errors:

   # Check variables file
   cat tests/hurl/.vars
   # Ensure correct path in command

3. Authentication errors:

   • Verify database and service are set up correctly
   • Check if endpoints require authentication
   • Update variables file with correct credentials

4. HTTP version errors:

   • Use HTTP 200 instead of HTTP/* 200
   • Hurl is strict about HTTP version syntax

Debug Mode

Run Hurl with verbose output for debugging:

hurl --test --verbose --variables-file tests/hurl/.vars tests/hurl/hello.hurl

Resources

• Hurl Official Documentation
• Hurl Installation Guide
• Hurl Tutorial
• HTTP Testing Best Practices

Migration Notes

Note: Test files have been moved from .api-test/ to tests/hurl/ for better project organization. All commands and documentation have been updated to reflect this change.