Troubleshooting

Common issues and solutions when using HTTPTests.

Directory Issues

ERROR: Directory not found

Error message:

❌ ERROR: Directory not found: ./my-service

Cause: The specified httptests-directory path doesn't exist in your repository.

Solutions:

1. Verify the path in your workflow file matches your repository structure
2. Check for typos in the directory name
3. Ensure you're using the correct relative path from repository root

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

# Wrong
- uses: serviceguards-com/httptests-action@v2
  with:
    httptests-directory: ./service/api-gateway   # Typo: 'service' vs 'services'

ERROR: .httptests directory not found

Error message:

❌ ERROR: .httptests directory not found in ./my-service

Cause: The .httptests folder doesn't exist in the specified directory.

Solutions:

1. Create a .httptests directory (note the leading dot)
2. Ensure it's committed to your repository (not in .gitignore)
3. Check that the folder name is exactly .httptests (lowercase)

# Create the directory
mkdir -p my-service/.httptests

# Verify it's created
ls -la my-service/

ERROR: Missing test.json

Error message:

❌ ERROR: Missing test.json in ./my-service/.httptests

Cause: The test.json file is missing from your .httptests directory.

Solutions:

1. Create a test.json file in .httptests/
2. Ensure the filename is exactly test.json (lowercase)
3. Verify it contains valid JSON

# Check files in .httptests
ls -la my-service/.httptests/

# Should contain:
# - config.yml
# - test.json

Docker Issues

ERROR: Failed to start test environment

Error message:

❌ ERROR: Failed to start test environment

Common causes and solutions:

Missing Dockerfile

Cause: No Dockerfile in the parent directory of .httptests.

Solution: Create a Dockerfile in the same directory as .httptests:

my-service/
├── Dockerfile          ← Must exist here
├── nginx.conf
└── .httptests/
    ├── config.yml
    └── test.json

Docker Build Errors

Cause: Syntax errors or issues in your Dockerfile.

Solution: Test your Dockerfile locally:

cd my-service
docker build -t test-image .

Port Conflicts

Cause: Port 80 is already in use or not exposed properly.

Solution: Ensure your Dockerfile exposes port 80:

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

Service Not Ready / Timeout

Symptom: Tests fail with connection errors or timeout messages.

Causes:

1. Service takes too long to start
2. Service crashes immediately after starting
3. Service doesn't listen on port 80

Solutions:

Check Service Health

Add a health check to your Dockerfile:

FROM nginx:alpine
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80

HEALTHCHECK --interval=5s --timeout=3s --retries=3 \
  CMD wget --quiet --tries=1 --spider http://localhost/ || exit 1

CMD ["nginx", "-g", "daemon off;"]

Review Container Logs

Check nginx logs in the test output (automatically shown on failure):

=== Nginx Logs ===
2025/10/30 12:00:00 [emerg] 1#1: invalid number of arguments in "server_name" directive

Test Locally with Docker Compose

Generate and test the Docker Compose setup locally:

cd my-service
# Create a test docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: "3.9"
services:
  mock:
    image: mendhak/http-https-echo:18
    networks:
      default:
        aliases:
          - backend
  nginx:
    build: .
    ports:
      - "80:80"
    depends_on:
      - mock
EOF

docker compose up
# Test in another terminal
curl -H "Host: api.example.com" http://localhost/health

Test Failures

Tests Pass Locally but Fail in CI

Common causes:

Environment Differences

Cause: Different environment variables or configurations.

Solution: Use the nginx.environment configuration:

# .httptests/config.yml
nginx:
  environment:
    API_HOST: backend
    API_PORT: 80

Timing Issues

Cause: Service needs more time to start in CI environment.

Solution: Ensure your service starts quickly or add health checks.

Assertion Failures

Unexpected Status Code

Error:

✗ Status code: 404 (expected 200)

Debug steps:

1. Check nginx configuration for correct location blocks
2. Verify proxy_pass URLs are correct
3. Test the endpoint manually with curl
4. Review mock service network aliases

