pwa-audit

What this skill does

# PWA Audit

Perform a comprehensive Progressive Web App readiness assessment. Validates
the web app manifest, inspects the service worker lifecycle and scope, tests
offline behavior by emulating network disconnection, and checks installability
criteria against the PWA checklist.

## When to Use

- Before submitting an app to app stores via PWA wrappers (TWA, PWABuilder).
- Verifying service worker registration and cache strategy after deployment.
- Diagnosing "Add to Home Screen" prompt not appearing.
- Checking offline fallback behavior after a service worker update.
- Auditing push notification readiness.

## Prerequisites

- **Playwright MCP server** connected and responding (all `mcp__playwright__browser_*` tools available).
- **Chromium-based browser** required for CDP service worker inspection and network emulation.
- Target page must be served over HTTPS (or localhost for development).

## Workflow

### Step 1 -- Navigate to the Target Page

```
browser_navigate({ url: "<target_url>" })
```

Wait for the page to fully load and the service worker to register:

```
browser_wait_for({ time: 3 })
```

### Step 2 -- Check HTTPS Enforcement

Verify the page is served over HTTPS (required for service workers and PWA installability).

```javascript
browser_evaluate({
  function: `() => {
    const protocol = window.location.protocol;
    const isLocalhost = window.location.hostname === 'localhost'
      || window.location.hostname === '127.0.0.1'
      || window.location.hostname === '[::1]';
    const isSecure = protocol === 'https:' || isLocalhost;

    return {
      protocol,
      hostname: window.location.hostname,
      isLocalhost,
      isSecureContext: window.isSecureContext,
      isHTTPS: protocol === 'https:',
      passesRequirement: isSecure,
      issue: !isSecure
        ? 'Page is not served over HTTPS. Service workers and PWA features require a secure context.'
        : null
    };
  }`
})
```

### Step 3 -- Validate the Web App Manifest

Fetch and validate the manifest linked in the page head.

```javascript
browser_evaluate({
  function: `() => {
    const link = document.querySelector('link[rel="manifest"]');
    if (!link) {
      return { found: false, href: null, issues: ['No <link rel="manifest"> found in document head'] };
    }
    return { found: true, href: link.href };
  }`
})
```

If a manifest link is found, fetch and validate its contents using Bash:

```bash
curl -sL "<manifest_url>" | python3 -c "
import json, sys
try:
    m = json.load(sys.stdin)
except:
    print(json.dumps({'valid_json': False, 'error': 'Failed to parse manifest as JSON'}))
    sys.exit(0)

required = ['name', 'short_name', 'start_url', 'display', 'icons']
recommended = ['background_color', 'theme_color', 'description', 'scope', 'lang', 'orientation']
issues = []

for field in required:
    if field not in m:
        issues.append(f'Missing required field: {field}')

for field in recommended:
    if field not in m:
        issues.append(f'Missing recommended field: {field}')

# Validate display mode
valid_display = ['fullscreen', 'standalone', 'minimal-ui', 'browser']
if m.get('display') and m['display'] not in valid_display:
    issues.append(f'Invalid display mode: {m[\"display\"]}. Must be one of: {valid_display}')

if m.get('display') == 'browser':
    issues.append('display: browser does not meet installability criteria. Use standalone, fullscreen, or minimal-ui.')

# Validate icons
icons = m.get('icons', [])
has_192 = any(i.get('sizes') == '192x192' for i in icons)
has_512 = any(i.get('sizes') == '512x512' for i in icons)
has_maskable = any('maskable' in (i.get('purpose') or '') for i in icons)
has_svg = any((i.get('type') or '').endswith('svg') or (i.get('src') or '').endswith('.svg') for i in icons)

if not has_192:
    issues.append('Missing 192x192 icon (required for Android install)')
if not has_512:
    issues.append('Missing 512x512 icon (required for splash screen)')
if not has_maskable:
    issues.append('No maskable icon defined (recommended for adaptive icon support)')

# Validate start_url
if 'start_url' in m and not m['start_url']:
    issues.append('start_url is empty')

result = {
    'valid_json': True,
    'name': m.get('name'),
    'short_name': m.get('short_name'),
    'start_url': m.get('start_url'),
    'display': m.get('display'),
    'background_color': m.get('background_color'),
    'theme_color': m.get('theme_color'),
    'scope': m.get('scope'),
    'icon_count': len(icons),
    'has_192_icon': has_192,
    'has_512_icon': has_512,
    'has_maskable_icon': has_maskable,
    'has_svg_icon': has_svg,
    'issues': issues
}
print(json.dumps(result, indent=2))
"
```

