@govtechsg/oobee 0.10.76 → 0.10.78-alpha1

package/examples/oobee-cypress-integration-js/cypress/support/e2e.js

@@ -55,12 +55,42 @@ Cypress.Commands.add("runOobeeA11yScan", (items = {}) => {
           elementsToScan,
           gradingReadabilityFlag,
         );
-        cy.task("pushOobeeA11yScanResults", {
-          res,
-          metadata,
-          elementsToClick,
-        }).then((count) => {
-          return count;
+
+        const processNodes = (nodes) => {
+            if (!nodes) return;
+            cy.wrap(nodes).each((node, index) => {
+               if (node.target && node.target.length > 0) {
+                   const selector = node.target[0];
+                   // Generate a unique filename
+                   const filename = `oobee-screenshot-${Date.now()}-${Math.floor(Math.random() * 1000)}-${index}.png`;
+                   
+                   // Check existence to prevent failure, then screenshot
+                   cy.get("body").then($body => {
+                       if ($body.find(selector).length) {
+                           // We use capture: 'viewport' to be safe and overwrite true
+                           cy.get(selector).first().scrollIntoView().screenshot(filename.replace('.png', ''), { capture: 'viewport', overwrite: true });
+                           node.screenshotFilename = filename;
+                       }
+                   });
+               }
+            });
+        };
+
+        const violations = res.axeScanResults.violations;
+        const incomplete = res.axeScanResults.incomplete;
+
+        cy.wrap(violations).each((v) => processNodes(v.nodes));
+        cy.wrap(incomplete).each((v) => processNodes(v.nodes));
+
+        // Ensure screenshots are done before pushing results
+        cy.then(() => {
+            cy.task("pushOobeeA11yScanResults", {
+              res,
+              metadata,
+              elementsToClick,
+            }).then((count) => {
+              return count;
+            });
         });
       },
     );

package/examples/oobee-cypress-integration-js/cypress.config.js

@@ -1,5 +1,7 @@
 import { defineConfig } from "cypress";
 import oobeeA11yInit from "@govtechsg/oobee";
+import * as fs from 'fs';
+import * as path from 'path';
 
 // viewport used in tests to optimise screenshots
 const viewportSettings = { width: 1920, height: 1040 };
@@ -44,7 +46,49 @@ export default defineConfig({
           return oobeeA11y.gradeReadability(sentences);
         },
         async pushOobeeA11yScanResults({ res, metadata, elementsToClick }) {
-          return await oobeeA11y.pushScanResults(res, metadata, elementsToClick);
+          if (oobeeA11y.scanDetails.isIncludeScreenshots) {
+              const moveScreenshots = (items) => {
+                  if (!items) return;
+                  items.forEach(item => {
+                      item.nodes.forEach((node) => {
+                          if (node.screenshotFilename) {
+                              const searchDir = 'cypress/screenshots';
+                              
+                              const findFile = (dir, name) => {
+                                   if (!fs.existsSync(dir)) return null;
+                                   const files = fs.readdirSync(dir);
+                                   for (const file of files) {
+                                       const filePath = path.join(dir, file);
+                                       if (fs.statSync(filePath).isDirectory()) {
+                                           const found = findFile(filePath, name);
+                                           if (found) return found;
+                                       } else if (file === name) {
+                                           return filePath;
+                                       }
+                                   }
+                                   return null;
+                              }
+
+                              const srcPath = findFile(searchDir, node.screenshotFilename);
+                              if (srcPath) {
+                                  const destDir = `results/${oobeeA11y.randomToken}/screenshots`;
+                                  if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+                                  const destPath = path.join(destDir, node.screenshotFilename);
+                                  fs.copyFileSync(srcPath, destPath);
+                                  // Set screenshot path for Oobee report
+                                  node.screenshotPath = node.screenshotFilename; 
+                              }
+                          }
+                      })
+                  })
+              };
+              
+              moveScreenshots(res.axeScanResults.violations);
+              moveScreenshots(res.axeScanResults.incomplete);
+          }
+
+          // Pass disableScreenshots=true to avoid opening a new Playwright browser
+          return await oobeeA11y.pushScanResults(res, metadata, elementsToClick, undefined, true);
         },
         returnResultsDir() {
           return `results/${oobeeA11y.randomToken}_${oobeeA11y.scanDetails.urlsCrawled.scanned.length}pages/report.html`;

package/examples/oobee-cypress-integration-ts/cypress.config.ts

@@ -1,5 +1,7 @@
 import { defineConfig } from "cypress";
 import oobeeA11yInit from "@govtechsg/oobee";
+import * as fs from 'fs';
+import * as path from 'path';
 
 interface ViewportSettings {
     width: number;
@@ -71,7 +73,51 @@ export default defineConfig({
                 },
                 async pushOobeeA11yScanResults({res, metadata, elementsToClick}: { res: any, metadata: any, elementsToClick: any[] }): Promise<{ mustFix: number, goodToFix: number }> {
                     const instance = await initOobeeIfNeeded();
-                    return await instance.pushScanResults(res, metadata, elementsToClick);
+
+                    if (instance.scanDetails.isIncludeScreenshots) {
+                        const moveScreenshots = (items: any[]) => {
+                            if (!items) return;
+                            items.forEach(item => {
+                                item.nodes.forEach((node: any) => {
+                                    if (node.screenshotFilename) {
+                                        const searchDir = 'cypress/screenshots';
+                                        
+                                        const findFile = (dir: string, name: string): string | null => {
+                                             if (!fs.existsSync(dir)) return null;
+                                             const files = fs.readdirSync(dir);
+                                             for (const file of files) {
+                                                 const filePath = path.join(dir, file);
+                                                 if (fs.statSync(filePath).isDirectory()) {
+                                                     const found = findFile(filePath, name);
+                                                     if (found) return found;
+                                                 } else if (file === name) {
+                                                     return filePath;
+                                                 }
+                                             }
+                                             return null;
+                                        }
+
+                                        const srcPath = findFile(searchDir, node.screenshotFilename);
+                                        if (srcPath) {
+                                            const destDir = `results/${instance.randomToken}/screenshots`;
+                                            if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+                                            const destPath = path.join(destDir, node.screenshotFilename);
+                                            fs.copyFileSync(srcPath, destPath);
+                                            // Set screenshot path for Oobee report
+                                            node.screenshotPath = node.screenshotFilename; 
+                                        }
+                                    }
+                                })
+                            })
+                        };
+                        
+                        moveScreenshots(res.axeScanResults.violations);
+                        moveScreenshots(res.axeScanResults.incomplete);
+                    }
+
+                    // Cypress task runs in Node.js and does not have access to the browser Page object
+                    // Pass disableScreenshots=true to avoid opening a new Playwright browser
+                    return await instance.pushScanResults(res, metadata, elementsToClick, undefined, true);
                 },
                 async returnResultsDir(): Promise<string> {
                     const instance = await initOobeeIfNeeded();

package/examples/oobee-cypress-integration-ts/src/cypress/support/e2e.ts

@@ -55,12 +55,42 @@ Cypress.Commands.add("runOobeeA11yScan", (items: OobeeScanOptions = {}) => {
                     elementsToScan,
                     gradingReadabilityFlag,
                 );
-                cy.task("pushOobeeA11yScanResults", {
-                    res,
-                    metadata,
-                    elementsToClick,
-                }).then((count) => {
-                     return count;
+
+                const processNodes = (nodes: any[]) => {
+                    if (!nodes) return;
+                    cy.wrap(nodes).each((node: any, index: number) => {
+                       if (node.target && node.target.length > 0) {
+                           const selector = node.target[0];
+                           // Generate a unique filename
+                           const filename = `oobee-screenshot-${Date.now()}-${Math.floor(Math.random() * 1000)}-${index}.png`;
+                           
+                           // Check existence to prevent failure, then screenshot
+                           cy.get("body").then($body => {
+                               if ($body.find(selector).length) {
+                                   // We use capture: 'viewport' to be safe and overwrite true
+                                   cy.get(selector).first().scrollIntoView().screenshot(filename.replace('.png', ''), { capture: 'viewport', overwrite: true });
+                                   node.screenshotFilename = filename;
+                               }
+                           });
+                       }
+                    });
+                };
+
+                const violations = res.axeScanResults.violations;
+                const incomplete = res.axeScanResults.incomplete;
+
+                cy.wrap(violations).each((v: any) => processNodes(v.nodes));
+                cy.wrap(incomplete).each((v: any) => processNodes(v.nodes));
+                
+                // Ensure screenshots are done before pushing results
+                cy.then(() => {
+                    cy.task("pushOobeeA11yScanResults", {
+                        res,
+                        metadata,
+                        elementsToClick,
+                    }).then((count) => {
+                        return count;
+                    });
                 });
             },
         );

package/examples/oobee-playwright-integration-js/oobee-playwright-demo.js

@@ -40,7 +40,8 @@ const oobeeA11y = await oobeeA11yInit({
       async ({ elementsToScan, gradingReadabilityFlag }) => await runA11yScan(elementsToScan, gradingReadabilityFlag),
       { elementsToScan, gradingReadabilityFlag },
     );
-    await oobeeA11y.pushScanResults(scanRes);
+    // Pass page object to allow screenshot reuse
+    await oobeeA11y.pushScanResults(scanRes, undefined, undefined, page);
     oobeeA11y.testThresholds(); // test the accumulated number of issue occurrences against specified thresholds. If exceed, terminate oobeeA11y instance.
   };
 

package/examples/oobee-playwright-integration-ts/src/oobee-playwright-demo.ts

@@ -59,7 +59,8 @@ const oobeeA11y = await oobeeA11yInit({
       async ({ elementsToScan, gradingReadabilityFlag }) => await runA11yScan(elementsToScan, gradingReadabilityFlag),
       { elementsToScan, gradingReadabilityFlag },
     );
-    await oobeeA11y.pushScanResults(scanRes);
+    // Pass page object to allow screenshot reuse
+    await oobeeA11y.pushScanResults(scanRes, undefined, undefined, page);
     oobeeA11y.testThresholds(); // test the accumulated number of issue occurrences against specified thresholds. If exceed, terminate oobeeA11y instance.
   };
 

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,9 +1,12 @@
 {
   "name": "@govtechsg/oobee",
   "main": "dist/npmIndex.js",
-  "version": "0.10.76",
+  "version": "0.10.78-alpha1",
   "type": "module",
   "author": "Government Technology Agency <info@tech.gov.sg>",
+  "bin": {
+    "oobee": "./dist/cli.js"
+  },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.948.0",
     "@json2csv/node": "^7.0.3",
@@ -58,7 +61,7 @@
     "@types/which": "^3.0.4",
     "@types/xml2js": "^0.4.14",
     "browserify-zlib": "^0.2.0",
-    "eslint": "^8.57.0",
+    "eslint": "^9.26.0",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-prettier": "^8.6.0",
     "eslint-plugin-import": "^2.27.4",
@@ -76,7 +79,10 @@
     "micromatch": "github:micromatch/micromatch.git#4.0.8",
     "brace-expansion": "^1.1.12",
     "tmp": "0.2.4",
-    "tar": "^7.5.6"
+    "tar": "^7.5.6",
+    "eslint-config-airbnb-base": {
+      "eslint": "^9.26.0"
+    }
   },
   "optionalDependencies": {
     "@napi-rs/canvas-darwin-arm64": "^0.1.53",

package/src/constants/common.ts

@@ -1333,14 +1333,14 @@ const cloneEdgeProfileCookieFiles = (options: GlobOptionsWithFileTypesFalse, des
   if (os.platform() === 'win32') {
     profileCookiesDir = globSync('**/Network/Cookies', {
       ...options,
-      ignore: 'oobee/**',
+      ignore: 'oobee*/**',
     });
     profileNamesRegex = /User Data\\(.*?)\\Network/;
   } else if (os.platform() === 'darwin') {
     // Ignores copying cookies from the oobee directory if it exists
     profileCookiesDir = globSync('**/Cookies', {
       ...options,
-      ignore: 'oobee/**',
+      ignore: 'oobee*/**',
     });
     profileNamesRegex = /Microsoft Edge\/(.*?)\/Cookies/;
   }

package/src/constants/constants.ts

@@ -1,5 +1,6 @@
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
 import fs from 'fs-extra';
 import { globSync } from 'glob';
 import which from 'which';
@@ -13,6 +14,7 @@ import { PageInfo } from '../mergeAxeResults.js';
 
 const filename = fileURLToPath(import.meta.url);
 const dirname = path.dirname(filename);
+const require = createRequire(import.meta.url);
 
 const maxRequestsPerCrawl = 100;
 
@@ -216,7 +218,7 @@ export const getExecutablePath = function (dir: string, file: string): string {
 export const basicAuthRegex = /^.*\/\/.*:.*@.*$/i;
 
 // for crawlers
-export const axeScript = path.join(dirname, '../../node_modules/axe-core/axe.min.js');
+export const axeScript = require.resolve('axe-core/axe.min.js');
 export class UrlsCrawled {
   siteName: string;
   toScan: string[] = [];

package/src/crawlers/crawlDomain.ts

@@ -151,6 +151,7 @@ const crawlDomain = async ({
             req.skipNavigation = true;
           }
           if (isDisallowedInRobotsTxt(req.url)) return null;
+          if (isBlacklisted(req.url, blacklistedPatterns)) return null;
           if (isUrlPdf(req.url)) {
             // playwright headless mode does not support navigation to pdf document
             req.skipNavigation = true;

package/src/crawlers/runCustom.ts

@@ -84,7 +84,6 @@ const runCustom = async (
       headless: false,
       channel: 'chrome',
       // bypassCSP: true,
-      devtools: DEBUG,
     });
 
     const context = await browser.newContext({

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,