Header Mismatch

Error:

✗ Response header: content-type = text/html (expected application/json)

Debug steps:

1. Check if nginx is serving an error page (404, 502, etc.)
2. Verify mock service is returning correct headers
3. Test with a simpler endpoint first
4. Review nginx logs for errors

Upstream Header Not Found

Error:

✗ Expected header 'X-Upstream-Target' not found in upstream request

Solutions:

1. Ensure automatic header injection is working (it runs automatically)
2. Verify proxy_pass directives exist in nginx config
3. Check nginx config syntax is correct
4. Manually add the header if needed:

location /api/ {
    proxy_pass http://backend:80/;
    proxy_set_header X-Upstream-Target "backend:80";
}

Configuration Issues

Invalid YAML in config.yml

Error:

Error parsing config.yml: ...

Solutions:

1. Validate YAML syntax at yamllint.com
2. Check indentation (must use spaces, not tabs)
3. Ensure proper quoting of special characters

# Correct
mock:
  network_aliases:
    - backend
    - api

# Wrong (mixing spaces and tabs)
mock:
	network_aliases:
    - backend

Invalid JSON in test.json

Error:

Error parsing test.json: ...

Solutions:

1. Validate JSON at jsonlint.com
2. Check for trailing commas (not allowed in JSON)
3. Ensure all strings use double quotes

// Correct
{
  "hosts": {
    "api.example.com": []
  }
}

// Wrong (trailing comma)
{
  "hosts": {
    "api.example.com": [],
  }
}

Network Alias Not Working

Symptom: Nginx can't reach backend service via network alias.

Debug steps:

1. Verify alias is defined in config.yml:

mock:
  network_aliases:
    - backend    ← Must match proxy_pass destination

2. Check nginx proxy_pass uses the correct alias:

# Must match network alias
proxy_pass http://backend:80/;

3. If using additional ports, ensure they're configured:

mock:
  additional_ports:
    - 5001       ← Required if proxying to :5001
  network_aliases:
    - backend

Performance Issues

Tests Run Slowly

Causes:

1. Slow Docker image builds
2. Large number of test cases
3. Service takes long to start

Solutions:

Optimize Docker Build

Use multi-stage builds and layer caching:

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

Parallelize Tests

Use matrix strategy to run multiple suites in parallel:

strategy:
  matrix:
    service: [service-a, service-b, service-c]
steps:
  - uses: serviceguards-com/httptests-action@v2
    with:
      httptests-directory: ./${{ matrix.service }}

Getting Help

If you continue to experience issues:

1. Check Examples: Review working examples for reference
2. GitHub Issues: Open an issue with:
   • Your workflow file
   • Directory structure
   • Error messages
   • Relevant configuration files
3. Minimal Reproduction: Create a minimal example that reproduces the issue

Useful Debug Information

When reporting issues, include:

# Your workflow file
name: HTTPTests
...

# Directory structure
my-service/
├── Dockerfile
├── nginx.conf
└── .httptests/
    ├── config.yml
    └── test.json

# Error output from GitHub Actions
❌ ERROR: ...

# Nginx configuration (relevant parts)
location /api/ {
    proxy_pass http://backend:80/;
}

Common Pitfalls

Forgetting the Leading Dot

❌ Wrong: httptests/config.yml
✅ Correct: .httptests/config.yml

Incorrect Path in Workflow

❌ Wrong: httptests-directory: my-service (missing ./)
✅ Correct: httptests-directory: ./my-service

Missing Dependencies

❌ Wrong: Dockerfile without EXPOSE
✅ Correct: Dockerfile with EXPOSE 80

Case Sensitivity

❌ Wrong: Test.json or CONFIG.yml
✅ Correct: test.json and config.yml

Network Alias Mismatch

❌ Wrong:

network_aliases: [backend]
# nginx: proxy_pass http://api:80/;  ← Mismatch!

✅ Correct:

network_aliases: [backend]
# nginx: proxy_pass http://backend:80/;  ← Match!