pwa-check.yml Configuration Reference

This document describes the configuration used by:

pwa-check audit https://example.com

For pipeline setup and authentication, see Integrating PWA Today Audits into CI/CD. For direct HTTP integration, see the Runtime Audit API Reference. For provider-specific deployment scripts, see Service Worker Deployment Testing.

Configuration file discovery

The CLI looks in its current working directory for the first available file in this order:

1. pwa-check.yml
2. pwa-check.yaml
3. pwa-check.json

Select another file with:

pwa-check audit --config config/production-audit.yml https://example.com

Paths in reports and the service worker deployment command are resolved relative to the directory in which the CLI runs.

Top-level structure

version: 1

audit:
  profile: standard
  applicationId: example.com
  allowedOrigins: []
  include: []
  exclude: []
  options: {}

qualityGate:
  minimumScore: 90
  failOn:
    - critical
    - high
  failOnWarnings: true

reports:
  json: reports/pwa-audit.json
  junit: reports/pwa-audit.xml

If no configuration file exists, the CLI uses version 1, the standard profile, the API’s default quality gate, and no report files.

version

The only supported value is:

version: 1

The CLI rejects files without version: 1.

audit

audit.profile

Selects the initial set of checks:

audit:
  profile: standard

Supported profiles:

The default profile is standard.

The hosted Runtime Audit API also applies the customer entitlement. The complimentary trial and Developer plan accept the standard profile with one or more Standard checks selected. Team and Business dashboard configurations may select any check from the Full runtime suite except service-worker-deployment; complete release audits use the exact full profile with service-worker-deployment included. Other profiles remain useful for local checks, but the API returns a structured entitlement error if they do not match the active plan.

Some selected checks require options. If their required options are missing, they return not-applicable. The exception is service-worker-deployment: when explicitly selected, its missing local command is a CLI configuration error.

audit.applicationId

Identifies the Application that owns the audit history:

audit:
  applicationId: example.com

If omitted, the audited hostname is used. An Application ID must:

• Be the verified Application hostname in the customer console.
• Match the hostname of the audited URL.
• Contain only letters, numbers, dots, or dashes.

audit.allowedOrigins

By default, the audit browser can load only the audited PWA origin. Add an origin here only when the PWA needs an essential script, stylesheet, font, image, or API from another host:

audit:
  allowedOrigins:
    - https://cdn.example.com
    - https://api.example.com

Each entry must be a public HTTPS origin without a path or query string. The audit validates and pins each origin before the browser starts, so an entry cannot resolve to a private network address during the audit. Same-origin PWAs do not need this setting. You can configure at most 10 additional origins.

audit.include

Adds checks to a profile:

audit:
  profile: quick
  include:
    - offline

For custom, include defines the entire check set and must contain at least one check:

audit:
  profile: custom
  include:
    - manifest
    - offline

Duplicate check IDs are removed.

audit.exclude

Removes checks after the profile and include list have been combined:

audit:
  profile: full
  exclude:
    - push-notifications

If a check appears in both include and exclude, it is excluded.

Stable check IDs

Unknown check IDs are rejected.

audit.options

Options are grouped by stable check ID:

audit:
  options:
    offline-navigation:
      series:
        - [/, /products, /checkout]

Do not put credentials, authorization headers, cookies, passwords, API keys, private keys, client secrets, or tokens in check options. Sensitive option names are rejected by the API, and the audit configuration is stored with the audit record.

Common browser timeout

Most checks support:

audit:
  options:
    manifest:
      timeout: 20000

timeout is a navigation timeout in milliseconds. The default is 15000. Increasing it can help applications that take longer to reach the browser’s network-idle state.

manifest

audit:
  options:
    manifest:
      timeout: 20000

The check:

• Loads the page in a browser.
• Resolves the manifest from the rendered document.
• Runs the static pwa-check manifest rules.
• Loads icons and screenshots to verify their actual dimensions.

offline

audit:
  options:
    offline:
      offlineUrls:
        - /
        - /products
      expectedSelectors:
        - main
        - h1
      requiredText:
        - Example Store
      minBodyTextLength: 20
      minHtmlLength: 1000
      timeout: 20000

This check loads each URL online, confirms that a service worker controls it, reloads it offline, and compares the online and offline documents.

offline-navigation

