Skip to main content

Start here

Quick start

Add the SDK to the Playwright suite you already have. It’s one line in your config with no test edits, and it has no network client: nothing leaves your machine.

What it needs

node
>=22
@playwright/test
The SDK declares >=1.45.0, but its types only hold for the version it was built against, so match your Playwright to the SDK’s until that is fixed. The app you test can be written in anything.
Your suite
Tests that visit your pages. The SDK scans what they drive and never crawls.
An account
None. Local runs work for as long as you like.

Before you install anything

See what your suite already covers: which routes it visits, which journeys have no coverage, and whether you already run axe, and at what level. It writes nothing, changes nothing and sends nothing anywhere.

Terminal
npx @setsquare/review-cli audit

  1. Install

    Terminal
    npm i -D @setsquare/review-sdk

    One install brings the setsquare command with it, so there’s no second package to add.

  2. Wrap your Playwright config

    Terminal
    npx setsquare init

    setsquare init adds two lines to your Playwright config and tells you what it found. With more than one config it asks which, rather than guessing.

    playwright.config.ts
    import { withSetsquare } from '@setsquare/review-sdk';

export default withSetsquare(defineConfig({/* your config, untouched */}));

    Then add .setsquare/ to your .gitignore.

  3. Run your suite

    Terminal
    npx playwright test    Setsquare — accessibility evidence   PLAYWRIGHT       36  passed   ACCESSIBILITY — WCAG 2.2 AA        6  surfaces scanned in 2 themes        0  rule–surface pairs failing — 0 rules across 0 surfaces      180  needing a judgement — a person decides   36,938  checks passed, across 48 distinct rules   CONFORMANCE — WCAG 2.2           Includes every 2.0 and 2.1 criterion. Automated checks cover only part of WCAG, so           this is evidence about what was scanned, never a conformance claim.            Level A    no failures detected in what was scanned           Level AA   no failures detected in what was scanned           Level AAA not assessed — AAA is opt-in; run with wcag: 'AAA' to include it.            No Level AA violations detected across 6 surfaces (automated checks only).       23  criteria: every automated rule passed — evidence, not conformance        5  criteria automation could not decide — see the two sections above       23  criteria: checks ran, nothing to check on these pages (no such content)        2  criteria no automated rule can decide — what you still owe an auditor        1  criteria compare pages against each other — fewer than two pages carried the evidence        1  criteria not automatically checked in this run            Which rules, on which surfaces, with the selectors and the criteria grid: in the           report below. SETSQUARE_VERBOSE=1 prints all of it here instead, for a CI log with no           report to open.

    Every settled page in every test is scanned against WCAG 2.2 AA. A scan never fails your build: your tests keep their own verdicts, and a scan error warns and carries on. The output above is this documentation’s sister site, www.setsquare.dev, scanned by its own suite.

  4. Read the evidence

    Each run writes a folder, .setsquare/runs/<timestamp>/, and removes the previous run's: local runs keep no history, by design.

    run.json
    The findings, their WCAG criteria, measured contrast ratios, the exact ruleset and timings.
    report.html
    Which rules failed on which surfaces, with their selectors, and the criteria-by-surfaces grid.
    screens.html
    An index of the screenshots Playwright wrote, linked where they lie.
    Terminal
    npx setsquare report --open

  5. Choose a level

    AA is the default, because it’s what conformance means in practice and what EN 301 549 and procurement ask for. AAA is a deliberate commitment, so you opt in to it.

    playwright.config.ts
    export default withSetsquare(defineConfig({ testDir: './e2e' }), {
  wcag: 'AAA', // default 'AA'
});

    Level AAA adds axe’s AAA rules, Setsquare’s AAA checks and a reading grade per page.

  6. Build with Setsquare UI

    The other half: components that meet the level you chose, in your own look. Set the same level on the html element and every target, focus ring and gap follows it.

    Terminal
    pnpm add @setsquare/ui react-aria-components @internationalized/date
    app/layout.tsx
    <html lang="en" data-conformance="aaa">

    Setsquare UI’s README, with every component and its guards, is on npm.

Automated evidence is not conformance

A rule failing is not a page failing, and needs a person is neither a pass nor a failure. WCAG 2.2 coverage lists every criterion no rule can decide, with the reason and what would have to change.

Next