npm API
Module overview
The @govtechsg/oobee package exposes a JavaScript and TypeScript API for scanning pages from Node.js code. The package entry point is dist/npmIndex.js. Oobee must be imported in a script that runs in Node.js, not in a browser.
| Export | Kind | Purpose |
|---|---|---|
default (also init) |
Function | Create an Oobee instance for framework integrations. Called oobeeA11yInit in the examples. |
scanPage |
Function | Scan one or more Playwright Page objects. The integration guide marks it Beta. |
scanHTML |
Function | Scan one or more HTML strings in a JSDOM environment. Experimental. |
scanCustomFlow |
Function | Run a custom flow scan and get a session handle |
RuleFlags |
Enum | Ruleset values: default, disable-oobee, enable-wcag-aaa |
a11yRuleShortDescriptionMap, a11yRuleLongDescriptionMap, a11yRuleStepByStepGuide |
Objects | Rule text keyed by rule ID |
getOobeeFunctionsScript |
Function | Build the Oobee script to inject into a page |
Install with npm install --save-dev @govtechsg/oobee. For worked examples, refer to Integrate Oobee with Playwright, Integrate Oobee with Cypress and Scan pages and HTML in Node.js.
oobeeA11yInit
Signature: async oobeeA11yInit(options). Returns an Oobee instance. Each instance collects results across the pages you push to it, until you call terminate().
oobeeA11yInit parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
entryUrl |
string |
Yes | None | Initial URL of the scan. Must be a valid URL. |
testLabel |
string |
Yes | None | Label for the test, used in the results folder name and the report. Characters outside letters, digits, _ and - become _, and the label is cut to 64 characters. |
name |
string |
Yes | None | Name, for Oobee data collection |
email |
string |
Yes | None | Email address, for Oobee data collection |
includeScreenshots |
boolean |
No | false |
Include screenshots of affected elements in the report |
viewportSettings |
{ width: number, height: number } |
No | { width: 1000, height: 660 } |
Viewport used for screenshots. The default matches Cypress. |
thresholds |
{ mustFix: number, goodToFix: number } |
No | Both undefined |
Maximum Must Fix and Good to Fix occurrences before testThresholds() throws. An undefined value does not fail tests. |
scanAboutMetadata |
{ browser?: string, viewport?: { width: number, height: number } } |
No | undefined |
Extra information for the Scan About section of the report |
zip |
string |
No | 'oobee-scan-results' |
Name of the results zip file written at the end of the scan |
deviceChosen |
string |
No | undefined |
Name of the device scanned, for example iPhone 13 Pro Max |
strategy |
EnqueueStrategy |
No | EnqueueStrategy.All |
Link-following strategy. Values: all, same-hostname, same-domain, same-origin. |
ruleset |
RuleFlags[] |
No | ['default'] |
Rulesets to use: default, disable-oobee, enable-wcag-aaa |
specifiedMaxConcurrency |
number |
No | 25 |
Maximum concurrent requests |
followRobots |
boolean |
No | false |
Follow robots.txt |
htmlMaxBytes |
number |
No | 1024 |
Maximum bytes of HTML saved for each affected element. Sets OOBEE_HTML_MAX_BYTES. |
parentHtmlDepth |
number |
No | 0 |
Number of parent levels of HTML to save with each affected element. 0 turns it off. Sets OOBEE_PARENT_HTML_DEPTH. |
parentHtmlMaxBytes |
number |
No | Value of htmlMaxBytes |
Maximum bytes of parent HTML. Sets OOBEE_PARENT_HTML_MAX_BYTES. |
Instance properties
| Property | Type | Description |
|---|---|---|
scanDetails |
object |
Details of the scan, such as startTime, endTime, crawlType, requestUrl and urlsCrawled |
randomToken |
string |
Unique identifier of the scan. It is used as the results folder name. |
Instance methods
| Method | Returns | Description |
|---|---|---|
getAxeScript() |
string |
The axe-core engine script to inject into the page |
getOobeeFunctions() |
string |
The Oobee functions script to inject into the page. Defines runA11yScan on window. Call it after getAxeScript(). |
gradeReadability(sentences) |
string |
Grades the readability of extracted sentences. It runs synchronously. It returns an empty string when the text passes, has fewer than 20 words or is empty, and returns the score as a string when the score is above 0 and at most 50. Pass the result as gradingReadabilityFlag to runA11yScan. |
pushScanResults(res, metadata, elementsToClick, page, disableScreenshots) |
Promise<{ mustFix: number, goodToFix: number }> |
Adds one page’s scan results to the report |
testThresholds() |
void |
Throws if the accumulated counts exceed thresholds, after terminating the instance |
terminate() |
Promise<string> |
Stops the instance, writes the reports and returns the results folder name |
After terminate(), getAxeScript(), getOobeeFunctions(), pushScanResults() and terminate() throw “This instance of Oobee was terminated. Please start a new instance.”
runA11yScan
window.runA11yScan(elementsToScan, gradingReadabilityFlag) runs in the page after you inject both scripts.
| Parameter | Type | Description |
|---|---|---|
elementsToScan |
string[] |
CSS selectors, or other axe-core context values, to scan. An empty array or no value scans the whole page. |
gradingReadabilityFlag |
string |
Readability score as a string. If set and not empty, and AAA rules are enabled, Oobee adds the readability check. |
It returns { pageUrl, pageTitle, axeScanResults }.
pushScanResults parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
res |
{ pageUrl, pageTitle, axeScanResults } |
Yes | The object returned by runA11yScan |
metadata |
string |
No | Extra text to store with the result. The report HTML does not show it. |
elementsToClick |
string[] |
No | CSS selectors to click before Oobee takes screenshots in its own browser. Used only when page is not set and screenshots are on. |
page |
Playwright Page |
No | Page to reuse for screenshots. If not set, Oobee opens its own Chrome browser. |
disableScreenshots |
boolean |
No | Default false. Set to true to skip screenshots, for example under Cypress. |
scanPage
Signature: async scanPage(pages, config). Scans one or more Playwright Page objects by injecting the Oobee engine, then submits and returns the results.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
pages |
Page or Page[] |
Yes | None | Playwright pages to scan |
config.name |
string |
Yes | None | Name for results |
config.email |
string |
Yes | None | Email address for results |
config.pageTitle |
string |
No | The page’s title | Overrides the page title. Applies only when you pass a single page. |
config.metadata |
string |
No | '' |
Extra metadata |
config.ruleset |
RuleFlags[] |
No | ['default'] |
Rulesets to use |
config.scanSource |
string |
No | undefined |
Source label recorded with the scan |
Returns the results for one page as an object, or merged results for several pages. Each has mustFix, goodToFix and needsReview categories with totalItems and rules.
scanHTML
Signature: async scanHTML(htmlContent, config). Scans HTML strings in a JSDOM environment in Node.js, without a browser. This is an experimental feature. It cannot find issues that need page layout or script execution.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
htmlContent |
string or string[] |
Yes | None | HTML to scan |
config.name |
string |
Yes | None | Name for results |
config.email |
string |
Yes | None | Email address for results |
config.pageUrl |
string |
No | 'raw-html' |
URL label for the report. For an array, Oobee appends -1, -2 and so on. |
config.pageTitle |
string |
No | 'HTML Content' |
Title label. For an array, Oobee appends a number. |
config.metadata |
string |
No | '' |
Extra metadata |
config.ruleset |
RuleFlags[] |
No | ['default'] |
Rulesets to use |
config.scanSource |
string |
No | undefined |
Source label recorded with the scan |
scanHTML runs the axe-core tags wcag2a, wcag2aa, wcag21a and wcag21aa, and adds wcag2aaa when enable-wcag-aaa is set. It returns the same result shape as scanPage.
| Limit | Default | Environment variable |
|---|---|---|
| Maximum size of one HTML string | 50 MB | OOBEE_SCANHTML_MAX_BYTES |
| Maximum time for one axe-core run | 300000 ms | OOBEE_SCANHTML_AXE_TIMEOUT_MS |
Set either variable to 0 for no limit.
scanCustomFlow
Signature: scanCustomFlow(config). Starts a custom flow scan in a visible Chrome window and returns a session handle at once. Run only one scanCustomFlow at a time in a Node.js process.
scanCustomFlow config
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
url |
string |
Yes | None | Start URL. Allowed schemes are http:, https: and local file:. |
name |
string |
Yes | None | Name for results |
email |
string |
Yes | None | Email address for results |
browser |
BrowserTypes |
No | Chrome | Browser to use |
deviceChosen |
string |
No | 'Desktop' |
Device name |
customDevice |
string |
No | '' |
Custom device name |
viewportWidth |
number |
No | 1920 |
Viewport width in pixels |
includeScreenshots |
boolean |
No | false |
Include element screenshots |
customFlowLabel |
string |
No | '' |
Label for the flow |
ruleset |
RuleFlags[] |
No | ['default'] |
Rulesets to use |
strategy |
EnqueueStrategy |
No | EnqueueStrategy.All |
Link-following strategy |
followRobots |
boolean |
No | false |
Follow robots.txt |
blacklistedPatterns |
string[] or null |
No | null |
URL patterns to exclude |
extraHTTPHeaders |
Record<string, string> |
No | undefined |
Headers to send |
zip |
string |
No | 'oobee-scan-results' |
Name of the results zip file |
metadata |
string |
No | '{}' |
Extra metadata |
cleanupArtifacts |
boolean |
No | true |
Delete the results folder after the scan |
waitForResultSubmission |
boolean |
No | true |
Wait for the result submission before the result resolves |
maxPagesToScan |
number |
No | undefined |
Maximum pages the user can scan |
scanSource |
string |
No | undefined |
Source label recorded with the scan |
overlayScope |
'all', 'same-domain' or 'same-origin' |
No | 'all' |
Where the Oobee toolbar appears |
onReady |
() => void |
No | None | Called when the browser is ready |
onFinalizing |
() => void |
No | None | Called when the scan is ending |
The config also accepts playwrightDeviceDetailsObject, randomToken, useExtensionOverlayUi and extensionSessionOrigin, which are used by tools that embed Oobee.
scanCustomFlow session and result
| Member | Type | Description |
|---|---|---|
ready |
Promise<void> |
Resolves when the browser is ready |
result |
Promise<ScanCustomFlowResult> |
Resolves when the scan ends |
stop() |
Promise<void> |
Ends the scan. Waits for ready first. |
focus() |
Promise<void> |
Brings the browser window to the front. Waits for ready first. |
ScanCustomFlowResult contains customFlowLabel, scanData, scanItems, results (Must Fix, Good to Fix and Needs Review categories by rule ID) and, in the type, resultDirectory and artifacts.
scanCustomFlow security
| Setting | Detail |
|---|---|
| Always blocked | Schemes other than http:, https: and local file:, remote file: hosts, and link-local and cloud-metadata addresses |
OOBEE_SSRF_PROTECTION |
Set to 1, true or yes to also refuse file://, localhost and private hosts. Required if you pass URLs from untrusted users. Off by default. |
Constraints and limitations
| Constraint | Detail |
|---|---|
| Terminated instance | After terminate(), a new instance is required. |
| No pages scanned | terminate() prints “No pages were scanned.” and writes no reports. |
| Threshold counts | Counts are cumulative across all pages pushed to the instance. |
| Concurrent custom flows | scanCustomFlow is single-flight per Node.js process. |
| Node.js only | scanHTML and the instance run in Node.js and need the Oobee dependencies built. |
| Usage data | terminate(), scanPage and scanHTML submit the name, email and a results summary to GovTech. Set OOBEE_DISABLE_TELEMETRY to 1, true or yes to stop all submissions. |
