Getting Started

Installation

There's no single install command — surea11y is a core engine plus a family of separately-published bindings, so which package(s) you install depends on how you already run tests or scripts. Pick your stack:

Not sure where to start?

Use Playwright to scan a real web application, or the CLI to check static HTML from a terminal or CI pipeline.

Need	Recommended option	Reason
Analyze a real web application	Playwright	Drives a real browser and an integration modern test suites already use, so results reflect actual layout and rendering.
Analyze static HTML	CLI	No integration to write — a single command against a file, URL, or CI step.
Already use Cypress, Selenium, Puppeteer, or WebdriverIO	The matching binding	Fits directly into the test environment you already have.
Unit or component tests	test-matchers	Direct Jest/Vitest integration against jsdom.
Your own integration, or direct engine access	`@surea11y/core`	Maximum control over execution and results.

A 5-minute example

The CLI is the fastest way to see a real result — no browser setup, no test framework. Scan a minimal page:

<html lang="en">
  <body>
    <main>
      <h1>Welcome</h1>
      <p style="color: #999999; background-color: #ffffff;">This text has low contrast.</p>
      <a href="/details">Click here</a>
    </main>
  </body>
</html>

$ npm install -g @surea11y/cli
$ surea11y scan ./index.html

surea11y scan: file:///path/to/index.html
  pass: 6   fail: 2   cantTell: 3   notApplicable: 114
  occurrences by tier: fail: 2   cantTell: 4
FAIL (2 rule(s)):
  contrast-enhanced  (serious, 1 fail occurrence(s))
    - html > body > main > p
      Element has insufficient color contrast (AAA) of 2.85:1 (foreground: #999999,
      background: #ffffff, font size: 0px, font weight: normal). Expected contrast
      ratio of 7:1 (normal text).
  contrast-minimum  (serious, 1 fail occurrence(s))
    - html > body > main > p
      Element has insufficient color contrast of 2.85:1 (foreground: #999999,
      background: #ffffff, font size: 0px, font weight: normal). Expected contrast
      ratio of 4.5:1 (normal text).
cantTell — needs human review (3 rule(s)): contrast-computable, link-name-quality,
manual-review

One fail the engine is certain about (contrast), a cantTell list for a human to review (is "Click here" a good link name, does that same low-contrast text pass a different check, is there something here needing a manual look), and, among the 114 notApplicable results, target-size-minimum — it can't run without real CSS layout, which a static-HTML scan doesn't have. See Results & Reports for what each field in a full result means.

End-to-end tests, driving a real or headless browser: Cypress, Playwright, Puppeteer, Selenium, or WebdriverIO.
Unit and component tests, against jsdom: test-matchers, for Jest or Vitest.
Static HTML from a terminal or CI pipeline: the CLI.
No test framework or build step: standalone — install @surea11y/core directly, or drop in the browser bundle.

Usage

However you run a scan — jsdom, a real browser, any binding, the CLI — it returns the same native result shape: checksResults (one entry per rule, including every pass/notApplicable — not a "violations only" list) and rulesResults (WCAG-SC rollups). This is not the violations/passes/incomplete/inapplicable shape used by other popular accessibility testing tools — each binding's method names are modeled on common conventions in this space for migration familiarity, but the richer result schema is kept as-is. See Results & Reports for the full schema.