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	Disabled	No file I/O, no cache hits needed
test	Disabled	Tests should be deterministic, no cache pollution
development	Enabled	Speeds up iterative testing
default	Enabled	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.