Testland
Browse all skills & agents

cdn-cache-purge-tests

Wraps CDN cache-purge testing patterns for Cloudflare (POST /zones/{zone_id}/purge_cache, single-file / everything / cache-tags / hostname / prefix), Fastly (POST purge-by-key / purge-all, surrogate-keys via Surrogate-Key header), and CloudFront (CreateInvalidation API + paths). Covers end-to-end test patterns (write origin → trigger purge → assert edge serves fresh), purge-propagation delay testing (typically 1-30s globally), surrogate-key + cache-tag patterns for group-purge, and Cache-Status header verification (cf-cache-status: HIT/MISS/BYPASS). Use when designing or auditing CDN cache-invalidation workflows.

Install with skills.sh (any agent)

npx skills add testland/qa --skill cdn-cache-purge-tests
View source

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/ (opens in new window), 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

HeaderCDNCommon values
cf-cache-statusCloudflareHIT, MISS, EXPIRED, BYPASS, DYNAMIC, REVALIDATED
x-cacheFastlyHIT, MISS, HIT-CLUSTER, HIT-CLUSTER-WAIT
x-cacheCloudFrontHit from cloudfront, Miss from cloudfront
ageRFC 9111 standardSeconds 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"

Parsing results

FieldUse
cf-cache-status: HITServed from edge cache
cf-cache-status: MISSOrigin pull just happened
cf-cache-status: EXPIREDStale; revalidated from origin
cf-cache-status: BYPASSCache deliberately skipped (e.g., uncacheable response)
cf-cache-status: DYNAMICNot cached at all
age: NPer 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-patternWhy it failsFix
time.sleep(60) between purge + assertionSlow; sometimes shorter / sometimes longerPoll cf-cache-status until MISS (timeout 30s)
Test purge against prodPollutes prod cache; rate-limitedDedicated test domain + zone
Purge-everything for smoke testMassive cache flush; alarming for opsSingle-file or tag-based
Don't test multi-regionEdge in test region; user in another sees staleVerify across regions
No Cache-Tag / Surrogate-Key on originGroup-purge has nothing to targetOrigin must set tags
Use only cf-cache-status to verify freshCould be HIT of newly-purged fresh fetchCompare response body to known fresh state
Skip purge-key naming reviewHot keys (all, feed) become noisyPer-resource tagging strategy
Assume purge is synchronousCloudflare: <30s; CloudFront: minutesPlan 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 tests via browser-cache-control-tests.

References

Related skills

browser-cache-control-tests

Wraps browser-side Cache-Control testing with Playwright (Cypress for legacy stacks): asserting response Cache-Control headers from Network events, ETag round-trips (If-None-Match → 304), service-worker strategies (Workbox cacheFirst / networkFirst / staleWhileRevalidate), and reload semantics (normal vs hard). Covers MDN Cache-Control + RFC 9111. Use when auditing browser-tier caching in E2E tests. For CDN-edge purge use cdn-cache-purge-tests; for the reverse-proxy tier use varnish-test-vtc-syntax; for an app-tier store use redis-cache-tests; SWR directive semantics live in stale-while-revalidate-reference.

cache-coherence-patterns-reference

Pure-reference catalog of cache-coherence patterns across the request path. Defines the five-tier cache stack (browser → CDN → reverse-proxy → application → data store), the per-tier cache-writing patterns (cache-aside, write-through, write-back, write-around, refresh-ahead), and the canonical invalidation strategies (TTL-only, event-driven purge, surrogate keys, version-tagged URLs, soft purge), plus an anti-pattern table and a worked multi-tenant coherence-test example. Deep detail - the RFC 9111 Cache-Control / Vary / ETag directive tables and the cross-tier coherence + per-tier test surface - lives in references/. Use for pattern selection, Cache-Control header design, and coherence audits; use a cache-key-collision check when the question is whether two requests in an existing system collide on a concrete key scheme. Consumed by redis-cache-tests, cdn-cache-purge-tests, varnish-test-vtc-syntax, browser-cache-control-tests, and the cache-key-collision check.

