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

Cache & CI/CD Integration

Note

: The incremental cache is an internal mechanism used by programmatic test runners (petit-runner, stateful-runner). CLI users do not interact with .apophis-cache.json directly. This document describes the internal caching behavior for advanced programmatic 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.