CtrlK
BlogDocsLog inGet started
Tessl Logo

testland/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.

76

Quality

95%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

Overview
Quality
Evals
Security
Files

SKILL.md

name:
cdn-cache-purge-tests
description:
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.

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

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

SKILL.md

tile.json