Installation

Learn how to integrate HTTPTests into your GitHub Actions workflows with different configurations and strategies.

Basic Installation

The simplest way to use HTTPTests is with a single test suite:

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

Input Parameters

HTTPTests accepts the following input parameters:

httptests-directory (required)

Path to the directory containing the .httptests folder.

- uses: serviceguards-com/httptests-action@v2
  with:
    httptests-directory: ./services/api-gateway

Examples:

• . - Root directory
• ./my-service - Service in subdirectory
• ./services/api-gateway - Nested directory structure

python-version (optional)

Python version to use for running tests. Defaults to 3.x.

- uses: serviceguards-com/httptests-action@v2
  with:
    httptests-directory: ./my-service
    python-version: '3.11'

Multiple Test Suites

If you have multiple services to test, use a matrix strategy to run them in parallel.

Matrix Strategy (Recommended)

name: HTTPTests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        test-suite:
          - ./services/api-gateway
          - ./services/user-service
          - ./services/payment-service
    steps:
      - uses: actions/checkout@v4
      - uses: serviceguards-com/httptests-action@v2
        with:
          httptests-directory: ${{ matrix.test-suite }}

Benefits:

• ✅ Tests run in parallel
• ✅ Faster overall execution
• ✅ Isolated environments
• ✅ Clear per-service results

Separate Jobs

Alternatively, define separate jobs for each service:

name: HTTPTests
on: [push, pull_request]

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

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

Benefits:

• ✅ Explicit job names in Actions UI
• ✅ Easy to add conditional execution
• ✅ Different configurations per service

Advanced Configurations

Only Run on Specific Paths

Run tests only when relevant files change:

name: HTTPTests
on:
  push:
    paths:
      - 'services/api-gateway/**'
      - '.github/workflows/test.yml'
  pull_request:
    paths:
      - 'services/api-gateway/**'

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

Conditional Execution

Skip tests on certain conditions:

jobs:
  test:
    runs-on: ubuntu-latest
    if: "!contains(github.event.head_commit.message, '[skip tests]')"
    steps:
      - uses: actions/checkout@v4
      - uses: serviceguards-com/httptests-action@v2
        with:
          httptests-directory: ./my-service

Continue on Error

Allow other tests to continue even if one fails:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        test-suite: [./service-a, ./service-b, ./service-c]
      fail-fast: false
    steps:
      - uses: actions/checkout@v4
      - uses: serviceguards-com/httptests-action@v2
        with:
          httptests-directory: ${{ matrix.test-suite }}

Schedule Regular Tests

Run tests on a schedule (e.g., nightly):

name: Nightly Tests
on:
  schedule:
    - cron: '0 2 * * *'  # 2 AM UTC daily
  workflow_dispatch:      # Allow manual trigger

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

Monorepo Setup

For monorepos with multiple services:

name: HTTPTests
on: [push, pull_request]

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      api: ${{ steps.filter.outputs.api }}
      gateway: ${{ steps.filter.outputs.gateway }}
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v2
        id: filter
        with:
          filters: |
            api:
              - 'services/api/**'
            gateway:
              - 'services/gateway/**'

  test-api:
    needs: detect-changes
    if: needs.detect-changes.outputs.api == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: serviceguards-com/httptests-action@v2
        with:
          httptests-directory: ./services/api

  test-gateway:
    needs: detect-changes
    if: needs.detect-changes.outputs.gateway == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: serviceguards-com/httptests-action@v2
        with:
          httptests-directory: ./services/gateway

Requirements

Runner Requirements

• Operating System: ubuntu-latest (recommended)
• Docker: Available by default on GitHub's Ubuntu runners
• Python: Automatically set up by the action

Repository Structure

your-repo/
├── .github/
│   └── workflows/
│       └── test.yml
├── my-service/
│   ├── Dockerfile          # Required
│   ├── nginx.conf          # Your service config
│   └── .httptests/
│       ├── config.yml      # Required
│       └── test.json       # Required

Key points:

• Dockerfile must be in the parent directory of .httptests
• .httptests directory must contain both config.yml and test.json
• Service must expose port 80 (or configure accordingly)

Workflow Examples

Minimal Example

name: Test
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: serviceguards-com/httptests-action@v2
        with:
          httptests-directory: .

Production Ready Example

name: HTTPTests
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    strategy:
      matrix:
        service:
          - name: API Gateway
            path: ./services/api-gateway
          - name: User Service
            path: ./services/user-service
          - name: Payment Service
            path: ./services/payment-service
      fail-fast: false
    
    name: Test ${{ matrix.service.name }}
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Run HTTPTests
        uses: serviceguards-com/httptests-action@v2
        with:
          httptests-directory: ${{ matrix.service.path }}
          python-version: '3.11'

Next Steps

• Learn about config.yml configuration
• Explore test.json test definitions
• See real-world examples
• Read about matrix testing strategies