audit:
  options:
    offline-navigation:
      series:
        - - /
          - /products
          - /checkout
        - - /
          - /account
      expectedSelectors:
        - main
      requiredText:
        - Example Store
      timeout: 20000

series is required. Each nested array is one navigation sequence. The check visits every URL in the sequence online and then repeats the sequence offline. Relative URLs resolve against the audited URL.

Use multiple sequences to test independent navigation paths:

series:
  - [/, /products, /products/featured]
  - [/, /help, /contact]

cache

audit:
  options:
    cache:
      routes:
        - url: /
          readySelector: '#home-title'
        - url: /audit/
          readySelector: '#audit-title'
      privateResponseAllowlist:
        - /offline-profile
      growthTolerance: 0
      cacheSettleTimeout: 10000
      cacheQuietPeriod: 1000
      timeout: 20000

routes is required. The audit opens every route twice online, waiting for its readySelector to contain text each time. It verifies that Cache Storage stops growing after the second pass, rejects cached private or no-store responses, and then opens every configured route in a fresh offline tab.

Use a route-specific readySelector that represents rendered page content, not an empty application shell. Relative URLs resolve against the audited URL.

service-worker-first-installation

audit:
  options:
    service-worker-first-installation:
      timeout: 20000

The check starts with a clean browser profile, waits up to 10 seconds for the first service worker to become ready, reloads the page, and verifies that the worker controls it.

The 10-second serviceWorker.ready limit is fixed separately from the navigation timeout.

service-worker-handlers

audit:
  options:
    service-worker-handlers:
      timeout: 20000

The check resolves the active service worker at runtime, loads its imported scripts, and checks the required handlers:

• install
• activate
• fetch
• push
• notificationclick

It also checks lifecycle behavior such as waitUntil, self.skipWaiting(), and self.clients.claim().

service-worker-update

audit:
  options:
    service-worker-update:
      timeout: 20000

The check installs the current service worker, requests a cache-busted version of its script, and verifies that the browser detects and installs the simulated update.

service-worker-deployment

This check is never selected automatically, including by the full profile. It must appear in include:

audit:
  profile: full
  include:
    - service-worker-deployment

  options:
    service-worker-deployment:
      deploymentTimeout: 900000
      commandTimeout: 900000
      command:
        - ./scripts/deploy-and-wait.sh
      requiredCachedUrls:
        - /
        - /offline
      contentCheckUrls:
        - /
        - /app.js

The CLI first asks the hosted deployment check to capture a baseline. It then runs command, waits for it to finish, signals deployment completion, and waits for the service worker verification result.

See Service Worker Deployment Testing for complete Vercel, Netlify, and AWS Amplify Hosting scripts.

Local-only options:

command is executed without a shell. This is correct:

command:
  - ./scripts/deploy-and-wait.sh

Arguments are separate array entries:

command:
  - ./scripts/deploy-and-wait.sh
  - production

Shell syntax is not interpreted inside an entry. Put pipes, redirects, and multiple shell commands inside the script.

Hosted deployment options:

All timeout values are milliseconds. The deployment must produce a changed service worker file; otherwise the update cannot be verified.

Do not configure testId manually. The CLI creates the deployment test and replaces the local deployment options with the resulting testId when it creates the aggregate runtime audit.

before-install-prompt

audit:
  options:
    before-install-prompt:
      timeout: 20000

The check observes the beforeinstallprompt event while loading, interacting with, and reloading the page.

offline-request-retry

audit:
  options:
    offline-request-retry:
      requests:
        - requestUrl: https://example.com/api/messages
          method: POST
          requestBody:
            message: Audit test request
      retryTimeout: 8000
      offlineSettleTime: 1000
      timeout: 20000

The check takes the browser offline, sends every configured request from the page, restores connectivity, and observes whether the service worker retries each request. It passes only when all configured requests are observed offline and retried online.

Use a dedicated test endpoint and test data. The check can cause a real request to reach the configured endpoint.

push-notifications

The check supports synthetic and real delivery.

Synthetic delivery does not contact an application push server:

audit:
  options:
    push-notifications:
      payload:
        title: PWA audit
        message: Synthetic test notification

Real delivery creates a new browser push subscription and calls a customer endpoint:

audit:
  options:
    push-notifications:
      applicationServerKey: YOUR_PUBLIC_VAPID_KEY
      triggerUrl: https://example.com/api/send-audit-push
      payload:
        title: PWA audit
        message: Real test notification
        pushSubscription: $subscription
      observationTimeout: 8000
      timeout: 20000

