John Dvorak
117 lines
3.3 KiB
Markdown
117 lines
3.3 KiB
Markdown
# 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.
|