### Step 4 -- Inspect Service Worker Status and Scope

Check service worker registration, state, and scope.

```javascript
browser_evaluate({
  function: `() => {
    if (!('serviceWorker' in navigator)) {
      return { supported: false, issues: ['Service Worker API not available in this browser'] };
    }

    return navigator.serviceWorker.getRegistration().then(reg => {
      if (!reg) {
        return {
          supported: true,
          registered: false,
          issues: ['No service worker registered for this scope']
        };
      }

      const sw = reg.active || reg.waiting || reg.installing;
      return {
        supported: true,
        registered: true,
        scope: reg.scope,
        scriptURL: sw ? sw.scriptURL : null,
        state: sw ? sw.state : null,
        hasActive: !!reg.active,
        hasWaiting: !!reg.waiting,
        hasInstalling: !!reg.installing,
        updateViaCache: reg.updateViaCache,
        issues: []
      };
    }).catch(err => ({
      supported: true,
      registered: false,
      error: err.message,
      issues: ['Service worker registration check failed: ' + err.message]
    }));
  }`
})
```

### Step 5 -- Deep Service Worker Inspection via CDP

Use CDP to get detailed service worker information including cache names
and script contents.

```javascript
browser_run_code({
  code: `async (page) => {
    const client = await page.context().newCDPSession(page);

    await client.send('ServiceWorker.enable');

    // Give the service worker time to report
    await page.waitForTimeout(2000);

    // Get all service worker versions
    const { versions } = await client.send('ServiceWorker.inspectWorker', {}).catch(() => ({ versions: [] }));

    // Get storage usage to understand cache sizes
    const { usage, quota } = await client.send('Storage.getUsageAndQuota', {
      origin: new URL(page.url()).origin
    }).catch(() => ({ usage: 0, quota: 0 }));

    // Get cache storage names
    const { caches } = await client.send('CacheStorage.requestCacheNames', {
      securityOrigin: new URL(page.url()).origin
    }).catch(() => ({ caches: [] }));

    await client.send('ServiceWorker.disable');

    return {
      cacheNames: caches.map(c => c.cacheName),
      cacheCount: caches.length,
      storageUsageBytes: usage,
      storageQuotaBytes: quota,
      storageUsageMB: Math.round(usage / 1024 / 1024 * 100) / 100,
      storageQuotaMB: Math.round(quota / 1024 / 1024 * 100) / 100
    };
  }`
})
```

### Step 6 -- Test Offline Capability

Emulate offline network conditions via CDP, then attempt to reload the page
and capture the result.

```javascript
browser_run_code({
  code: `async (page) => {
    const client = await page.context().newCDPSession(page);

    // Go offline
    await client.send('Network.enable');
    await client.send('Network.emulateNetworkConditions', {
      offline: true,
      latency: 0,
      downloadThroughput: 0,
      uploadThroughput: 0
    });

    // Attempt to reload
    let offlineResult;
    try {
      await page.reload({ timeout: 10000, waitUntil: 'domcontentloaded' });

      // Check what loaded
      const title = await page.title();
      const bodyText = await page.evaluate(() => document.body ? document.body.innerText.substring(0, 500) : '');
      const hasConte