If the application stores subscriptions separately, configure subscriptionUrl:

push-notifications:
  applicationServerKey: YOUR_PUBLIC_VAPID_KEY
  subscriptionUrl: https://example.com/api/push-subscriptions
  triggerUrl: https://example.com/api/send-audit-push
  payload:
    title: PWA audit
    message: Real test notification

For real delivery, every value equal to the exact string $subscription inside payload is replaced recursively with the generated subscription. If there is no placeholder, triggerUrl receives only the configured payload.

The audit request sends the audited application’s origin in the HTTP Origin header when calling subscriptionUrl and triggerUrl. These endpoints must accept that origin.

The check creates a fresh subscription for the run and unsubscribes it during cleanup.

qualityGate

qualityGate:
  minimumScore: 90
  failOn:
    - critical
    - high

qualityGate.minimumScore

A number from 0 to 100. The default is 90.

The score is:

passed checks / scored checks × 100

Statuses included in the score:

• passed
• failed
• warning

not-applicable, skipped, and error are not scored.

qualityGate.failOn

An array containing any of:

• critical
• high
• medium
• low

The default is:

failOn:
  - critical
  - high

The quality gate fails when either:

• The score is below minimumScore.
• A failed check has a severity listed in failOn.

Warnings do not trigger failOn, although they lower the score because they are scored but not counted as passed.

qualityGate.failOnWarnings

A boolean that defaults to false. When true, any warning causes the quality gate to fail.

Infrastructure errors produce an audit status of failed or partially-completed. The CLI returns its service-error exit code independently of the quality gate.

reports

reports:
  json: reports/pwa-audit.json
  junit: reports/pwa-audit.xml

Directories are created automatically. Paths are relative to the CLI working directory unless absolute paths are used.

Report files are optional and are written after the audit reaches a terminal state. Configure the CI/CD platform to retain them as artifacts.

CLI overrides

These command-line flags override configuration values:

Examples:

pwa-check audit \
  --profile quick \
  --minimum-score 95 \
  https://example.com

pwa-check audit \
  --include offline,service-worker-update \
  https://example.com

The CLI flags replace the corresponding configured arrays when at least one value is supplied; they do not append to them.

Authenticated audits

For a protected PWA, provide a bearer token or cookies only at runtime. Do not put credentials in pwa-check.yml.

export PWA_AUDIT_AUTH='{"headers":{"authorization":"Bearer token"}}'
pwa-check audit --auth-env PWA_AUDIT_AUTH https://app.example.com

The service encrypts one-time CLI credentials, uses them only for the exact target origin, and expires them after the audit. Cross-origin redirects never receive them. A local --auth-file must not be readable by group or others.

Runtime-only CLI settings do not have pwa-check.yml fields:

Complete annotated example

version: 1

audit:
  applicationId: shop.example.com
  profile: full

  include:
    - service-worker-deployment

  exclude: []

  options:
    manifest:
      timeout: 20000

    offline:
      offlineUrls:
        - /
        - /products
      expectedSelectors:
        - main
      requiredText:
        - Example Store

    offline-navigation:
      series:
        - [/, /products, /checkout]
        - [/, /account]
      expectedSelectors:
        - main

    cache:
      routes:
        - url: /
          readySelector: '#home-title'
        - url: /products
          readySelector: '#products-title'

    service-worker-first-installation:
      timeout: 20000

    service-worker-handlers:
      timeout: 20000

    service-worker-update:
      timeout: 20000

    service-worker-deployment:
      deploymentTimeout: 900000
      commandTimeout: 900000
      command:
        - ./scripts/deploy-and-wait.sh
      requiredCachedUrls:
        - /
        - /offline
      contentCheckUrls:
        - /
        - /app.js

    before-install-prompt:
      timeout: 20000

    offline-request-retry:
      requests:
        - requestUrl: https://example.com/api/audit-messages
          method: POST
          requestBody:
            message: PWA audit retry test

    push-notifications:
      payload:
        title: PWA audit
        message: Synthetic notification

qualityGate:
  minimumScore: 90
  failOn:
    - critical
    - high
  failOnWarnings: true

reports:
  json: reports/pwa-audit.json
  junit: reports/pwa-audit.xml

Remove options and checks that are not relevant to the application. In particular, only enable checks that create external side effects when dedicated test endpoints and data are available.