Scan pages and HTML in Node.js

What this guide covers

scanPage and scanHTML scan content from a plain Node.js script, without an Oobee instance, a test framework or the CLI. Both return the results as an object that you can check in your own code. Use scanPage when you control a Playwright page, and scanHTML when you only have an HTML string.

The functions do not write a report folder. To produce a report, use the Oobee instance in Integrate Oobee with Playwright.

Prerequisites

• Node.js 20 or later.
• @govtechsg/oobee installed: npm install --save-dev @govtechsg/oobee.
• For scanPage: Playwright and its Chromium browser, npx playwright install chromium.
• A project that runs ES modules: set "type": "module" in package.json, or use .mjs files.
• Parameter details: npm API.

Step 1: Scan Playwright pages with scanPage

Pass one page or an array of pages. Oobee injects its scripts into each page and runs the scan.

import { chromium } from "playwright";
import { scanPage } from "@govtechsg/oobee";

const browser = await chromium.launch({ headless: false, channel: "chrome" });
const page = await browser.newPage();
await page.goto("<PAGE_URL>");

const results = await scanPage(page, {
  name: "<YOUR_NAME>",
  email: "<YOUR_EMAIL>",
});

console.log(JSON.stringify(results, null, 2));
await browser.close();Copy to clipboardErrorCopied

To scan several pages in one call, pass [page, page2]. To enable AAA rules or turn off Oobee’s own checks, add ruleset: ["enable-wcag-aaa"] or ruleset: ["disable-oobee"] to the config.

Step 2: Scan HTML strings with scanHTML

Pass one HTML string or an array of strings. scanHTML needs no browser.

import { scanHTML } from "@govtechsg/oobee";

const html = `<!DOCTYPE html>
<html lang="en">
<head><title>Test page</title></head>
<body>
  <h1>Accessibility test</h1>
  <button></button>
  <img src="test.jpg" />
</body>
</html>`;

const results = await scanHTML(html, {
  name: "<YOUR_NAME>",
  email: "<YOUR_EMAIL>",
  pageUrl: "<PAGE_LABEL>",
  pageTitle: "<PAGE_TITLE>",
});Copy to clipboardErrorCopied

For an array, Oobee appends -1, -2 and so on to pageUrl, and a number to pageTitle.

Step 3: Read the results

Both functions return the same shape. A single page returns its results directly, and several pages return merged results. Each result has three categories, and each category has a totalItems count and a rules object keyed by rule ID.

const mustFix = results.mustFix.totalItems;
const goodToFix = results.goodToFix.totalItems;

for (const [ruleId, rule] of Object.entries(results.mustFix.rules)) {
  console.log(ruleId, rule.totalItems);
  for (const item of rule.items) {
    console.log(item.html, item.message);
  }
}Copy to clipboardErrorCopied

Each item has html and message, and may have xpath and parentHtml. A rule also has description, helpUrl, conformance, axeImpact, shortDescription, longDescription and stepByStepGuide.

Constraints and limitations

Related content

• npm API — every parameter and default.
• Integrate Oobee with Playwright — produce an HTML report from a Playwright script.
• Scan rules and severity — rule categories.