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`:

```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:

```bash
# 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:

```json
{
  "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.