API reference

withSetsquare()

withSetsquare(config: PlaywrightTestConfig, options?: SetsquareOptions): PlaywrightTestConfig

Wraps your Playwright config and appends one reporter. Projects, testDir, use, webServer and timeouts stay as you wrote them.

import { defineConfig } from '@playwright/test';
import { withSetsquare } from '@setsquare/review-sdk';

export default withSetsquare(defineConfig({ testDir: './e2e' }), {
  wcag: 'AAA', // default 'AA'
  personas: { 'a11y-admin': 'recruiter' },
  themes: { 'dark-suite': 'dark' },
  surfaces: { '/jobs/:id/edit': 'job-editor' },
  mask: ['.candidate-name'],
  settleByRoute: { '/pages/editor': { settleTimeoutMs: 15000 } },
});

Options

setsquare.scan()

setsquare.scan(page: Page, surface: string, options?: ScanOptions): Promise<ScanSummary>

Waits for the page to settle, then scans it under a surface name you choose. Use it for a state your test reaches that the URL doesn’t show: a dialog that’s open, a form showing its errors. An explicit scan always outranks an inferred one for the same context.

import { test } from '@playwright/test';
import { setsquare } from '@setsquare/review-sdk';

test('the editor reports validation errors accessibly', async ({ page }) => {
  await page.goto('/jobs/42/edit');
  await page.getByRole('button', { name: 'Save' }).click();

  await setsquare.scan(page, 'job-editor', { state: 'validation-errors' });
});

ScanOptions

ScanSummary

What the scan found, returned so a test can assert on it. Facts only, and no comparison of any kind: locally there is nothing to compare against.

setsquare.covers()

setsquare.covers(...criteria: string[]): void

Says that this test checks a WCAG 2.2 success criterion. The report lists it as covered by your own test, with the test named beside it, and records it as your claim rather than our finding.

test('no horizontal scrolling at 320px', async ({ page }) => {
  setsquare.covers('1.4.10');

  await page.setViewportSize({ width: 320, height: 800 });
  await page.goto('/pricing');
  expect(await hasHorizontalOverflow(page)).toBe(false);
});

Pointing at a moment

Some criteria are out of reach only because we don’t know something your suite does: when a session expired, or which step comes before a submission completes. Point at that moment and the SDK takes the measurement.

setsquare.acrossReauthentication()

setsquare.acrossReauthentication(page: Page, run: () => Promise<void>): Promise<void>

For 2.2.5 Re-authenticating.

await page.goto('/checkout');
await page.fill('#address', '12 Example Street');

await setsquare.acrossReauthentication(page, async () => {
  await page.context().clearCookies(); // however your app ends a session
  await signBackIn(page);
});

setsquare.acrossSubmission()

setsquare.acrossSubmission(page: Page, options: { consequential?: boolean }, run: () => Promise<void>): Promise<void>

For 3.3.6, and for 3.3.4 when consequential is true.

await setsquare.acrossSubmission(page, { consequential: true }, async () => {
  await page.click('#review-order'); // the step before it completes
});

What each one measures, in the SDK’s own words, is in What your tests cover.

Helpers

Environment variables

For CI and for the script that calls Playwright, where editing the config isn’t the right lever.

The setsquare command

setsquare <command> [options]

Installed with the SDK. audit and doctor need nothing installed and send nothing anywhere, so you can run them first with npx @setsquare/review-cli audit. These tables are the command’s own help.

Commands

Options

What a run writes

Everything lands under outputDir, .setsquare by default.