Getting Started

HTTPTests is an automated HTTP integration testing framework built specifically for GitHub Actions. It enables you to test APIs, proxies, and microservices with Docker isolation and zero configuration.

What is HTTPTests?

HTTPTests provides:

• Automated Testing: Run comprehensive HTTP integration tests in your CI/CD pipeline
• Docker Isolation: Each test suite runs in its own isolated environment
• Simple Configuration: Define tests using simple YAML and JSON files
• Multi-Service Support: Test complex architectures with multiple services
• Upstream Validation: Automatically track and validate proxy destinations

Prerequisites

Before you begin, ensure you have:

• A GitHub repository
• Basic knowledge of:
  • Docker and containers
  • HTTP protocols and status codes
  • YAML and JSON formats
• (Optional) Nginx or other proxy knowledge for advanced use cases

Your First Test Suite

Let's create a simple test suite that validates an Nginx proxy configuration.

Step 1: Create the Test Structure

In your repository, create a directory with a .httptests folder:

mkdir -p my-service/.httptests
cd my-service

Step 2: Create the Configuration File

Create .httptests/config.yml:

mock:
  network_aliases:
    - backend
    - api

nginx:
  environment:
    API_VERSION: v1

This configuration:

• Creates a mock HTTP service accessible as backend and api
• Sets an environment variable API_VERSION for the Nginx container

Step 3: Create the Test File

Create .httptests/test.json:

{
  "hosts": {
    "api.example.com": [
      {
        "paths": ["/health"],
        "method": "GET",
        "expectedStatus": 200,
        "expectedResponseHeaders": [
          ["Content-Type", "application/json"]
        ]
      },
      {
        "paths": ["/api/users"],
        "method": "GET",
        "expectedStatus": 200
      }
    ]
  }
}

This test configuration:

• Tests the host api.example.com
• Makes GET requests to /health and /api/users
• Validates status codes and response headers

Step 4: Create the Nginx Configuration

Create nginx.conf:

events {
    worker_connections 1024;
}

http {
    server {
        listen 80;
        server_name api.example.com;

        location /health {
            proxy_pass http://backend:80/;
            proxy_set_header Host $host;
        }

        location /api/ {
            proxy_pass http://backend:80/;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}

Step 5: Create the Dockerfile

Create Dockerfile:

FROM nginx:alpine
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Step 6: Add GitHub Actions Workflow

Create .github/workflows/test.yml:

name: HTTPTests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: serviceguards-com/httptests-action@v2
        with:
          httptests-directory: ./my-service

Step 7: Commit and Push

git add .
git commit -m "Add HTTPTests integration tests"
git push

What Happens Next?

When you push your code:

1. GitHub Actions triggers the workflow
2. HTTPTests discovers your .httptests directory
3. Docker Compose is generated from your config.yml
4. Services start: Mock service and your Nginx container
5. Tests run: HTTP requests are made and validated
6. Results display: Detailed output shows passed/failed assertions
7. Cleanup: All containers are automatically removed

Expected Output

You'll see output like this:

🔧 Adding X-Upstream-Target headers to nginx configs...
🚀 Starting environment...
🧪 Running tests for httptests-my-service

test_endpoints (__main__.IntegrationTests.test_endpoints) ... ok
  → Testing: GET api.example.com/health
    ✓ Status code: 200 (expected 200)
    ✓ Response header: content-type = application/json
  → Testing: GET api.example.com/api/users
    ✓ Status code: 200 (expected 200)
============================================================
Total assertions passed: 3
============================================================

Next Steps

Now that you have a basic test suite running:

• Learn about Installation options for advanced configurations
• Explore the config.yml reference for all configuration options
• Check out test.json reference for comprehensive test definitions
• Browse real-world examples for different use cases
• Discover advanced features like upstream tracking

Common First Steps

Add More Test Cases

Expand your test.json with more endpoints:

{
  "hosts": {
    "api.example.com": [
      {
        "paths": ["/health", "/status", "/version"],
        "method": "GET",
        "expectedStatus": 200
      },
      {
        "paths": ["/api/users"],
        "method": "POST",
        "expectedStatus": 201
      }
    ]
  }
}

Test Multiple Services

Update your config.yml to include more services:

mock:
  additional_ports:
    - 5001
    - 8080
  network_aliases:
    - backend
    - payment-service
    - auth-service

Add Header Validation

Validate that headers are forwarded correctly:

{
  "paths": ["/api/users"],
  "method": "GET",
  "expectedStatus": 200,
  "expectedRequestHeadersToUpstream": [
    ["X-Real-IP"],
    ["X-Forwarded-For"]
  ]
}

Troubleshooting

If you encounter issues:

1. Check file structure: Ensure .httptests folder exists with config.yml and test.json
2. Verify Dockerfile: Must be in the parent directory of .httptests
3. Review logs: Failed tests show nginx logs automatically
4. Test locally: Use Docker Compose to test your configuration

See the Troubleshooting guide for detailed solutions.