apophis-fastify/docs/cache-and-ci.md

Cache & CI/CD Integration

APOPHIS includes an incremental test cache that speeds up test runs by skipping unchanged routes. This document covers cache invalidation strategies and CI/CD integration.

How the Cache Works

The cache stores generated test commands per route in .apophis-cache.json:

{
  "version": 1,
  "entries": {
    "a1b2c3d4": {
      "routeHash": "a1b2c3d4",
      "schemaHash": "e5f6g7h8",
      "path": "/users",
      "method": "GET",
      "commands": [{ "params": {}, "headers": {} }],
      "timestamp": 1704067200000
    }
  }
}

Each entry is keyed by a hash of the route's path, method, and schema. If the schema changes, the entry is automatically invalidated.

Environment Behavior

Environment	Cache	Reason
production	Enabled by default	Set APOPHIS_DISABLE_CACHE=1 to opt-out
test	Enabled by default	Set APOPHIS_DISABLE_CACHE=1 to opt-out
development	Enabled by default	Speeds up iterative testing
default	Enabled by default	Backward compatible

Cache Invalidation

1. Automatic Invalidation

The cache is automatically invalidated when:

• A route's schema changes (detected via schema hash mismatch)
• The cache file is corrupted or has the wrong version

2. CI/CD Hints via Environment Variable

Set APOPHIS_CHANGED_ROUTES to invalidate specific routes on the next test run. The cache is checked during contract() and stateful() test runs:

# Exact path
APOPHIS_CHANGED_ROUTES=/users

# Multiple paths (comma-separated)
APOPHIS_CHANGED_ROUTES=/users,/items,/orders

# Method prefix
APOPHIS_CHANGED_ROUTES=GET /users,POST /orders

# Wildcards
APOPHIS_CHANGED_ROUTES=/api/*,/admin/**

Patterns support:

• Exact path: /users
• Method prefix: GET /users
• Single wildcard: /api/* (matches one segment)
• Double wildcard: /api/** (matches any depth)

3. CI/CD Hints via File

Create .apophis-hints.json in your project root:

{
  "changed": [
    "/users",
    "GET /items",
    "/api/**"
  ]
}

This is useful when your CI system can write a file but setting env vars is awkward.

CI/CD Examples

GitHub Actions

See docs/examples/github-actions.yml for a complete workflow.

Key steps:

1. Run tests with cache
2. If tests fail, re-run without cache to rule out cache issues
3. On main branch, clear cache after deployment

GitLab CI

See docs/examples/gitlab-ci.yml for a complete pipeline.

Best Practices

1. Commit the cache file? No — .apophis-cache.json should be in .gitignore
2. Cache in CI? Yes — cache .apophis-cache.json between runs for faster builds
3. Invalidate on deploy? Yes — set APOPHIS_CHANGED_ROUTES from your deployment diff
4. Debug cache issues? Set APOPHIS_LOG_LEVEL=debug to see cache hits/misses

Logging

Cache operations are logged at the info level:

[apophis] Invalidated 3 cached route(s) from CI/CD hints

Set APOPHIS_LOG_LEVEL=debug to see detailed cache operations.