cdn-cache-purge-tests
Overview
CDN cache-purge tests verify that the
write-origin-then-invalidate-edge sequence works end-to-end -
the most-likely-broken cache integration in real deployments.
Per
developers.cloudflare.com/cache/how-to/purge-cache/,
Cloudflare offers five purge methods (Single-file, Everything,
Cache-tags, Hostname, Prefix). Fastly's surrogate-key pattern
and CloudFront's invalidation API offer similar shapes.
When to use
- Verifying a new purge integration works end-to-end.
- Regression-testing the write-origin-then-purge sequence.
- Auditing existing purge logic before a deploy.
- Investigating "users see stale content after a write."
Authoring
Cloudflare - purge by URL
curl -X POST \
"https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/purge_cache" \
-H "Authorization: Bearer ${CF_API_TOKEN}" \
-H "Content-Type: application/json" \
--data '{"files":["https://example.com/api/users/1"]}'
Response:
{ "success": true, "result": { "id": "...." } }
Cloudflare - purge by cache-tag (Enterprise)
curl -X POST "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/purge_cache" \
-H "Authorization: Bearer ${CF_API_TOKEN}" \
--data '{"tags":["user-1","posts-feed"]}'
The response headers from the origin must have included
Cache-Tag: user-1, posts-feed for this to work.
Fastly - purge by surrogate-key
curl -X POST "https://api.fastly.com/service/${SERVICE_ID}/purge/${SURROGATE_KEY}" \
-H "Fastly-Key: ${FASTLY_API_TOKEN}"
Origin responses include Surrogate-Key: user-1 posts-feed (space-separated).
CloudFront - invalidation
aws cloudfront create-invalidation \
--distribution-id ${DIST_ID} \
--paths "/api/users/1" "/api/users/1/*"
Cloud-side wait + propagation. Returns an InvalidationId; poll
status via get-invalidation.
Running - end-to-end test
The canonical purge test:
import requests, time
def test_write_then_purge_serves_fresh():
# 1. Origin write
origin_response = requests.post(
"https://origin.example.com/api/users/1",
json={"name": "Alice"},
headers={"Authorization": f"Bearer {ADMIN_TOKEN}"},
)
assert origin_response.status_code == 200
# 2. Verify edge has the *old* value (might or might not - cache hit)
edge_before = requests.get("https://example.com/api/users/1")
cache_status_before = edge_before.headers.get("cf-cache-status")
# 3. Trigger purge
purge = requests.post(
f"https://api.cloudflare.com/client/v4/zones/{ZONE_ID}/purge_cache",
headers={"Authorization": f"Bearer {CF_API_TOKEN}"},
json={"files": ["https://example.com/api/users/1"]},
)
assert purge.json()["success"]
# 4. Wait for global propagation (Cloudflare typically <30s)
time.sleep(10)
# 5. Verify edge fetches fresh from origin
edge_after = requests.get("https://example.com/api/users/1")
cache_status_after = edge_after.headers.get("cf-cache-status")
# Either MISS (just fetched) or HIT (re-cached fresh value)
assert cache_status_after in ("MISS", "HIT", "EXPIRED")
assert edge_after.json()["name"] == "Alice"
Cache-Status header verification
| Header | CDN | Common values |
|---|
cf-cache-status | Cloudflare | HIT, MISS, EXPIRED, BYPASS, DYNAMIC, REVALIDATED |
x-cache | Fastly | HIT, MISS, HIT-CLUSTER, HIT-CLUSTER-WAIT |
x-cache | CloudFront | Hit from cloudfront, Miss from cloudfront |
age | RFC 9111 standard | Seconds since cached |
Multi-region propagation
EDGES = [
"https://example.com", # default
"https://eu.example.com", # geo-routed
"https://ap.example.com",
]
def test_purge_propagates_globally():
# Pre-cache in each region
for url in EDGES:
requests.get(url + "/api/users/1")
# Trigger purge
purge_url(API, "/api/users/1")
# Wait for global propagation
time.sleep(30)
# Verify each region serves fresh
for url in EDGES:
r = requests.get(url + "/api/users/1")
assert r.json()["name"] == "Alice"
Client-tier cache-control
The purge test proves the edge refreshes; the client tier can still serve
stale from the browser's own cache. Browser-side verification - asserting
the browser acts on Cache-Control as intended (served-from-cache via
CDP, ETag If-None-Match → 304 round-trips, Workbox service-worker
strategies, normal-vs-hard reload semantics) with Playwright across the
Chromium / Firefox / WebKit matrix - is in
references/browser-cache-control.md,
with deeper recipes in
references/playwright-cache-recipes.md.
Asserting only which header the server emits needs no browser - keep that
in the project's HTTP-level runner.
Parsing results
| Field | Use |
|---|
cf-cache-status: HIT | Served from edge cache |
cf-cache-status: MISS | Origin pull just happened |
cf-cache-status: EXPIRED | Stale; revalidated from origin |
cf-cache-status: BYPASS | Cache deliberately skipped (e.g., uncacheable response) |
cf-cache-status: DYNAMIC | Not cached at all |
age: N | Per RFC 9111: seconds since cached |
For tests: assert on the transition (HIT → MISS after purge),
not on the absolute state.
CI integration
jobs:
cdn-purge-smoke:
if: github.event_name == 'deployment_status' && github.event.deployment_status.state == 'success'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Write to origin
env:
ADMIN_TOKEN: ${{ secrets.ADMIN_TOKEN }}
run: ./scripts/write-test-fixture.sh
- name: Purge edge
env:
CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
run: ./scripts/purge-test-paths.sh
- name: Verify edge serves fresh
run: pytest tests/cdn/test_purge_propagation.py
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
time.sleep(60) between purge + assertion | Slow; sometimes shorter / sometimes longer | Poll cf-cache-status until MISS (timeout 30s) |
| Test purge against prod | Pollutes prod cache; rate-limited | Dedicated test domain + zone |
| Purge-everything for smoke test | Massive cache flush; alarming for ops | Single-file or tag-based |
| Don't test multi-region | Edge in test region; user in another sees stale | Verify across regions |
No Cache-Tag / Surrogate-Key on origin | Group-purge has nothing to target | Origin must set tags |
| Use only cf-cache-status to verify fresh | Could be HIT of newly-purged fresh fetch | Compare response body to known fresh state |
| Skip purge-key naming review | Hot keys (all, feed) become noisy | Per-resource tagging strategy |
| Assume purge is synchronous | Cloudflare: <30s; CloudFront: minutes | Plan for async; poll |
Limitations
- Per-vendor behaviour differs. Cloudflare and Fastly purge
in seconds; CloudFront invalidations take longer. Test against
the actual vendor in use.
- Purge rate limits. Cloudflare has per-zone tag-purge limits;
Fastly has API-call rate limits. Tests can hit these.
- Edge node consistency. Even within a CDN, edge nodes refresh
at slightly different times. Cross-edge tests need tolerance.
- Doesn't test the origin's behaviour. If origin sends
uncacheable responses, purge does nothing. Pair with origin
Cache-Control assertions in the project's HTTP-level runner and the
browser-tier tests in
references/browser-cache-control.md.
References