offline-fallback-tests
/offline-fallback-tests
Build-an-X workflow that emits the offline-fallback test suite. Walks the eight Jake Archibald offline recipes per [web.dev/articles/offline-cookbook][off-cookbook] (`Cache only`, `Network only`, `Cache, falling back to network`, `Cache and network race`, `Network falling back to cache`, `Cache then network`, `Generic fallback`, `Service Worker side templating`), maps each recipe to its assertion shape, layers the Workbox `offlineFallback()` recipe per [developer.chrome.com/docs/workbox/modules/workbox-recipes][wb-recipes], and pins the offline storage strategy (Cache Storage vs IndexedDB vs S
- Author
- testland ↗
- Repository
- qa ↗
- Licence
- MIT
- Last repository change
- 20.10.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 9
No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Build-an-X workflow that emits the offline-fallback test suite. Walks the eight Jake Archibald offline recipes per [web.dev/articles/offline-cookbook][off-cookbook] (`Cache only`, `Network only`, `Cache, falling back to network`, `Cache and network race`, `Network falling back to cache`, `Cache then network`, `Generic fallback`, `Service Worker side templating`), maps each recipe to its assertion shape, layers the Workbox `offlineFallback()` recipe per [developer.chrome.com/docs/workbox/modules/workbox-recipes][wb-recipes], and pins the offline storage strategy (Cache Storage vs IndexedDB vs S
Original author description
Build-an-X workflow that emits the offline-fallback test suite. Walks the eight Jake Archibald offline recipes per [web.dev/articles/offline-cookbook][off-cookbook] (`Cache only`, `Network only`, `Cache, falling back to network`, `Cache and network race`, `Network falling back to cache`, `Cache then network`, `Generic fallback`, `Service Worker side templating`), maps each recipe to its assertion shape, layers the Workbox `offlineFallback()` recipe per [developer.chrome.com/docs/workbox/modules/workbox-recipes][wb-recipes], and pins the offline storage strategy (Cache Storage vs IndexedDB vs S
How it works
- Overview
- When to use
- Workflow
- Worked example: a 4-route news PWA
- Anti-patterns
- Limitations
- References
SKILL.md preview
---
name: offline-fallback-tests
description: "Build-an-X workflow that emits the offline-fallback test suite. Walks the eight Jake Archibald offline recipes per [web.dev/articles/offline-cookbook][off-cookbook] (`Cache only`, `Network only`, `Cache, falling back to network`, `Cache and network race`, `Network falling back to cache`, `Cache then network`, `Generic fallback`, `Service Worker side templating`), maps each recipe to its assertion shape, layers the Workbox `offlineFallback()` recipe per [developer.chrome.com/docs/workbox/modules/workbox-recipes][wb-recipes], and pins the offline storage strategy (Cache Storage vs IndexedDB vs Storage Manager `persist()`/`estimate()`) per [web.dev/learn/pwa/offline-data][off-data]. Output: a Playwright spec file with one test per route's chosen recipe + a coverage matrix mapping recipes to URL patterns. Use when a route's SW caching behavior is being chosen or changed, or when a \"doesn't work offline\" report needs the failing route's recipe localized."
metadata:
keywords: "offline-fallback, offline-cookbook, workbox-recipes, cache-storage, storage-manager"
version: "1.2.7"
---
# offline-fallback-tests
## Overview
Offline behavior fragments into eight named recipes per Jake
Archibald's offline cookbook [off-cookbook] - and most PWAs use
three or four of them across different routes. A test suite that
asserts "the site works offline" misses the per-route recipe
contract: a route on `Cache only` must serve from cache even when
network is fine; a route on `Network falling back to cache` must
*prefer* network when both are present.
This skill emits the per-route test suite. The output is a
Playwright spec file plus a coverage YAML that maps each URL
pattern to its recipe and its assertion. The suite is distinct
from the strategy *authoring* covered by `workbox-tests`
(references/cache-strategy-design.md); that side authors the
strategy, this builder generates the verification.
[off-cookbook]: https://web.dev/articles/offline-cookbook
[off-data]: https://web.dev/learn/pwa/offline-data
[wb-recipes]: https://developer.chrome.com/docs/workbox/modules/workbox-recipes
Composes with:
- `workbox-tests` - when the SW uses
Workbox's `offlineFallback()` recipe, the workbox-tests spec
covers the recipe's runtime; this builder covers the per-route
decision and the page-side assertion.
- `service-worker-lifecycle-tests` - every recipe assumes an active SW; the lifecycle spec is the
prerequisite for this one.
- `add-to-homescreen-flow-tests` (references/install-flow-reference.md) - install-gate Stage 1's service-worker prerequisite cell is the same SW
this builder tests offline behavior of.
## When to use
- New PWA - author the offline-fallback test plan before any route
ships SW caching.
- "Site doesn't work offline" bug report - the recipe matrix
localizes whether the recipe is wrong or just missing for that
route.
- Migrating from hand-rolled `caches.match` / `event.respondWith`
to Workbox `offlineFallback()` - assert that the recipe-named
behavior matches the hand-rolled one.
- Adding a new offline-capable feature (e.g. saved articles, draft
form data) - pick a recipe per the matrix and emit the test.
## Workflow
### Step 1 - Inventory routes and pick a recipe per route
For each URL pattern the SW intercepts, decide which of the eight
named recipes per [off-cookbook] applies. The cookbook recipes
verbatim:
| Recipe (per [off-cookbook]) | When to use (quoted) |
|---|---|
| **Cache only** | "Use for static assets you've cached during installation that your site depends on." |
| **Network only** | "Best for requests without offline equivalents, like analytics or non-GET operations." |
| **Cache, falling back to network** | "Ideal for building offline-first apps where cached content serves as the default." |
| **Cache and network race** | "Useful when disk access is slow and network speed might win the competition for small assets." |
| **Network falling back to cache** | "Good for frequently updating resources, though slow connections create user frustration." |
| **Cache then network** | "Perfect for content that changes often; displays cached data immediately, updates when fresh data arrives." |
| **Generic fallback** | "Provides a default response when both cache and network requests fail for secondary content." |
| **Service worker-side templating** | "Combines cached templates with JSON data to render pages the service worker controls." |
Workbox layers a named composite recipe on top per [wb-recipes]:
- `offlineFallback()` - "serve a web page, image, or font if
there's a routing error" when users are offline, defaulting to
`offline.html`.
Capture decisions in a YAML manifest:
```yaml
# tests/offline-recipe-matrix.yaml
routes:
- pattern: /_next/static/**
recipe: Cache only
reason: Hashed filenames, immutable
- pattern: /
recipe: Network falling back to cache
reason: HTML shell - fresh while online, stale offline
- pattern: /api/feed
recipe: Cache then network
reason: List view; show fast, update behind
- pattern: /api/user/me
recipe: Network only
reason: PII; never cache
- pattern: /img/**
recipe: Cache, falling back to network
reason: Bandwidth save; image lifetime ≥ cache TTL
- pattern: /*
recipe: Generic fallback
reason: Catch-all 404; offline.html
```
### Step 2 - Emit the per-recipe Playwright test
For each recipe row in Step 1's matrix, emit the matching test - the assertion
shape must distinguish "served from cache" vs "served from network." The two
poles (cache-always vs network-always) are inline; the rest live in the
reference.
#### Cache only
Serves from cache even with network reachable AND with network blocked:
```ts
test('Cache only: /_next/static/x.css serves from cache regardless of network', async ({ page, context }) => {
await page.goto('https://localhost:3000/');
await page.waitForLoadState('networkidle');
// Block network for the static path
await context.route('**/_next/static/**', route => route.abort('failed'));
const res = await page.evaluate(() =>
fetch('/_next/static/x.css').then(r => r.status).catch(() => 0)
);
expect(res).toBe(200);
});
```
#### Network only
```ts
test('Network only: /api/user/me fails when offline (never cached)', async ({ page, context }) => {
await page.goto('https://localhost:3000/');
await context.setOffline(true);
const res = await page.evaluate(() =>
fetch('/api/user/me').then(r => r.status).catch(() => 0)
);
expect(res).toBe(0); // network error; not served from cache
});
```
The remaining six recipe templates - Cache falling back to network, Cache and
network race, Network falling back to cache, Cache then network, Generic
fallback, and SW-side templating - are in
[references/recipes.md](references/recipes.md), each with its assertion-shape
note.
### Step 3 - Test the underlying storage choice
Per [off-data], offline data needs the right storage:
| Storage | Per [off-data] | Test posture |
|---|---|---|
| **Cache Storage API** | "Designed for network resources accessed via URL (HTML, CSS, JavaScript, images, videos, audio)" | Assert `caches.has(name)` + `caches.open(name).keys()` returns expected URLs |
| **IndexedDB** | "Use IndexedDB to store structured data" - "data that needs to be searchable or combinable in a NoSQL-like manner" | Assert IDB schema + key existence via `indexedDB.open()` |
| **Storage Manager** | `navigator.storage.estimate()` returns `{ quota, usage }`; `navigator.storage.persist()` requests durable storage | Assert `persisted()` returns true post-request |
Test the Storage Manager `persist()` request:
```ts
test('Storage Manager persist() succeeds for installed PWA', async ({ page }) => {
await page.goto('https://localhost:3000/');
const result = await page.evaluate(async () => {
const persisted = await navigator.storage.persist();
const isPersisted = await navigator.storage.persisted();
return { persisted, isPersisted };
});
expect(result.isPersisted).toBe(true);
});
```
Per [off-data]: "Chrome permits origins to use up to 60% of total
disk space." Tests that assume small caches mask quota-pressure
bugs; assert the application stays well below the estimate:
```ts
test('cache usage stays under 50MB', async ({ page }) => {
await page.goto('https://localhost:3000/');
await page.waitForLoadState('networkidle');
const est = await page.evaluate(async () => navigator.storage.estimate());
expect(est.usage!).toBeLessThan(50 * 1024 * 1024);
});
```
### Step 4 - Test the offline-fallback page itself
Per [wb-recipes], `offlineFallback()` defaults to `offline.html`.
Assert the file is precached + the response shape:
```ts
test('offline.html is precached and well-formed', async ({ page, context }) => {
await page.goto('https://localhost:3000/');
await page.waitForLoadState('networkidle');
let [sw] = context.serviceWorkers();
if (!sw) sw = await context.waitForEvent('serviceworker');
const offlinePagePresent = await sw.evaluate(async () => {
for (const name of await caches.keys()) {
const c = await caches.open(name);
const found = await c.match('/offline.html') || await c.match('/_offline');
if (found) return found.status;
}
return null;
});
expect(offlinePagePresent).toBe(200);
});
```
If the project overrides the default `pageFallback` option, swap
the assertion target.
### Step 5 - Test the offline → online recovery
A subtle class of bugs: a route correctly serves from cache offline,
but doesn't refresh when network returns. Test the transition:
```ts
test('cache then network: recovers fresh data when online returns', async ({ page, context }) => {
await page.goto('https://localhost:3000/feed');
await context.setOffline(true);
await page.reload();
// Stale cache served
await context.setOffline(false);
// Trigger refresh
await page.evaluate(() => fetch('/api/feed').then(r => r.json()));
await page.waitForTimeout(500);
// Assert no "offline" banner lingering
await expect(page.locator('[data-testid="offline-banner"]')).not.toBeVisible();
});
```
### Step 6 - Emit the coverage matrix and CI gate
Write `tests/offline-coverage.yaml` mapping each route from
Step 1 to its test name and the source cookbook recipe:
```yaml
matrix:
- route: /_next/static/**
recipe: Cache only
spec: offline-fallback.spec.ts > 'Cache only: /_next/static/*'
source: off-cookbook "Cache only"
- route: /
recipe: Network falling back to cache
spec: offline-fallback.spec.ts > 'Network falling back to cache'
source: off-cookbook "Network falling back to cache"
- route: /api/feed
recipe: Cache then network
spec: offline-fallback.spec.ts > 'Cache then network: /api/feed'
source: off-cookbook "Cache then network"
- route: /api/user/me
recipe: Network only
spec: offline-fallback.spec.ts > 'Network only: /api/user/me'
source: off-cookbook "Network only"
- route: /img/**
recipe: Cache, falling back to network
spec: offline-fallback.spec.ts > 'Cache, falling back to network: /img/*'
source: off-cookbook "Cache, falling back to network"
- route: /*
recipe: Generic fallback
spec: offline-fallback.spec.ts > 'Generic fallback'
source: off-cookbook "Generic fallback"; wb-recipes offlineFallback()
storage:
- check: cache-usage-under-budget
source: off-data Storage Manager estimate()
- check: persisted-storage-granted
source: off-data Storage Manager persist()
```
CI gates on every row having a passing spec.
## Worked example: a 4-route news PWA
Applying Step 1's matrix to a news PWA - static -> Cache only, `/` -> Network
falling back to cache, `/api/articles` -> Cache then network, `/api/user/me` ->
Network only, `/*` -> Generic fallback - emits a 5-cell Playwright spec that
runs in ~15 seconds on Chromium and catches the four most common offline
regressions:
1. Static cache miss on stale deploy.
2. HTML shell stuck stale when network returns.
3. Article list never refreshes when going online.
4. PII endpoint accidentally cached.
## Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| One "site works offline" smoke test | Per-route recipe regressions invisible | One spec per recipe row per [off-cookbook] (Step 2) |
| Test offline by killing the dev server | SW caches still serve from network until `setOffline(true)` is called | Always `context.setOffline(true)` (every cell) |
| Skip the offline → online recovery test | Stale data lingers after network returns; users see "offline" banner online | Step 5 |
| Pin `caches.match('/offline.html')` to a hard URL | Workbox `pageFallback` option overrides; tests false-fail on custom configs | Match by suffix (Step 4) |
| Test only Chromium | Firefox cache behavior + quota differ | Run cross-browser; Firefox `storage.persist()` UX differs |
| Hand-build storage assertions instead of `navigator.storage.estimate()` | Misses quota-pressure | Step 3 uses the API |
| Assume cached HTML stays fresh forever | TTL plugin (or its absence) gates this; per [wb-recipes] `imageCache()` defaults to 30 days | Assert TTL via `imageCache`-style entry expiration in `workbox-tests` |
| Mix recipes without documenting per route | New routes inherit wrong default | The matrix YAML (Step 1) is the source of truth |
## Limitations
- **The "Cache and network race" recipe** is timing-sensitive;
Step 2's < 100ms threshold is a heuristic for "cache won" - slow
test machines or instrumented Playwright may report higher
values. Tighten / loosen per the project's CI host.
- **`SW-side templating`** is rare in modern PWAs; the Step 2 test
for it assumes the project actually uses the pattern. Skip if
not.
- **Quota-pressure tests are fragile** - a 50 MB ceiling per the
Step 3 test is project-specific; per [off-data] the browser
permits "up to 60% of total disk space" which varies by device.
- **`navigator.storage.persist()`** may prompt the user on some
browsers; in headless CI the prompt auto-dismisses (or
auto-grants) inconsistently. Use the `permissions:
['persistent-storage']` Playwright context option to grant
upfront.
- **`offline.html` precache** depends on the SW's
`precacheAndRoute(self.__WB_MANIFEST)` including the offline
page; `workbox-tests` Step 3
asserts the manifest contents, which is the upstream gate.
- **No IndexedDB-specific recipe** in [off-cookbook]; this builder
documents IDB usage in the storage matrix (Step 3) but does not
generate per-store test cells. Pair with a dedicated IDB test
skill for full coverage.
## References
- web.dev - Offline cookbook (the eight named recipes; verbatim
use-case statements per recipe) - [off-cookbook].
- web.dev - Learn PWA: Offline data (Cache Storage vs IndexedDB
vs Storage Manager; quota note "up to 60% of total disk space") - [off-data].
- Chrome - Workbox recipes (`offlineFallback()` recipe defaults to
`offline.html`) - [wb-recipes].
- Composes:
`workbox-tests`,
`service-worker-lifecycle-tests`,
`add-to-homescreen-flow-tests`.
- Differentiation: the cache-strategy design reference in
`workbox-tests` (references/cache-strategy-design.md) authors the
strategy; this builder generates the verification
suite. Both consume the cookbook recipe vocabulary; the
authoring side writes the SW code, this side writes the spec
that locks it.
- Sibling builders:
`add-to-homescreen-flow-tests`,
`service-worker-lifecycle-tests`.
Files in this package (3)
- SKILL.md 15 KB
- .tessl-plugin/plugin.json 1 KB
- references/recipes.md 4 KB
Versions
The database has no other skills named offline-fallback-tests.
Database snapshot: 13.11.2026 · package version 4cb79b0667b4 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100workbox-tests
Test Workbox-built service workers - pin behavior of the named recipes (`pageCache`, `staticResourceCache`, `imageCache`, `googleFontsCache`, `offlineFallback`, `warmStrategyCache`) per [developer.chrome.com/docs/workbox/modules/workbox-recipes][wb-recipes]; validate… - 100pwa
Progressive Web App development. Service workers, Web App Manifest, offline-first strategies, caching with Workbox, push notifications, and installability. USE WHEN: user mentions "PWA", "Progressive Web App", "service worker", "offline-first", "Web App Manifest", "Workbox",… - 100pwa-offline-first
Use when building offline-first Progressive Web Apps — Service Worker lifecycle, Workbox caching strategies, IndexedDB via Dexie.js, Background Sync for queued writes, Web Push notifications, Lighthouse gates, and Next.js PWA integration. Default for apps that must work on… - 100progressive-web-app
Build Progressive Web Apps (PWAs) with offline support, installability, and caching strategies. Trigger whenever the user mentions PWA, service workers, web app manifests, Workbox, 'add to home screen', or wants their web app to work offline, feel native, or be installable. - 100progressive-web-app
Build Progressive Web Apps (PWAs) with offline support, installability, and caching strategies. Trigger whenever the user mentions PWA, service workers, web app manifests, Workbox, 'add to home screen', or wants their web app to work offline, feel native, or be installable. - 100progressive-web-app
Build Progressive Web Apps (PWAs) with offline support, installability, and caching strategies. Trigger whenever the user mentions PWA, service workers, web app manifests, Workbox, 'add to home screen', or wants their web app to work offline, feel native, or be installable.