A Singapore Government Agency Website

Integrate Oobee with Cypress

What this guide covers

The Oobee npm module runs in Node.js, and Cypress tests run in the browser. To connect them, you expose the Oobee instance as Cypress tasks in cypress.config.js, add custom commands that inject Oobee’s scripts into the page, and call the commands from your tests. This guide covers a JavaScript project. For TypeScript, use the example in the Oobee repository.

Prerequisites

  • Node.js 20 or later.
  • A project that runs ES modules: set "type": "module" in package.json, or use .mjs files. The samples use import and top-level await.
  • A Cypress project. Refer to Cypress for setup.
  • The reference for every option: npm API.

Step 1: Install Oobee

Add the module to your project, then build it inside node_modules if dist is missing:

npm install --save-dev @govtechsg/oobee
cd node_modules/@govtechsg/oobee
npm install
npm run build
cd ../../..

Step 2: Create the Oobee instance and tasks

In cypress.config.js, create an Oobee instance and expose it as tasks. Set disableScreenshots to true in pushScanResults, because Oobee cannot share the Cypress browser with Node.js.

import { defineConfig } from "cypress";
import oobeeA11yInit from "@govtechsg/oobee";

const viewportSettings = { width: 1920, height: 1040 };

const oobeeA11y = await oobeeA11yInit({
  entryUrl: "<ENTRY_URL>",
  testLabel: "Demo Cypress Scan",
  name: "<YOUR_NAME>",
  email: "<YOUR_EMAIL>",
  includeScreenshots: false,
  viewportSettings,
  thresholds: { mustFix: 20, goodToFix: 25 },
  scanAboutMetadata: { browser: "Chrome (Desktop)" },
  zip: "oobee-scan-results.zip",
  deviceChosen: "E2E Test Device",
  ruleset: ["enable-wcag-aaa"],
});

export default defineConfig({
  taskTimeout: 120000,
  viewportHeight: viewportSettings.height,
  viewportWidth: viewportSettings.width,
  e2e: {
    setupNodeEvents(on, _config) {
      on("task", {
        getAxeScript() {
          return oobeeA11y.getAxeScript();
        },
        getOobeeA11yScripts() {
          return oobeeA11y.getOobeeFunctions();
        },
        gradeReadability(sentences) {
          return oobeeA11y.gradeReadability(sentences);
        },
        async pushOobeeA11yScanResults({ res, metadata, elementsToClick }) {
          return await oobeeA11y.pushScanResults(res, metadata, elementsToClick, undefined, true);
        },
        finishOobeeA11yTestCase() {
          oobeeA11y.testThresholds();
          return null;
        },
        async terminateOobeeA11y() {
          return await oobeeA11y.terminate();
        },
      });
    },
  },
});

taskTimeout is raised to 120000 ms because scans can take longer than the Cypress default. Add "disable-oobee" to ruleset to turn off Oobee’s custom checks.

Step 3: Add the custom commands

In cypress/support/e2e.js, add three commands. The first injects the axe-core engine and the Oobee functions into the page. The second runs a scan and pushes the results. The third ends the scan.

Cypress.Commands.add("injectOobeeA11yScripts", () => {
  cy.task("getAxeScript").then((script) => {
    cy.window().then((win) => win.eval(script));
  });
  cy.task("getOobeeA11yScripts").then((script) => {
    cy.window().then((win) => win.eval(script));
  });
});

Cypress.Commands.add("runOobeeA11yScan", (items = {}) => {
  cy.window().then(async (win) => {
    const { elementsToScan, elementsToClick, metadata } = items;
    const sentences = win.extractText();

    cy.task("gradeReadability", sentences).then(async (gradingReadabilityFlag) => {
      const res = await win.runA11yScan(elementsToScan, gradingReadabilityFlag);
      cy.task("pushOobeeA11yScanResults", { res, metadata, elementsToClick });
    });
    cy.task("finishOobeeA11yTestCase");
  });
});

Cypress.Commands.add("terminateOobeeA11y", () => {
  cy.task("terminateOobeeA11y");
});

Step 4: Call the commands in a test

Inject the scripts after each page load, run a scan, and terminate at the end. Pass elementsToScan to scan only some elements.

describe("accessibility scan", () => {
  it("scans the page and a revealed section", () => {
    cy.visit("<PAGE_URL>");
    cy.injectOobeeA11yScripts();
    cy.runOobeeA11yScan();

    cy.get("<TOGGLE_SELECTOR>").click();
    cy.runOobeeA11yScan({
      elementsToScan: ["input", "button"],
      metadata: "Clicked button",
    });

    cy.terminateOobeeA11y();
  });
});

Step 5: Run the test

Run the test, then open the report in the results folder in your project’s root folder:

npx cypress run

For the report files, refer to Read and export scan reports.

Include element screenshots

Oobee cannot take screenshots in the Cypress browser, so the example in the Oobee repository takes them with Cypress and copies them into the results folder. To use it, copy cypress.config.js and cypress/support/e2e.js from examples/oobee-cypress-integration-js in the repository, and set includeScreenshots to true. The repository also has a TypeScript example in examples/oobee-cypress-integration-ts.

Constraints and limitations

Constraint Detail
Screenshots pushScanResults must be called with disableScreenshots set to true under Cypress.
Script injection Inject both scripts after every page load.
Cumulative thresholds finishOobeeA11yTestCase totals the counts across the whole run.
Task timeout The default Cypress task timeout can be too short for scans.
One report per instance The instance in cypress.config.js serves the whole run. terminate ends it.
Chat with me!
Bot Launcher