@govtechsg/oobee 0.10.77 → 0.10.78-alpha1

package/INTEGRATION.md

@@ -426,3 +426,46 @@ You will see Oobee results generated in <code>results</code> folder.
     runScript();
 
 </details>
+
+#### Integration with any NodeJS workflow (Beta)
+
+You can also use Oobee in any NodeJS script without needing a specific framework integration pattern. This is useful for custom workflows, CI/CD pipelines, or simple scripts where you manage the browser automation yourself or want to scan static HTML.
+
+Refer to the examples in `examples/oobee-scan-page-demo.js` and `examples/oobee-scan-html-demo.js`.
+
+##### `async scanPage(pages, config)`
+
+Scans one or more Playwright Page objects. This injects the Oobee engine into the page context to perform the audit.
+
+**Parameters:**
+
+- `pages`: A Playwright `Page` object or an array of `Page` objects.
+- `config`: Configuration object
+  - `name`: Name for results (required)
+  - `email`: Email for results (required)
+  - `pageTitle`: Optional override for page title (only applied if scanning a single page)
+  - `metadata`: Optional metadata string
+  - `ruleset`: Optional array of `RuleFlags` (e.g. `['enable-wcag-aaa', 'disable-oobee']`)
+
+**Returns:**
+
+- Scan results object containing categorized violations and pass counts.
+
+##### `async scanHTML(htmlContent, config)`
+
+Scans raw HTML string(s). Note that this runs in a JSDOM environment (NodeJS) using axe-core and may not catch accessibility issues that require a full browser layout or JavaScript execution to render.
+
+**Parameters:**
+
+- `htmlContent`: HTML string or array of HTML strings.
+- `config`: Configuration object
+  - `name`: Name for results (required)
+  - `email`: Email for results (required)
+  - `pageUrl`: Optional URL identifier for the report (defaults to 'raw-html')
+  - `pageTitle`: Optional title identifier (defaults to 'HTML Content')
+  - `metadata`: Optional metadata string
+  - `ruleset`: Optional array of `RuleFlags`
+
+**Returns:**
+
+- Scan results object containing categorized violations and pass counts.

package/dist/mergeAxeResults.js

@@ -8,7 +8,6 @@ import { AsyncParser } from '@json2csv/node';
 import zlib from 'zlib';
 import { Base64Encode } from 'base64-stream';
 import { pipeline } from 'stream/promises';
-// @ts-ignore
 import * as Sentry from '@sentry/node';
 import constants, { BrowserTypes, ScannerTypes, sentryConfig, setSentryUser, WCAGclauses, a11yRuleShortDescriptionMap, disabilityBadgesMap, a11yRuleLongDescriptionMap, } from './constants/constants.js';
 import { getBrowserToRun, getPlaywrightLaunchOptions } from './constants/common.js';
@@ -904,31 +903,49 @@ function updateIssuesWithOccurrences(issuesList, urlOccurrencesMap) {
         issue.totalOccurrences = urlOccurrencesMap.get(issue.url) || 0;
     });
 }
