homelab-frontend/INTEGRATION_TESTS.md

Integration Tests

Integration tests call the real deployed gateway to verify X-Service routing works end-to-end.

Quick Start

Local Test (requires running gateway)

# Terminal 1: Start the gateway
CONFIG_PATH=k8s/configmap.yaml go run ./cmd/gateway

# Terminal 2: Run tests
./scripts/test-integration.sh

Cluster Test (production gateway)

GATEWAY_URL=https://api.riotpiao.com ./scripts/test-integration.sh

Canary Deployment (scale to 1, test, scale back)

./scripts/test-canary.sh

# Or with custom settings:
NAMESPACE=api DEPLOYMENT=api-gateway REPLICAS=3 ./scripts/test-canary.sh

Configuration

Create .dev.test.local (gitignored) with:

GATEWAY_URL=https://api.riotpiao.com
TEST_JWT_TOKEN=eyJ...  # Real JWT from Authentik
SKIP_AUTH_TESTS=false
TEST_TIMEOUT=30

Or set env vars directly:

export GATEWAY_URL=https://api.riotpiao.com
export TEST_JWT_TOKEN=eyJ...
export SKIP_AUTH_TESTS=false
go test -tags integration -v ./internal/serviceadapter

Test Matrix

Test	Type	Expected	Notes
Health check	GET /healthz	200 OK	Always works
SQS list-queues	GET X-Service: sqs	200 or 502	502 if service unreachable
S3 list-objects	GET X-Service: s3	200 or 502	502 if service unreachable
Memory query	POST X-Service: memory	200 or 502	502 if service unreachable
Service not found	GET X-Service: nonexistent	404	Routing error
Resource not found	GET X-Service: sqs X-Resource: invalid	404	Resource error
IAM with JWT	GET X-Service: iam + Bearer token	200 or 502	Requires valid JWT
Missing X-Service	GET (no header)	404	Routed to default handler

Canary Deployment Flow

Current: 3/3 replicas running
    ↓
scale → 1/3 replicas
    ↓
wait for pod ready
    ↓
run integration tests
    ├─ PASS → scale → 3/3 replicas ✅
    └─ FAIL → keep 1/3 for debugging ❌

Running in CI

Add to .gitea/workflows/ci.yaml:

- name: Integration Tests
  run: |
    GATEWAY_URL=https://api.riotpiao.com \
    SKIP_AUTH_TESTS=true \
    TEST_TIMEOUT=30 \
    go test -tags integration -v ./internal/serviceadapter

Debugging Failed Tests

If a test fails:

1. Check pod logs:

   kubectl -n api logs -l app=api-gateway --tail=50
   

2. Check service availability:

   kubectl get svc -A | grep -E "sqs|minio|authentik|poimen"
   

3. Test service directly:

   kubectl -n sqs port-forward svc/management-service 9090:9090
   curl http://localhost:9090/sqs/queues
   

4. Check ConfigMap:

   kubectl get configmap api-gateway-config -n api -o yaml | grep -A50 "adapters:"
   

Notes

• Auth tests are skipped by default (SKIP_AUTH_TESTS=true)
• To test with JWT, set TEST_JWT_TOKEN and SKIP_AUTH_TESTS=false
• Services in different namespaces may not be reachable from the gateway (NetworkPolicy)
• Canary tests expect /healthz endpoint to be available