cache-key-discriminator-audit

Audits whether a cache key carries every discriminator the cached response actually depends on, so two requests that must not share a slot cannot collide. Ranks identity discriminators (tenant, user, authorization scope, plan tier) above presentation ones (locale, region, currency, feature flag), maps each missing discriminator to the data-exposure or wrong-content consequence it causes, classifies each key-and-value pair into a critical / high / medium severity band (including the Python lru_cache-on-an-instance-method trap), and writes the fix as a namespaced key builder plus the matching HTTP Vary header. Use when a cache key is being designed or changed, when a per-user or per-tenant response is about to be stored in a shared cache or CDN, or when investigating a report that one user or tenant saw another's data.

cache-stampede-reference

Pure-reference catalog of cache-stampede (thundering-herd) phenomena and mitigations: parallel misses on key expiry trigger simultaneous recomputation (often congestion-collapse), countered by three families - locking, external recomputation near-expiry, and probabilistic early expiration via XFetch (`(time() - delta * beta * log(rand(0,1))) >= expiry`). Use when designing cache-refresh strategy or diagnosing a stampede incident. This is the single failure-mode pattern; for the broader multi-tier pattern catalog use cache-coherence-patterns-reference, for the stale-while-revalidate / stale-if-error extensions use stale-while-revalidate-reference; a reference consumed by redis-cache-tests, not a runnable test.

memcached-tests

Wraps Memcached cache testing against a real container: an inline set/get/expire/no-persistence worked example, with the exhaustive protocol-command tests (set/get/add/cas/incr/decr, TTL 0=never-expire / 30-day Unix-timestamp boundary) and the LRU-eviction, consistent-hashing distribution, ElastiCache Auto Discovery, and CI-wiring deep-dives in references/. Use when writing tests for an application that uses Memcached as its primary cache, when verifying ElastiCache Memcached cluster behaviour, or when contrasting Memcached eviction and distribution semantics against Redis.

redis-cache-tests

Wraps Redis cache testing: EXPIRE / PEXPIRE / TTL verification (Redis 7+ NX/XX/GT/LT flags), cache-aside write-then-invalidate (write source → DEL key → assert fresh read), eviction under memory pressure (maxmemory + allkeys-lru), pub/sub invalidation across nodes, and tenant key-namespacing. Use when Redis is the app's primary cache. For a Memcached app-tier store use memcached-tests; for the browser/HTTP tier use browser-cache-control-tests; a runnable test, not the cache-stampede-reference or cache-coherence-patterns-reference catalogs.

stale-while-revalidate-reference

Pure-reference catalog of RFC 5861's stale-while-revalidate + stale-if-error Cache-Control extensions. Defines stale-while-revalidate=N (caches MAY serve a stale response while asynchronously revalidating, up to N seconds after expiry) and stale-if-error=N (caches MAY serve stale on 5xx upstream errors). Distinguishes from RFC 9111's must-revalidate (forbids serving stale) and from manual cache-aside refresh (synchronous). Covers the interaction with the freshness lifetime (max-age) and the cache-stampede-mitigation properties. Use when designing the cache-refresh boundary or auditing existing Cache-Control headers.

varnish-test-vtc-syntax

Wraps the varnishtest CLI + VTC (Varnish Test Case) syntax for testing VCL configurations. Covers the VTC test-file format (varnishtest scripts with server { ... } + client { ... } + varnish v1 -vcl+backend { ... } blocks), the grace-mode + saint-mode behaviours (stale-while-revalidate + stale-if-error equivalents in VCL), the PURGE method handler pattern (vcl_purge subroutine + ACL guards), and surrogate-key invalidation via xkey vmod. Use when authoring or testing Varnish-based caching layers.