-const createRuleIdJson = allIssues => {
+const extractRuleAiData = (ruleId, totalItems, items, callback) => {
+    let snippets = [];
+    if (oobeeAiRules.includes(ruleId)) {
+        const snippetsSet = new Set();
+        if (items) {
+            items.forEach(item => {
+                snippetsSet.add(oobeeAiHtmlETL(item.html));
+            });
+        }
+        snippets = [...snippetsSet];
+        if (callback)
+            callback();
+    }
+    return {
+        snippets,
+        occurrences: totalItems,
+    };
+};
+// This is for telemetry purposes called within mergeAxeResults.ts
+export const createRuleIdJson = allIssues => {
     const compiledRuleJson = {};
-    const ruleIterator = rule => {
-        const ruleId = rule.rule;
-        let snippets = [];
-        if (oobeeAiRules.includes(ruleId)) {
-            const snippetsSet = new Set();
-            rule.pagesAffected.forEach(page => {
-                page.items.forEach(htmlItem => {
-                    snippetsSet.add(oobeeAiHtmlETL(htmlItem.html));
+    ['mustFix', 'goodToFix', 'needsReview'].forEach(category => {
+        allIssues.items[category].rules.forEach(rule => {
+            const allItems = rule.pagesAffected.flatMap(page => page.items || []);
+            compiledRuleJson[rule.rule] = extractRuleAiData(rule.rule, rule.totalItems, allItems, () => {
+                rule.pagesAffected.forEach(p => {
+                    delete p.items;
                 });
             });
-            snippets = [...snippetsSet];
-            rule.pagesAffected.forEach(p => {
-                delete p.items;
+        });
+    });
+    return compiledRuleJson;
+};
+// This is for telemetry purposes called from npmIndex (scanPage and scanHTML) where report is not generated
+export const createBasicFormHTMLSnippet = filteredResults => {
+    const compiledRuleJson = {};
+    ['mustFix', 'goodToFix', 'needsReview'].forEach(category => {
+        if (filteredResults[category] && filteredResults[category].rules) {
+            Object.entries(filteredResults[category].rules).forEach(([ruleId, ruleVal]) => {
+                compiledRuleJson[ruleId] = extractRuleAiData(ruleId, ruleVal.totalItems, ruleVal.items);
             });
         }
-        compiledRuleJson[ruleId] = {
-            snippets,
-            occurrences: rule.totalItems,
-        };
-    };
-    allIssues.items.mustFix.rules.forEach(ruleIterator);
-    allIssues.items.goodToFix.rules.forEach(ruleIterator);
-    allIssues.items.needsReview.rules.forEach(ruleIterator);
+    });
     return compiledRuleJson;
 };
 const moveElemScreenshots = (randomToken, storagePath) => {
@@ -1143,7 +1160,7 @@ function populateScanPagesDetail(allIssues) {
     };
 }
 // Send WCAG criteria breakdown to Sentry
-const sendWcagBreakdownToSentry = async (appVersion, wcagBreakdown, ruleIdJson, scanInfo, allIssues, pagesScannedCount = 0) => {
+export const sendWcagBreakdownToSentry = async (appVersion, wcagBreakdown, ruleIdJson, scanInfo, allIssues, pagesScannedCount = 0) => {
     try {
         // Initialize Sentry
         Sentry.init(sentryConfig);

package/dist/npmIndex.js

@@ -1,13 +1,14 @@
-import fs from 'fs';
 import path from 'path';
 import printMessage from 'print-message';
+import axe from 'axe-core';
+import { JSDOM } from 'jsdom';
 import { fileURLToPath } from 'url';
 import { EnqueueStrategy } from 'crawlee';
 import constants, { BrowserTypes, RuleFlags, ScannerTypes } from './constants/constants.js';
 import { deleteClonedProfiles, getBrowserToRun, getPlaywrightLaunchOptions, submitForm, } from './constants/common.js';
 import { createCrawleeSubFolders, filterAxeResults } from './crawlers/commonCrawlerFunc.js';
-import { createAndUpdateResultsFolders } from './utils.js';
-import generateArtifacts from './mergeAxeResults.js';
+import { createAndUpdateResultsFolders, getVersion } from './utils.js';
+import generateArtifacts, { createBasicFormHTMLSnippet, sendWcagBreakdownToSentry } from './mergeAxeResults.js';
 import { takeScreenshotForHTMLElements } from './screenshotFunc/htmlScreenshotFunc.js';
 import { consoleLogger } from './logs.js';
 import { alertMessageOptions } from './constants/cliFunctions.js';
@@ -21,50 +22,11 @@ import { extractText } from './crawlers/custom/extractText.js';
 import { gradeReadability } from './crawlers/custom/gradeReadability.js';
 const filename = fileURLToPath(import.meta.url);
 const dirname = path.dirname(filename);
-export const init = async ({ entryUrl, testLabel, name, email, includeScreenshots = false, viewportSettings = { width: 1000, height: 660 }, // cypress' default viewport settings
-thresholds = { mustFix: undefined, goodToFix: undefined }, scanAboutMetadata = undefined, zip = 'oobee-scan-results', deviceChosen, strategy = EnqueueStrategy.All, ruleset = [RuleFlags.DEFAULT], specifiedMaxConcurrency = 25, followRobots = false, }) => {
-    consoleLogger.info('Starting Oobee');
-    const [date, time] = new Date().toLocaleString('sv').replaceAll(/-|:/g, '').split(' ');
-    const domain = new URL(entryUrl).hostname;
-    const sanitisedLabel = testLabel ? `_${testLabel.replaceAll(' ', '_')}` : '';
-    const randomToken = `${date}_${time}${sanitisedLabel}_${domain}`;
-    const disableOobee = ruleset.includes(RuleFlags.DISABLE_OOBEE);
-    const enableWcagAaa = ruleset.includes(RuleFlags.ENABLE_WCAG_AAA);
-    // max numbers of mustFix/goodToFix occurrences before test returns a fail
-    const { mustFix: mustFixThreshold, goodToFix: goodToFixThreshold } = thresholds;
-    process.env.CRAWLEE_STORAGE_DIR = randomToken;
-    const scanDetails = {
-        startTime: new Date(),
-        endTime: new Date(),
-        deviceChosen,
-        crawlType: ScannerTypes.CUSTOM,
-        requestUrl: entryUrl,
-        urlsCrawled: { ...constants.urlsCrawledObj },
-        isIncludeScreenshots: includeScreenshots,
-        isAllowSubdomains: strategy,
-        isEnableCustomChecks: ruleset,
-        isEnableWcagAaa: ruleset,
-        isSlowScanMode: specifiedMaxConcurrency,
-        isAdhereRobots: followRobots,
-    };
-    const urlsCrawled = { ...constants.urlsCrawledObj };
-    const { dataset } = await createCrawleeSubFolders(randomToken);
-    let mustFixIssues = 0;
-    let goodToFixIssues = 0;
-    let isInstanceTerminated = false;
-    const throwErrorIfTerminated = () => {
-        if (isInstanceTerminated) {
-            throw new Error('This instance of Oobee was terminated. Please start a new instance.');
-        }
-    };
-    const getAxeScript = () => {
-        throwErrorIfTerminated();
-        const axeScript = fs.readFileSync(path.join(dirname, '../../../axe-core/axe.min.js'), 'utf-8');
-        return axeScript;
-    };
-    const getOobeeFunctions = () => {
-        throwErrorIfTerminated();
-        return `
+const getAxeScriptContent = () => {
+    return axe.source;
+};
+const getOobeeFunctionsScript = (disableOobee, enableWcagAaa) => {
+    return `
       // Fix for missing __name function used by bundler
       if (typeof __name === 'undefined') {
         window.__name = function(fn, name) {
@@ -122,7 +84,7 @@ thresholds = { mustFix: undefined, goodToFix: undefined }, scanAboutMetadata = u
                 return !node.dataset.flagged; // fail any element with a data-flagged attribute set to true
               },
             },
-            ...(enableWcagAaa
+            ...((enableWcagAaa && !disableOobee)
               ? [
                   {
                     id: 'oobee-grading-text-contents',
@@ -170,19 +132,23 @@ thresholds = { mustFix: undefined, goodToFix: undefined }, scanAboutMetadata = u
                 helpUrl: 'https://www.deque.com/blog/accessible-aria-buttons',
               },
             },
-            {
-              id: 'oobee-grading-text-contents',
-              selector: 'html',
-              enabled: true,
-              any: ['oobee-grading-text-contents'],
-              tags: ['wcag2aaa', 'wcag315'],
-              metadata: {
-                description:
-                  'Text content should be easy to understand for individuals with education levels up to university graduates. If the text content is difficult to understand, provide supplemental content or a version that is easy to understand.',
-                help: 'Text content should be clear and plain to ensure that it is easily understood.',
-                helpUrl: 'https://www.wcag.com/uncategorized/3-1-5-reading-level/',
-              },
-            },
+            ...((enableWcagAaa && !disableOobee)
+              ? [
+                  {
+                    id: 'oobee-grading-text-contents',
+                    selector: 'html',
+                    enabled: true,
+                    any: ['oobee-grading-text-contents'],
+                    tags: ['wcag2aaa', 'wcag315'],
+                    metadata: {
+                      description:
+                        'Text content should be easy to understand for individuals with education levels up to university graduates. If the text content is difficult to understand, provide supplemental content or a version that is easy to understand.',
+                      help: 'Text content should be clear and plain to ensure that it is easily understood.',
+                      helpUrl: 'https://www.wcag.com/uncategorized/3-1-5-reading-level/',
+                    },
+                  },
+                ]
+              : []),
           ]
             .filter(rule => (disableOobee ? !rule.id.startsWith('oobee') : true))
             .concat(
@@ -235,6 +201,31 @@ thresholds = { mustFix: undefined, goodToFix: undefined }, scanAboutMetadata = u
         const axeScanResults = await (window).axe.run(elementsToScan, {
           resultTypes: ['violations', 'passes', 'incomplete'],
         });
+
+        if (axeScanResults) {
+          ['violations', 'incomplete'].forEach(type => {
+            if (axeScanResults[type]) {
+              axeScanResults[type].forEach(result => {
+                if (result.nodes) {
+                  result.nodes.forEach(node => {
+                     ['any', 'all', 'none'].forEach(key => {
+                        if (node[key]) {
+                          node[key].forEach(check => {
+                            if (check.message && check.message.indexOf("Axe encountered an error") !== -1) {
+                                if (check.data) {
+                                  // console.error(check.data);
+                                  console.error("Axe encountered an error: " + (check.data.stack || check.data.message || JSON.stringify(check.data)));
+                                }
+                            }
+                          });
+                        }
+                     });
+                  });
+                }
+              });
+            }
+          });
+        }
   
         // add custom Oobee violations
         if (!(window).disableOobee) {
@@ -284,6 +275,50 @@ thresholds = { mustFix: undefined, goodToFix: undefined }, scanAboutMetadata = u
       window.enableWcagAaa=${enableWcagAaa};
       window.runA11yScan = runA11yScan;
     `;
+};
+export const init = async ({ entryUrl, testLabel, name, email, includeScreenshots = false, viewportSettings = { width: 1000, height: 660 }, // cypress' default viewport settings
+thresholds = { mustFix: undefined, goodToFix: undefined }, scanAboutMetadata = undefined, zip = 'oobee-scan-results', deviceChosen, strategy = EnqueueStrategy.All, ruleset = [RuleFlags.DEFAULT], specifiedMaxConcurrency = 25, followRobots = false, }) => {
+    consoleLogger.info('Starting Oobee');
+    const [date, time] = new Date().toLocaleString('sv').replaceAll(/-|:/g, '').split(' ');
+    const domain = new URL(entryUrl).hostname;
+    const sanitisedLabel = testLabel ? `_${testLabel.replaceAll(' ', '_')}` : '';
+    const randomToken = `${date}_${time}${sanitisedLabel}_${domain}`;
+    const disableOobee = ruleset.includes(RuleFlags.DISABLE_OOBEE);
+    const enableWcagAaa = ruleset.includes(RuleFlags.ENABLE_WCAG_AAA);
+    // max numbers of mustFix/goodToFix occurrences before test returns a fail
+    const { mustFix: mustFixThreshold, goodToFix: goodToFixThreshold } = thresholds;
+    process.env.CRAWLEE_STORAGE_DIR = randomToken;
+    const scanDetails = {
+        startTime: new Date(),
+        endTime: new Date(),
+        deviceChosen,
+        crawlType: ScannerTypes.CUSTOM,
+        requestUrl: entryUrl,
+        urlsCrawled: { ...constants.urlsCrawledObj },
+        isIncludeScreenshots: includeScreenshots,
+        isAllowSubdomains: strategy,
+        isEnableCustomChecks: ruleset,
+        isEnableWcagAaa: ruleset,
+        isSlowScanMode: specifiedMaxConcurrency,
+        isAdhereRobots: followRobots,
+    };
+    const urlsCrawled = { ...constants.urlsCrawledObj };
+    const { dataset } = await createCrawleeSubFolders(randomToken);
+    let mustFixIssues = 0;
+    let goodToFixIssues = 0;
+    let isInstanceTerminated = false;
+    const throwErrorIfTerminated = () => {
+        if (isInstanceTerminated) {
+            throw new Error('This instance of Oobee was terminated. Please start a new instance.');
+        }
+    };
+    const getAxeScript = () => {
+        throwErrorIfTerminated();
+        return getAxeScriptContent();
+    };
+    const getOobeeFunctions = () => {
+        throwErrorIfTerminated();
+        return getOobeeFunctionsScript(disableOobee, enableWcagAaa);
     };
     // Helper script for manually copy-paste testing in Chrome browser
     /*
@@ -427,3 +462,179 @@ thresholds = { mustFix: undefined, goodToFix: undefined }, scanAboutMetadata = u
     };
 };
 export default init;
+const processAndSubmitResults = async (scanData, name, email, metadata) => {
+    const items = Array.isArray(scanData) ? scanData : [scanData];
+    const numberOfPagesScanned = items.length;
+    const allFilteredResults = items.map((item, index) => {
+        const filtered = filterAxeResults(item.axeScanResults, item.pageTitle, { pageIndex: index + 1, metadata });
+        filtered.url = item.pageUrl;
+        return filtered;
+    });
+    const mergedResults = {
+        mustFix: { totalItems: 0, rules: {} },
+        goodToFix: { totalItems: 0, rules: {} },
+        needsReview: { totalItems: 0, rules: {} },
+        // omitting passed from being processed to reduce payload size
+        // passed: { totalItems: 0, rules: {} },
+    };
+    allFilteredResults.forEach(result => {
+        ['mustFix', 'goodToFix', 'needsReview'].forEach(category => {
+            const categoryResult = result[category];
+            if (categoryResult) {
+                mergedResults[category].totalItems += categoryResult.totalItems;
+                Object.entries(categoryResult.rules).forEach(([ruleId, ruleVal]) => {
+                    if (!mergedResults[category].rules[ruleId]) {
+                        mergedResults[category].rules[ruleId] = JSON.parse(JSON.stringify(ruleVal));
+                        // Map the description to the short description if available
+                        if (constants.a11yRuleShortDescriptionMap[ruleId]) {
+                            mergedResults[category].rules[ruleId].description = constants.a11yRuleShortDescriptionMap[ruleId];
+                        }
+                        // Add url to items
+                        mergedResults[category].rules[ruleId].items.forEach((item) => {
+                            item.url = result.url;
+                            if (item.displayNeedsReview) {
+                                delete item.displayNeedsReview;
+                            }
+                        });
+                    }
+                    else {
+                        mergedResults[category].rules[ruleId].totalItems += ruleVal.totalItems;
+                        const newItems = ruleVal.items.map((item) => {
+                            const newItem = { ...item, url: result.url };
+                            if (newItem.displayNeedsReview) {
+                                delete newItem.displayNeedsReview;
+                            }
+                            return newItem;
+                        });
+                        mergedResults[category].rules[ruleId].items.push(...newItems);
+                    }
+                });
+            }
+        });
+    });
+    const basicFormHTMLSnippet = createBasicFormHTMLSnippet(mergedResults);
+    const entryUrl = items[0].pageUrl;
+    await submitForm(BrowserTypes.CHROMIUM, '', entryUrl, null, ScannerTypes.CUSTOM, email, name, JSON.stringify(basicFormHTMLSnippet), numberOfPagesScanned, 0, 0, '{}');
+    // Generate WCAG breakdown for Sentry
+    const wcagOccurrencesMap = new Map();
+    // Iterate through relevant categories to collect WCAG violation occurrences
+    ['mustFix', 'goodToFix'].forEach(category => {
+        const rulesObj = mergedResults[category]?.rules;
+        if (rulesObj) {
+            Object.values(rulesObj).forEach((rule) => {
+                const count = rule.totalItems;
+                if (rule.conformance && Array.isArray(rule.conformance)) {
+                    rule.conformance
+                        .filter((c) => /wcag[0-9]{3,4}/.test(c))
+                        .forEach((c) => {
+                        const current = wcagOccurrencesMap.get(c) || 0;
+                        wcagOccurrencesMap.set(c, current + count);
+                    });
+                }
+            });
+        }
+    });
+    const oobeeAppVersion = getVersion();
+    await sendWcagBreakdownToSentry(oobeeAppVersion, wcagOccurrencesMap, basicFormHTMLSnippet, {
+        entryUrl: entryUrl,
+        scanType: ScannerTypes.CUSTOM,
+        browser: 'chromium', // Defaulting since we might scan HTML without browser or implicit browser
+        email: email,
+        name: name,
+    }, undefined, numberOfPagesScanned);
+    // Return original single result if only one page was scanning to maintain backward compatibility structure
+    if (numberOfPagesScanned === 1) {
+        const singleResult = allFilteredResults[0];
+        // Clean up displayNeedsReview from single result
+        ['mustFix', 'goodToFix', 'needsReview'].forEach(category => {
+            const resultCategory = singleResult[category];
+            if (resultCategory && resultCategory.rules) {
+                Object.values(resultCategory.rules).forEach((rule) => {
+                    // Map the description to the short description if available
+                    if (constants.a11yRuleShortDescriptionMap[rule.rule]) {
+                        rule.description = constants.a11yRuleShortDescriptionMap[rule.rule];
+                    }
+                    if (rule.items) {
+                        rule.items.forEach((item) => {
+                            // Ensure item URL matches the result URL
+                            item.url = singleResult.url;
+                            if (item.displayNeedsReview) {
+                                delete item.displayNeedsReview;
+                            }
+                        });
+                    }
+                });
+            }
+        });
+        return singleResult;
+    }
+    return mergedResults;
+};
+// This is an experimental feature to scan static HTML code without the need for Playwright browser
+export const scanHTML = async (htmlContent, config) => {
+    const { name, email, pageUrl = 'raw-html', pageTitle = 'HTML Content', metadata = '', ruleset = [RuleFlags.DEFAULT], } = config;
+    const enableWcagAaa = ruleset.includes(RuleFlags.ENABLE_WCAG_AAA);
+    const tags = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'];
+    if (enableWcagAaa) {
+        tags.push('wcag2aaa');
+    }
+    const htmlItems = Array.isArray(htmlContent) ? htmlContent : [htmlContent];
+    const scanData = [];
+    for (let i = 0; i < htmlItems.length; i++) {
+        const htmlString = htmlItems[i];
+        const dom = new JSDOM(htmlString);
+        // Configure axe for node environment
+        // eslint-disable-next-line no-await-in-loop
+        const axeScanResults = await axe.run(dom.window.document.documentElement, {
+            runOnly: {
+                type: 'tag',
+                values: tags,
+            },
+            resultTypes: ['violations', 'passes', 'incomplete'],
+        });
+        scanData.push({
+            axeScanResults,
+            pageUrl: htmlItems.length > 1 ? `${pageUrl}-${i + 1}` : pageUrl,
+            pageTitle: htmlItems.length > 1 ? `${pageTitle} ${i + 1}` : pageTitle,
+        });
+    }
+    return processAndSubmitResults(scanData, name, email, metadata);
+};
+export const scanPage = async (pages, config) => {
+    const { name, email, pageTitle, metadata = '', ruleset = [RuleFlags.DEFAULT], } = config;
+    const disableOobee = ruleset.includes(RuleFlags.DISABLE_OOBEE);
+    const enableWcagAaa = ruleset.includes(RuleFlags.ENABLE_WCAG_AAA);
+    const axeScript = getAxeScriptContent();
+    const oobeeFunctions = getOobeeFunctionsScript(disableOobee, enableWcagAaa);
+    const pagesArray = Array.isArray(pages) ? pages : [pages];
+    const scanData = [];
+    for (const page of pagesArray) {
+        await page.evaluate(`${axeScript}\n${oobeeFunctions}`);
+        // Run the scan inside the page
+        const consoleListener = (msg) => {
+            if (msg.type() === 'error') {
+                console.error(`[Browser Console] ${msg.text()}`);
+            }
+        };
+        page.on('console', consoleListener);
+        try {
+            const scanResult = await page.evaluate(async () => {
+                return window.runA11yScan();
+            });
+            scanData.push({
+                axeScanResults: scanResult.axeScanResults,
+                pageUrl: page.url(),
+                pageTitle: await page.title(),
+            });
+        }
+        finally {
+            page.off('console', consoleListener);
+        }
+    }
+    // Allow override of page title if scanning a single page
+    if (!Array.isArray(pages) && pageTitle) {
+        scanData[0].pageTitle = pageTitle;
+    }
+    return processAndSubmitResults(scanData, name, email, metadata);
+};
+export { RuleFlags };

package/examples/oobee-scan-html-demo.js

@@ -0,0 +1,51 @@
+import { scanHTML } from '../dist/npmIndex.js';
+
+const htmlContent = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>Test Page</title>
+</head>
+<body>
+    <h1>Accessibility Test</h1>
+    <button></button>              <!-- Violation: button-name -->
+    <img src="test.jpg" />         <!-- Violation: image-alt -->
+    <div role="button">Fake</div>  <!-- Violation: role-button (if interactive) -->
+</body>
+</html>
+`;
+
+const htmlContent2 = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>Test Page 2</title>
+</head>
+<body>
+    <h1>Accessibility Test 2</h1>
+    <a href="#">Click me</a>       <!-- Violation: link-name (if vague) or empty href issues -->
+    <input type="text" />          <!-- Violation: label -->
+</body>
+</html>
+`;
+
+(async () => {
+  console.log("Scanning HTML string...");
+  try {
+    // Run scanHTML without needing full Oobee init
+    // Pass an array of HTML strings to demonstrate batch scanning
+    const results = await scanHTML(
+      [htmlContent, htmlContent2], 
+      {
+        name: "Your Name",
+        email: "email@domain.com",
+      }
+    );
+    console.log(JSON.stringify(results, null, 2));
+
+    console.log(`\nScan Complete.`);
+
+  } catch (error) {
+    console.error("Error during scan:", error);
+  }
+})();

package/examples/oobee-scan-page-demo.js

@@ -0,0 +1,40 @@
+import { chromium } from 'playwright';
+import { scanPage } from '../dist/npmIndex.js';
+
+(async () => {
+  console.log("Launching browser...");
+  const browser = await chromium.launch({ 
+    headless: false,
+    channel: 'chrome' // Use Chrome instead of Chromium
+  }); 
+  const page = await browser.newPage();
+
+  console.log("Navigating to test page...");
+  // Using a sample page that likely has accessibility issues
+  await page.goto('https://govtechsg.github.io/purple-banner-embeds/purple-integrated-scan-example.htm');
+
+  const page2 = await browser.newPage();
+  console.log("Navigating to second test page...");
+  await page2.goto('https://a11y.tech.gov.sg');
+
+  console.log("Scanning page...");
+  try {
+    // Run scanPage using the existing Playwright page
+    const results = await scanPage(
+      [page, page2], 
+      {
+        name: "Your Name",
+        email: "email@domain.com",
+      }
+    );
+
+    console.log(JSON.stringify(results, null, 2));
+
+    console.log(`\nScan Complete.`);
+
+  } catch (error) {
+    console.error("Error during scan:", error);
+  } finally {
+    await browser.close();
+  }
+})();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@govtechsg/oobee",
   "main": "dist/npmIndex.js",
-  "version": "0.10.77",
+  "version": "0.10.78-alpha1",
   "type": "module",
   "author": "Government Technology Agency <info@tech.gov.sg>",
   "bin": {

package/src/mergeAxeResults.ts

@@ -12,7 +12,6 @@ import { AsyncParser, ParserOptions } from '@json2csv/node';
 import zlib from 'zlib';
 import { Base64Encode } from 'base64-stream';
 import { pipeline } from 'stream/promises';
-// @ts-ignore
 import * as Sentry from '@sentry/node';
 import constants, {
   BrowserTypes,
@@ -1289,34 +1288,56 @@ function updateIssuesWithOccurrences(issuesList: any[], urlOccurrencesMap: Map<s
   });
 }
 
+const extractRuleAiData = (ruleId: string, totalItems: number, items: any[], callback?: () => void) => {
+  let snippets = [];
+
+  if (oobeeAiRules.includes(ruleId)) {
+    const snippetsSet = new Set();
+    if (items) {
+      items.forEach(item => {
+        snippetsSet.add(oobeeAiHtmlETL(item.html));
+      });
+    }
+    snippets = [...snippetsSet];
+    if (callback) callback();
+  }
+  return {
+    snippets,
+    occurrences: totalItems,
+  };
+};
+
+// This is for telemetry purposes called within mergeAxeResults.ts
+export
 const createRuleIdJson = allIssues => {
   const compiledRuleJson = {};
 
-  const ruleIterator = rule => {
-    const ruleId = rule.rule;
-    let snippets = [];
-
-    if (oobeeAiRules.includes(ruleId)) {
-      const snippetsSet = new Set();
-      rule.pagesAffected.forEach(page => {
-        page.items.forEach(htmlItem => {
-          snippetsSet.add(oobeeAiHtmlETL(htmlItem.html));
+  ['mustFix', 'goodToFix', 'needsReview'].forEach(category => {
+    allIssues.items[category].rules.forEach(rule => {
+      const allItems = rule.pagesAffected.flatMap(page => page.items || []);
+      compiledRuleJson[rule.rule] = extractRuleAiData(rule.rule, rule.totalItems, allItems, () => {
+        rule.pagesAffected.forEach(p => {
+          delete p.items;
         });
       });
-      snippets = [...snippetsSet];
-      rule.pagesAffected.forEach(p => {
-        delete p.items;
+    });
+  });
+
+  return compiledRuleJson;
+};
+
+// This is for telemetry purposes called from npmIndex (scanPage and scanHTML) where report is not generated
+export const createBasicFormHTMLSnippet = filteredResults => {
+  const compiledRuleJson = {};
+
+  ['mustFix', 'goodToFix', 'needsReview'].forEach(category => {
+    if (filteredResults[category] && filteredResults[category].rules) {
+      Object.entries(filteredResults[category].rules).forEach(([ruleId, ruleVal]: [string, any]) => {
+        compiledRuleJson[ruleId] = extractRuleAiData(ruleId, ruleVal.totalItems, ruleVal.items);
       });
     }
-    compiledRuleJson[ruleId] = {
-      snippets,
-      occurrences: rule.totalItems,
-    };
-  };
+  });
 
-  allIssues.items.mustFix.rules.forEach(ruleIterator);
-  allIssues.items.goodToFix.rules.forEach(ruleIterator);
-  allIssues.items.needsReview.rules.forEach(ruleIterator);
   return compiledRuleJson;
 };
 
@@ -1587,7 +1608,7 @@ function populateScanPagesDetail(allIssues: AllIssues): void {
 }
 
 // Send WCAG criteria breakdown to Sentry
-const sendWcagBreakdownToSentry = async (
+export const sendWcagBreakdownToSentry = async (
   appVersion: string,
   wcagBreakdown: Map<string, number>,
   ruleIdJson: any,

package/src/npmIndex.ts

@@ -2,6 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import printMessage from 'print-message';
 import axe, { AxeResults, ImpactValue } from 'axe-core';
+import { JSDOM } from 'jsdom';
 import { fileURLToPath } from 'url';
 import { EnqueueStrategy } from 'crawlee';
 import constants, { BrowserTypes, RuleFlags, ScannerTypes } from './constants/constants.js';
@@ -12,8 +13,8 @@ import {
   submitForm,
 } from './constants/common.js';
 import { createCrawleeSubFolders, filterAxeResults } from './crawlers/commonCrawlerFunc.js';
-import { createAndUpdateResultsFolders } from './utils.js';
-import generateArtifacts from './mergeAxeResults.js';
+import { createAndUpdateResultsFolders, getVersion } from './utils.js';
+import generateArtifacts, { createBasicFormHTMLSnippet, sendWcagBreakdownToSentry } from './mergeAxeResults.js';
 import { takeScreenshotForHTMLElements } from './screenshotFunc/htmlScreenshotFunc.js';
 import { consoleLogger, silentLogger } from './logs.js';
 import { alertMessageOptions } from './constants/cliFunctions.js';
@@ -26,101 +27,42 @@ import xPathToCss from './crawlers/custom/xPathToCss.js';
 import { extractText } from './crawlers/custom/extractText.js';
 import { gradeReadability } from './crawlers/custom/gradeReadability.js';
 import { BrowserContext, Page } from 'playwright';
+import { filter } from 'jszip';
+
+// Define global window properties for Oobee injection functions
+declare global {
+  interface Window {
+    runA11yScan: (
+      elements?: any[],
+      gradingReadabilityFlag?: string,
+    ) => Promise<{
+      pageUrl: string;
+      pageTitle: string;
+      axeScanResults: AxeResults;
+    }>;
+    axe: any;
+    getAxeConfiguration: any;
+    flagUnlabelledClickableElements: any;
+    disableOobee: boolean;
+    enableWcagAaa: boolean;
+    xPathToCss: any;
+    evaluateAltText: any;
+    escapeCssSelector: any;
+    framesCheck: any;
+    findElementByCssSelector: any;
+    extractText: any;
+  }
+}
 
 const filename = fileURLToPath(import.meta.url);
 const dirname = path.dirname(filename);
 
-export const init = async ({
-  entryUrl,
-  testLabel,
-  name,
-  email,
-  includeScreenshots = false,
-  viewportSettings = { width: 1000, height: 660 }, // cypress' default viewport settings
-  thresholds = { mustFix: undefined, goodToFix: undefined },
-  scanAboutMetadata = undefined,
-  zip = 'oobee-scan-results',
-  deviceChosen,
-  strategy = EnqueueStrategy.All,
-  ruleset = [RuleFlags.DEFAULT],
-  specifiedMaxConcurrency = 25,
-  followRobots = false,
-}: {
-  entryUrl: string;
-  testLabel: string;
-  name: string;
-  email: string;
-  includeScreenshots?: boolean;
-  viewportSettings?: { width: number; height: number };
-  thresholds?: { mustFix: number; goodToFix: number };
-  scanAboutMetadata?: {
-    browser?: string;
-    viewport?: { width: number; height: number };
-  };
-  zip?: string;
-  deviceChosen?: string;
-  strategy?: EnqueueStrategy;
-  ruleset?: RuleFlags[];
-  specifiedMaxConcurrency?: number;
-  followRobots?: boolean;
-}) => {
-  consoleLogger.info('Starting Oobee');
-
-  const [date, time] = new Date().toLocaleString('sv').replaceAll(/-|:/g, '').split(' ');
-  const domain = new URL(entryUrl).hostname;
-  const sanitisedLabel = testLabel ? `_${testLabel.replaceAll(' ', '_')}` : '';
-  const randomToken = `${date}_${time}${sanitisedLabel}_${domain}`;
-
-  const disableOobee = ruleset.includes(RuleFlags.DISABLE_OOBEE);
-  const enableWcagAaa = ruleset.includes(RuleFlags.ENABLE_WCAG_AAA);
-
-  // max numbers of mustFix/goodToFix occurrences before test returns a fail
-  const { mustFix: mustFixThreshold, goodToFix: goodToFixThreshold } = thresholds;
-
-  process.env.CRAWLEE_STORAGE_DIR = randomToken;
-
-  const scanDetails = {
-    startTime: new Date(),
-    endTime: new Date(),
-    deviceChosen,
-    crawlType: ScannerTypes.CUSTOM,
-    requestUrl: entryUrl,
-    urlsCrawled: { ...constants.urlsCrawledObj },
-    isIncludeScreenshots: includeScreenshots,
-    isAllowSubdomains: strategy,
-    isEnableCustomChecks: ruleset,
-    isEnableWcagAaa: ruleset,
-    isSlowScanMode: specifiedMaxConcurrency,
-    isAdhereRobots: followRobots,
-  };
-
-  const urlsCrawled = { ...constants.urlsCrawledObj };
-
-  const { dataset } = await createCrawleeSubFolders(randomToken);
-
-  let mustFixIssues = 0;
-  let goodToFixIssues = 0;
-
-  let isInstanceTerminated = false;
-
-  const throwErrorIfTerminated = () => {
-    if (isInstanceTerminated) {
-      throw new Error('This instance of Oobee was terminated. Please start a new instance.');
-    }
-  };
-
-  const getAxeScript = () => {
-    throwErrorIfTerminated();
-    const axeScript = fs.readFileSync(
-      path.join(dirname, '../../../axe-core/axe.min.js'),
-      'utf-8',
-    );
-    return axeScript;
-  };
+const getAxeScriptContent = () => {
+  return axe.source;
+};
 
-  const getOobeeFunctions = () => {
-    throwErrorIfTerminated();
-    return `
+const getOobeeFunctionsScript = (disableOobee: boolean, enableWcagAaa: boolean) => {
+  return `
       // Fix for missing __name function used by bundler
       if (typeof __name === 'undefined') {
         window.__name = function(fn, name) {
@@ -178,7 +120,7 @@ export const init = async ({
                 return !node.dataset.flagged; // fail any element with a data-flagged attribute set to true
               },
             },
-            ...(enableWcagAaa
+            ...((enableWcagAaa && !disableOobee)
               ? [
                   {
                     id: 'oobee-grading-text-contents',
@@ -226,19 +168,23 @@ export const init = async ({
                 helpUrl: 'https://www.deque.com/blog/accessible-aria-buttons',
               },
             },
-            {
-              id: 'oobee-grading-text-contents',
-              selector: 'html',
-              enabled: true,
-              any: ['oobee-grading-text-contents'],
-              tags: ['wcag2aaa', 'wcag315'],
-              metadata: {
-                description:
-                  'Text content should be easy to understand for individuals with education levels up to university graduates. If the text content is difficult to understand, provide supplemental content or a version that is easy to understand.',
-                help: 'Text content should be clear and plain to ensure that it is easily understood.',
-                helpUrl: 'https://www.wcag.com/uncategorized/3-1-5-reading-level/',
-              },
-            },
+            ...((enableWcagAaa && !disableOobee)
+              ? [
+                  {
+                    id: 'oobee-grading-text-contents',
+                    selector: 'html',
+                    enabled: true,
+                    any: ['oobee-grading-text-contents'],
+                    tags: ['wcag2aaa', 'wcag315'],
+                    metadata: {
+                      description:
+                        'Text content should be easy to understand for individuals with education levels up to university graduates. If the text content is difficult to understand, provide supplemental content or a version that is easy to understand.',
+                      help: 'Text content should be clear and plain to ensure that it is easily understood.',
+                      helpUrl: 'https://www.wcag.com/uncategorized/3-1-5-reading-level/',
+                    },
+                  },
+                ]
+              : []),
           ]
             .filter(rule => (disableOobee ? !rule.id.startsWith('oobee') : true))
             .concat(
@@ -291,6 +237,31 @@ export const init = async ({
         const axeScanResults = await (window).axe.run(elementsToScan, {
           resultTypes: ['violations', 'passes', 'incomplete'],
         });
+
+        if (axeScanResults) {
+          ['violations', 'incomplete'].forEach(type => {
+            if (axeScanResults[type]) {
+              axeScanResults[type].forEach(result => {
+                if (result.nodes) {
+                  result.nodes.forEach(node => {
+                     ['any', 'all', 'none'].forEach(key => {
+                        if (node[key]) {
+                          node[key].forEach(check => {
+                            if (check.message && check.message.indexOf("Axe encountered an error") !== -1) {
+                                if (check.data) {
+                                  // console.error(check.data);
+                                  console.error("Axe encountered an error: " + (check.data.stack || check.data.message || JSON.stringify(check.data)));
+                                }
+                            }
+                          });
+                        }
+                     });
+                  });
+                }
+              });
+            }
+          });
+        }
   
         // add custom Oobee violations
         if (!(window).disableOobee) {
@@ -340,6 +311,95 @@ export const init = async ({
       window.enableWcagAaa=${enableWcagAaa};
       window.runA11yScan = runA11yScan;
     `;
+};
+
+export const init = async ({
+  entryUrl,
+  testLabel,
+  name,
+  email,
+  includeScreenshots = false,
+  viewportSettings = { width: 1000, height: 660 }, // cypress' default viewport settings
+  thresholds = { mustFix: undefined, goodToFix: undefined },
+  scanAboutMetadata = undefined,
+  zip = 'oobee-scan-results',
+  deviceChosen,
+  strategy = EnqueueStrategy.All,
+  ruleset = [RuleFlags.DEFAULT],
+  specifiedMaxConcurrency = 25,
+  followRobots = false,
+}: {
+  entryUrl: string;
+  testLabel: string;
+  name: string;
+  email: string;
+  includeScreenshots?: boolean;
+  viewportSettings?: { width: number; height: number };
+  thresholds?: { mustFix: number; goodToFix: number };
+  scanAboutMetadata?: {
+    browser?: string;
+    viewport?: { width: number; height: number };
+  };
+  zip?: string;
+  deviceChosen?: string;
+  strategy?: EnqueueStrategy;
+  ruleset?: RuleFlags[];
+  specifiedMaxConcurrency?: number;
+  followRobots?: boolean;
+}) => {
+  consoleLogger.info('Starting Oobee');
+
+  const [date, time] = new Date().toLocaleString('sv').replaceAll(/-|:/g, '').split(' ');
+  const domain = new URL(entryUrl).hostname;
+  const sanitisedLabel = testLabel ? `_${testLabel.replaceAll(' ', '_')}` : '';
+  const randomToken = `${date}_${time}${sanitisedLabel}_${domain}`;
+
+  const disableOobee = ruleset.includes(RuleFlags.DISABLE_OOBEE);
+  const enableWcagAaa = ruleset.includes(RuleFlags.ENABLE_WCAG_AAA);
+
+  // max numbers of mustFix/goodToFix occurrences before test returns a fail
+  const { mustFix: mustFixThreshold, goodToFix: goodToFixThreshold } = thresholds;
+
+  process.env.CRAWLEE_STORAGE_DIR = randomToken;
+
+  const scanDetails = {
+    startTime: new Date(),
+    endTime: new Date(),
+    deviceChosen,
+    crawlType: ScannerTypes.CUSTOM,
+    requestUrl: entryUrl,
+    urlsCrawled: { ...constants.urlsCrawledObj },
+    isIncludeScreenshots: includeScreenshots,
+    isAllowSubdomains: strategy,
+    isEnableCustomChecks: ruleset,
+    isEnableWcagAaa: ruleset,
+    isSlowScanMode: specifiedMaxConcurrency,
+    isAdhereRobots: followRobots,
+  };
+
+  const urlsCrawled = { ...constants.urlsCrawledObj };
+
+  const { dataset } = await createCrawleeSubFolders(randomToken);
+
+  let mustFixIssues = 0;
+  let goodToFixIssues = 0;
+
+  let isInstanceTerminated = false;
+
+  const throwErrorIfTerminated = () => {
+    if (isInstanceTerminated) {
+      throw new Error('This instance of Oobee was terminated. Please start a new instance.');
+    }
+  };
+
+  const getAxeScript = () => {
+    throwErrorIfTerminated();
+    return getAxeScriptContent();
+  };
+
+  const getOobeeFunctions = () => {
+    throwErrorIfTerminated();
+    return getOobeeFunctionsScript(disableOobee, enableWcagAaa);
   };
 
   // Helper script for manually copy-paste testing in Chrome browser
@@ -527,4 +587,295 @@ export const init = async ({
   };
 };
 
-export default init;
+export default init;
+
+const processAndSubmitResults = async (
+  scanData: { axeScanResults: AxeResults; pageUrl: string; pageTitle: string } | { axeScanResults: AxeResults; pageUrl: string; pageTitle: string }[],
+  name: string,
+  email: string,
+  metadata: string,
+) => {
+  const items = Array.isArray(scanData) ? scanData : [scanData];
+  const numberOfPagesScanned = items.length;
+  
+  const allFilteredResults = items.map((item, index) => {
+    const filtered = filterAxeResults(item.axeScanResults, item.pageTitle, { pageIndex: index + 1, metadata });
+    (filtered as any).url = item.pageUrl;
+    return filtered;
+  });
+
+  type Rule = {
+    totalItems: number;
+    items: any[];
+    [key: string]: any;
+  };
+
+  type ResultCategory = {
+    totalItems: number;
+    rules: Record<string, Rule>;
+  };
+
+  type CategoryKey = 'mustFix' | 'goodToFix' | 'needsReview';
+
+  const mergedResults: Record<CategoryKey, ResultCategory> = {
+    mustFix: { totalItems: 0, rules: {} },
+    goodToFix: { totalItems: 0, rules: {} },
+    needsReview: { totalItems: 0, rules: {} },
+    // omitting passed from being processed to reduce payload size
+    // passed: { totalItems: 0, rules: {} },
+  };
+
+  allFilteredResults.forEach(result => {
+    (['mustFix', 'goodToFix', 'needsReview'] as CategoryKey[]).forEach(category => {
+      const categoryResult = (result as any)[category];
+      if (categoryResult) {
+        mergedResults[category].totalItems += categoryResult.totalItems;
+        Object.entries(categoryResult.rules).forEach(([ruleId, ruleVal]: [string, any]) => {
+          if (!mergedResults[category].rules[ruleId]) {
+            mergedResults[category].rules[ruleId] = JSON.parse(JSON.stringify(ruleVal));
+
+            // Map the description to the short description if available
+            if (constants.a11yRuleShortDescriptionMap[ruleId]) {
+              mergedResults[category].rules[ruleId].description = constants.a11yRuleShortDescriptionMap[ruleId];
+            }
+            
+            // Add url to items
+            mergedResults[category].rules[ruleId].items.forEach((item: any) => {
+              item.url = (result as any).url;
+              if (item.displayNeedsReview) {
+                delete item.displayNeedsReview;
+              }
+            });
+          } else {
+            mergedResults[category].rules[ruleId].totalItems += ruleVal.totalItems;
+            const newItems = ruleVal.items.map((item: any) => {
+               const newItem = { ...item, url: (result as any).url };
+               if (newItem.displayNeedsReview) {
+                 delete newItem.displayNeedsReview;
+               }
+               return newItem;
+             });
+            mergedResults[category].rules[ruleId].items.push(...newItems);
+          }
+        });
+      }
+    });
+  });
+
+  const basicFormHTMLSnippet = createBasicFormHTMLSnippet(mergedResults);
+  const entryUrl = items[0].pageUrl;
+
+  await submitForm(
+    BrowserTypes.CHROMIUM,
+    '',
+    entryUrl,
+    null,
+    ScannerTypes.CUSTOM,
+    email,
+    name,
+    JSON.stringify(basicFormHTMLSnippet),
+    numberOfPagesScanned,
+    0,
+    0,
+    '{}',
+  );
+
+  // Generate WCAG breakdown for Sentry
+  const wcagOccurrencesMap = new Map<string, number>();
+  
+  // Iterate through relevant categories to collect WCAG violation occurrences
+  (['mustFix', 'goodToFix'] as CategoryKey[]).forEach(category => {
+    const rulesObj = mergedResults[category]?.rules;
+    if (rulesObj) {
+      Object.values(rulesObj).forEach((rule: any) => {
+        const count = rule.totalItems;
+        if (rule.conformance && Array.isArray(rule.conformance)) {
+          rule.conformance
+            .filter((c: string) => /wcag[0-9]{3,4}/.test(c))
+            .forEach((c: string) => {
+              const current = wcagOccurrencesMap.get(c) || 0;
+              wcagOccurrencesMap.set(c, current + count);
+            });
+        }
+      });
+    }
+  });
+
+  const oobeeAppVersion = getVersion();
+  
+  await sendWcagBreakdownToSentry(
+    oobeeAppVersion,
+    wcagOccurrencesMap,
+    basicFormHTMLSnippet,
+    {
+      entryUrl: entryUrl,
+      scanType: ScannerTypes.CUSTOM,
+      browser: 'chromium', // Defaulting since we might scan HTML without browser or implicit browser
+      email: email,
+      name: name,
+    },
+    undefined,
+    numberOfPagesScanned,
+  );
+
+  // Return original single result if only one page was scanning to maintain backward compatibility structure
+  if (numberOfPagesScanned === 1) {
+    const singleResult = allFilteredResults[0];
+    
+    // Clean up displayNeedsReview from single result
+    (['mustFix', 'goodToFix', 'needsReview'] as CategoryKey[]).forEach(category => {
+      const resultCategory = (singleResult as any)[category];
+      if (resultCategory && resultCategory.rules) {
+        Object.values(resultCategory.rules).forEach((rule: any) => {
+
+          // Map the description to the short description if available
+          if (constants.a11yRuleShortDescriptionMap[rule.rule]) {
+            rule.description = constants.a11yRuleShortDescriptionMap[rule.rule];
+          }
+
+          if (rule.items) {
+           rule.items.forEach((item: any) => {
+             // Ensure item URL matches the result URL
+             item.url = (singleResult as any).url;
+
+             if (item.displayNeedsReview) {
+               delete item.displayNeedsReview;
+             }
+           });
+          }
+        });
+      }
+    });
+
+    return singleResult;
+  }
+
+  return mergedResults;
+};
+
+// This is an experimental feature to scan static HTML code without the need for Playwright browser
+export const scanHTML = async (
+  htmlContent: string | string[],
+  config: {
+    name: string;
+    email: string;
+    pageUrl?: string; // If array, we will append index
+    pageTitle?: string; // If array, we will append index
+    metadata?: string;
+    ruleset?: RuleFlags[];
+  },
+) => {
+  const {
+    name,
+    email,
+    pageUrl = 'raw-html',
+    pageTitle = 'HTML Content',
+    metadata = '',
+    ruleset = [RuleFlags.DEFAULT],
+  } = config;
+
+  const enableWcagAaa = ruleset.includes(RuleFlags.ENABLE_WCAG_AAA);
+  const tags = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'];
+
+  if (enableWcagAaa) {
+    tags.push('wcag2aaa');
+  }
+
+  const htmlItems = Array.isArray(htmlContent) ? htmlContent : [htmlContent];
+  const scanData = [];
+
+  for (let i = 0; i < htmlItems.length; i++) {
+    const htmlString = htmlItems[i];
+    const dom = new JSDOM(htmlString);
+
+    // Configure axe for node environment
+    // eslint-disable-next-line no-await-in-loop
+    const axeScanResults = await axe.run(
+      dom.window.document.documentElement as unknown as Element,
+      {
+        runOnly: {
+          type: 'tag',
+          values: tags,
+        },
+        resultTypes: ['violations', 'passes', 'incomplete'],
+      },
+    );
+    
+    scanData.push({
+      axeScanResults,
+      pageUrl: htmlItems.length > 1 ? `${pageUrl}-${i + 1}` : pageUrl,
+      pageTitle: htmlItems.length > 1 ? `${pageTitle} ${i + 1}` : pageTitle,
+    });
+  }
+
+  return processAndSubmitResults(scanData, name, email, metadata);
+};
+
+export const scanPage = async (
+  pages: Page | Page[],
+  config: {
+    name: string;
+    email: string;
+    pageTitle?: string;
+    metadata?: string;
+    ruleset?: RuleFlags[];
+  },
+) => {
+  const {
+    name,
+    email,
+    pageTitle,
+    metadata = '',
+    ruleset = [RuleFlags.DEFAULT],
+  } = config;
+
+  const disableOobee = ruleset.includes(RuleFlags.DISABLE_OOBEE);
+  const enableWcagAaa = ruleset.includes(RuleFlags.ENABLE_WCAG_AAA);
+
+  const axeScript = getAxeScriptContent();
+  const oobeeFunctions = getOobeeFunctionsScript(disableOobee, enableWcagAaa);
+
+  const pagesArray = Array.isArray(pages) ? pages : [pages];
+  const scanData = [];
+
+  for (const page of pagesArray) {
+    await page.evaluate(`${axeScript}\n${oobeeFunctions}`);
+
+    // Run the scan inside the page
+    const consoleListener = (msg: any) => {
+      if (msg.type() === 'error') {
+        console.error(`[Browser Console] ${msg.text()}`);
+      }
+    };
+    page.on('console', consoleListener);
+
+    try {
+      const scanResult = await page.evaluate(async () => {
+        return window.runA11yScan();
+      });
+
+      scanData.push({
+        axeScanResults: scanResult.axeScanResults,
+        pageUrl: page.url(),
+        pageTitle: await page.title(),
+      });
+    } finally {
+      page.off('console', consoleListener);
+    }
+  }
+
+  // Allow override of page title if scanning a single page
+  if (!Array.isArray(pages) && pageTitle) {
+    scanData[0].pageTitle = pageTitle;
+  }
+
+  return processAndSubmitResults(
+    scanData,
+    name,
+    email,
+    metadata,
+  );
+};
+
+export { RuleFlags };
+