@govtechsg/oobee 0.10.20

package/src/npmIndex.ts

@@ -0,0 +1,284 @@
+import fs from 'fs';
+import path from 'path';
+import printMessage from 'print-message';
+import axe from 'axe-core';
+import { fileURLToPath } from 'url';
+import constants, { BrowserTypes } from './constants/constants.js';
+import {
+  deleteClonedProfiles,
+  getBrowserToRun,
+  getPlaywrightLaunchOptions,
+  submitForm,
+  urlWithoutAuth,
+} from './constants/common.js';
+import { createCrawleeSubFolders, filterAxeResults } from './crawlers/commonCrawlerFunc.js';
+import { createAndUpdateResultsFolders, createDetailsAndLogs } from './utils.js';
+import generateArtifacts from './mergeAxeResults.js';
+import { takeScreenshotForHTMLElements } from './screenshotFunc/htmlScreenshotFunc.js';
+import { silentLogger } from './logs.js';
+import { alertMessageOptions } from './constants/cliFunctions.js';
+
+const filename = fileURLToPath(import.meta.url);
+const dirname = path.dirname(filename);
+
+export const init = async (
+  entryUrl,
+  testLabel,
+  name = 'Your Name',
+  email = 'email@domain.com',
+  includeScreenshots = false,
+  viewportSettings = { width: 1000, height: 660 }, // cypress' default viewport settings
+  thresholds = { mustFix: undefined, goodToFix: undefined },
+  scanAboutMetadata = undefined,
+  zip = undefined,
+) => {
+  console.log('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}`;
+
+  // 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(),
+    crawlType: 'Custom',
+    requestUrl: entryUrl,
+    urlsCrawled: { ...constants.urlsCrawledObj },
+  };
+
+  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 getScripts = () => {
+    throwErrorIfTerminated();
+    const axeScript = fs.readFileSync(
+      path.join(dirname, '../node_modules/axe-core/axe.min.js'),
+      'utf-8',
+    );
+    async function runA11yScan(elementsToScan = []) {
+      axe.configure({
+        branding: {
+          application: 'oobee',
+        },
+        // Add custom img alt text check
+        checks: [
+          {
+            id: 'oobee-confusing-alt-text',
+            evaluate(node: HTMLElement) {
+              const altText = node.getAttribute('alt');
+              const confusingTexts = ['img', 'image', 'picture', 'photo', 'graphic'];
+
+              if (altText) {
+                const trimmedAltText = altText.trim().toLowerCase();
+                // Check if the alt text exactly matches one of the confusingTexts
+                if (confusingTexts.some(text => text === trimmedAltText)) {
+                  return false; // Fail the check if the alt text is confusing or not useful
+                }
+              }
+
+              return true; // Pass the check if the alt text seems appropriate
+            },
+            metadata: {
+              impact: 'serious', // Set the severity to serious
+              messages: {
+                pass: 'The image alt text is probably useful',
+                fail: "The image alt text set as 'img', 'image', 'picture', 'photo', or 'graphic' is confusing or not useful",
+              },
+            },
+          },
+        ],
+        rules: [
+          { id: 'target-size', enabled: true },
+          {
+            id: 'oobee-confusing-alt-text',
+            selector: 'img[alt]',
+            enabled: true,
+            any: ['oobee-confusing-alt-text'],
+            all: [],
+            none: [],
+            tags: ['wcag2a', 'wcag111'],
+            metadata: {
+              description: 'Ensures image alt text is clear and useful',
+              help: 'Image alt text must not be vague or unhelpful',
+              helpUrl: 'https://www.deque.com/blog/great-alt-text-introduction/',
+            },
+          },
+        ],
+      });
+      const axeScanResults = await axe.run(elementsToScan, {
+        resultTypes: ['violations', 'passes', 'incomplete'],
+      });
+      return {
+        pageUrl: window.location.href,
+        pageTitle: document.title,
+        axeScanResults,
+      };
+    }
+    return `${axeScript} ${runA11yScan.toString()}`;
+  };
+
+  const pushScanResults = async (res, metadata, elementsToClick) => {
+    throwErrorIfTerminated();
+    if (includeScreenshots) {
+      // use chrome by default
+      const { browserToRun, clonedBrowserDataDir } = getBrowserToRun(BrowserTypes.CHROME);
+      const browserContext = await constants.launcher.launchPersistentContext(
+        clonedBrowserDataDir,
+        { viewport: scanAboutMetadata.viewport, ...getPlaywrightLaunchOptions(browserToRun) },
+      );
+      const page = await browserContext.newPage();
+      await page.goto(res.pageUrl);
+      await page.waitForLoadState('networkidle');
+
+      // click on elements to reveal hidden elements so screenshots can be taken
+      elementsToClick?.forEach(async elem => {
+        try {
+          await page.locator(elem).click();
+        } catch (e) {
+          silentLogger.info(e);
+        }
+      });
+
+      res.axeScanResults.violations = await takeScreenshotForHTMLElements(
+        res.axeScanResults.violations,
+        page,
+        randomToken,
+        3000,
+      );
+      res.axeScanResults.incomplete = await takeScreenshotForHTMLElements(
+        res.axeScanResults.incomplete,
+        page,
+        randomToken,
+        3000,
+      );
+
+      await browserContext.close();
+      deleteClonedProfiles(browserToRun);
+    }
+    const pageIndex = urlsCrawled.scanned.length + 1;
+    const filteredResults = filterAxeResults(res.axeScanResults, res.pageTitle, {
+      pageIndex,
+      metadata,
+    });
+    urlsCrawled.scanned.push({
+      url: urlWithoutAuth(res.pageUrl).toString(),
+      actualUrl: 'tbd',
+      pageTitle: `${pageIndex}: ${res.pageTitle}`,
+    });
+
+    mustFixIssues += filteredResults.mustFix ? filteredResults.mustFix.totalItems : 0;
+    goodToFixIssues += filteredResults.goodToFix ? filteredResults.goodToFix.totalItems : 0;
+    await dataset.pushData(filteredResults);
+
+    // return counts for users to perform custom assertions if needed
+    return {
+      mustFix: filteredResults.mustFix ? filteredResults.mustFix.totalItems : 0,
+      goodToFix: filteredResults.goodToFix ? filteredResults.goodToFix.totalItems : 0,
+    };
+  };
+
+  const terminate = async () => {
+    throwErrorIfTerminated();
+    console.log('Stopping Oobee');
+    isInstanceTerminated = true;
+    scanDetails.endTime = new Date();
+    scanDetails.urlsCrawled = urlsCrawled;
+
+    if (urlsCrawled.scanned.length === 0) {
+      printMessage([`No pages were scanned.`], alertMessageOptions);
+    } else {
+      await createDetailsAndLogs(randomToken);
+      await createAndUpdateResultsFolders(randomToken);
+      const pagesNotScanned = [
+        ...scanDetails.urlsCrawled.error,
+        ...scanDetails.urlsCrawled.invalid,
+      ];
+      const updatedScanAboutMetadata = {
+        viewport: `${viewportSettings.width} x ${viewportSettings.height}`,
+        ...scanAboutMetadata,
+      };
+      const basicFormHTMLSnippet = await generateArtifacts(
+        randomToken,
+        scanDetails.requestUrl,
+        scanDetails.crawlType,
+        updatedScanAboutMetadata.viewport,
+        scanDetails.urlsCrawled.scanned,
+        pagesNotScanned,
+        testLabel,
+        updatedScanAboutMetadata,
+        scanDetails,
+        zip,
+      );
+
+      await submitForm(
+        BrowserTypes.CHROMIUM, // browserToRun
+        '', // userDataDirectory
+        scanDetails.requestUrl, // scannedUrl
+        null, // entryUrl
+        scanDetails.crawlType, // scanType
+        email, // email
+        name, // name
+        JSON.stringify(basicFormHTMLSnippet), // scanResultsKson
+        urlsCrawled.scanned.length, // numberOfPagesScanned
+        0,
+        0,
+        '{}',
+      );
+    }
+
+    return randomToken;
+  };
+
+  const testThresholds = () => {
+    // check against thresholds to fail tests
+    let isThresholdExceeded = false;
+    let thresholdFailMessage = 'Exceeded thresholds:\n';
+    if (mustFixThreshold !== undefined && mustFixIssues > mustFixThreshold) {
+      isThresholdExceeded = true;
+      thresholdFailMessage += `mustFix occurrences found: ${mustFixIssues} > ${mustFixThreshold}\n`;
+    }
+
+    if (goodToFixThreshold !== undefined && goodToFixIssues > goodToFixThreshold) {
+      isThresholdExceeded = true;
+      thresholdFailMessage += `goodToFix occurrences found: ${goodToFixIssues} > ${goodToFixThreshold}\n`;
+    }
+
+    // uncomment to reset counts if you do not want violations count to be cumulative across other pages
+    // mustFixIssues = 0;
+    // goodToFixIssues = 0;
+
+    if (isThresholdExceeded) {
+      terminate(); // terminate if threshold exceeded
+      throw new Error(thresholdFailMessage);
+    }
+  };
+
+  return {
+    getScripts,
+    pushScanResults,
+    terminate,
+    scanDetails,
+    randomToken,
+    testThresholds,
+  };
+};
+
+export default init;

package/src/screenshotFunc/htmlScreenshotFunc.ts

@@ -0,0 +1,411 @@
+// import { JSDOM } from "jsdom";
+import { createHash } from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { consoleLogger } from '../logs.js';
+import { Result } from 'axe-core';
+import { Page } from 'playwright';
+import { NodeResultWithScreenshot, ResultWithScreenshot } from '../crawlers/commonCrawlerFunc.js';
+
+const screenshotMap = {}; // Map of screenshot hashkey to its buffer value and screenshot path
+
+export const takeScreenshotForHTMLElements = async (
+  violations: Result[],
+  page: Page,
+  randomToken: string,
+  locatorTimeout = 2000,
+  maxScreenshots = 50,
+): Promise<ResultWithScreenshot[]> => {
+  const newViolations: ResultWithScreenshot[] = [];
+  let screenshotCount = 0;
+
+  for (const violation of violations) {
+    if (screenshotCount >= maxScreenshots) {
+      consoleLogger.warn(
+        `Skipping screenshots for ${violation.id} as maxScreenshots (${maxScreenshots}) exceeded. You can increase it by specifying a higher value when calling takeScreenshotForHTMLElements.`,
+      );
+      newViolations.push(violation);
+      continue;
+    }
+
+    const { id: rule } = violation;
+
+    // Check if rule ID is 'oobee-grading-text-contents' and skip screenshot logic
+    if (rule === 'oobee-grading-text-contents') {
+      consoleLogger.info('Skipping screenshot for rule oobee-grading-text-contents');
+      newViolations.push(violation); // Make sure it gets added
+      continue;
+    }
+
+    const newViolationNodes: NodeResultWithScreenshot[] = [];
+    for (const node of violation.nodes) {
+      const nodeWithScreenshotPath: NodeResultWithScreenshot = node;
+      const { target } = node;
+      const hasValidSelector = target.length === 1 && typeof target[0] === 'string';
+      const selector = hasValidSelector ? (target[0] as string) : null;
+      if (selector) {
+        try {
+          const locator = page.locator(selector);
+          const locators = await locator.all();
+          for (const currLocator of locators) {
+            await currLocator.scrollIntoViewIfNeeded({ timeout: locatorTimeout });
+            const isVisible = await currLocator.isVisible();
+
+            if (isVisible) {
+              const buffer = await currLocator.screenshot({ timeout: locatorTimeout });
+              const screenshotPath = getScreenshotPath(buffer, randomToken);
+              nodeWithScreenshotPath.screenshotPath = screenshotPath;
+              screenshotCount++;
+            } else {
+              consoleLogger.info(`Element at ${currLocator} is not visible`);
+            }
+
+            break; // Stop looping after finding the first visible locator
+          }
+        } catch (e) {
+          consoleLogger.info(`Unable to take element screenshot at ${selector}`);
+        }
+      }
+      newViolationNodes.push(nodeWithScreenshotPath);
+    }
+    violation.nodes = newViolationNodes;
+    newViolations.push(violation);
+  }
+  // console.log('Processed Violations (after screenshots):', JSON.stringify(newViolations, null, 2));
+  return newViolations;
+};
+
+const generateBufferHash = (buffer: Buffer) => {
+  const hash = createHash('sha256');
+  hash.update(buffer);
+  return hash.digest('hex');
+};
+
+const isSameBufferHash = (buffer: Buffer, hash: string) => {
+  const bufferHash = generateBufferHash(buffer);
+  return hash === bufferHash;
+};
+
+const getIdenticalScreenshotKey = (buffer: Buffer) => {
+  for (const hashKey in screenshotMap) {
+    const isIdentical = isSameBufferHash(buffer, hashKey);
+    if (isIdentical) return hashKey;
+  }
+  return undefined;
+};
+
+const getScreenshotPath = (buffer: Buffer, randomToken: string) => {
+  let hashKey = getIdenticalScreenshotKey(buffer);
+  // If exists identical entry in screenshot map, get its filepath
+  if (hashKey) {
+    return screenshotMap[hashKey];
+  }
+  // Create new entry in screenshot map
+  hashKey = generateBufferHash(buffer);
+  const path = generateScreenshotPath(hashKey);
+  screenshotMap[hashKey] = path;
+
+  // Save image file to local storage
+  saveImageBufferToFile(buffer, `${randomToken}/${path}`);
+
+  return path;
+};
+
+const generateScreenshotPath = (hashKey: string) => {
+  return `elemScreenshots/html/${hashKey}.jpeg`;
+};
+
+const saveImageBufferToFile = (buffer: Buffer, fileName: string) => {
+  if (!fileName) return;
+  // Find and create parent directories recursively if not exist
+  const absPath = path.resolve(fileName);
+  const dir = path.dirname(absPath);
+  fs.mkdir(dir, { recursive: true }, err => {
+    if (err) console.log('Error trying to create parent directory(s):', err);
+    // Write the image buffer to file
+    fs.writeFile(absPath, buffer, err => {
+      if (err) console.log('Error trying to write file:', err);
+    });
+  });
+};
+
+// const hasMultipleLocators = async (locator) => await locator.count() > 1;
+
+// const resolveMultipleLocators = async (page, locator, html) => {
+//     const { tag, classAttrib, hrefAttrib, textContent } = generateAttribs(html);
+
+//     const allLocators = await locator.all();
+//     // console.log('locator before: ', locator);
+//     allLocators.forEach(async currLocator => {
+//         console.log('curr locator: ', currLocator);
+//         let hrefIsExactMatch, containsTextContent;
+//         // if (hrefAttrib) hrefIsExactMatch = (await currLocator.getAttribute('href')) === hrefAttrib;
+//         if (textContent) containsTextContent = (await currLocator.innerText()).includes(textContent);
+
+//         // if (hrefAttrib && textContent) {
+//         //     if (hrefIsExactMatch && containsTextContent) {
+//         //         locator = currLocator;
+//         //         console.log('1: ', locator);
+//         //     }
+//         // } else if (hrefAttrib) {
+//         //     if (hrefIsExactMatch) {
+//         //         locator = currLocator;
+//         //         console.log('2: ', locator);
+//         //     }
+//         // } else
+
+//         if (textContent) {
+//             if (containsTextContent) {
+//                 locator = currLocator;
+//                 console.log('3: ', locator);
+//             }
+//         } else {
+//             locator = null;
+//         }
+//     })
+//     console.log('final locator: ', locator);
+//     return locator;
+//  }
+
+// const generateAttribs = (html) => {
+//     const processedHTMLString = html.replaceAll('\n', '');
+//     const tagNamesRegex =  /(?<=[<])\s*([a-zA-Z][^\s>/]*)\b/g;
+//     const tag = processedHTMLString.match(tagNamesRegex)[0];
+
+//     const dom = new JSDOM(processedHTMLString);
+//     const elem = dom.window.document.querySelector(tag);
+
+//     const textContent = elem.textContent.trim();
+//     const classAttrib = elem.getAttribute('class')?.trim();
+//     const hrefAttrib = (tag === 'a') ? elem.getAttribute('href') : null;
+//     console.log('text content: ', textContent);
+
+//     return {
+//         tag,
+//         ...(classAttrib && {classAttrib}),
+//         ...(hrefAttrib && {hrefAttrib}),
+//         ...(textContent && {textContent})
+//     }
+// }
+
+// export const takeScreenshotForHTMLElements = async (screenshotData, storagePath, browserToRun) => {
+//     const screenshotDir = `${storagePath}/screenshots`;
+//     let screenshotItems = [];
+//     let randomToken = `cloned-${Date.now()}`;
+//     const clonedDir = getClonedProfilesWithRandomToken(browserToRun, randomToken);
+//     const browser = await constants.launcher.launchPersistentContext(
+//         clonedDir,
+//         {
+//             headless: false,
+//             ...getPlaywrightLaunchOptions(browserToRun)
+//         }
+//     );
+
+//     for (const item of screenshotData) {
+//           const domain = item.url.replaceAll("https://", '').replaceAll('/', '_');
+//           item.htmlItems = generateSelectors(item.htmlItems);
+//           const page = await browser.newPage();
+//           await page.goto(item.url);
+//           let htmlItemsWithScreenshotPath = [];
+//           for (const htmlItem of item.htmlItems) {
+//               const { rule, category, selector } = htmlItem;
+//               const locator = await getLocators(page, selector);
+//               const screenshotFilePath = `${domain}/${category}/${rule}/${selector.tag}-${htmlItemsWithScreenshotPath.length}.png`;
+//               if (locator) {
+//                   await locator.screenshot({ path: `${screenshotDir}/${screenshotFilePath}` });
+//                   htmlItem.screenshotPath = `screenshots/${screenshotFilePath}`;
+//               }
+//               delete htmlItem.selector;
+//               htmlItemsWithScreenshotPath.push(htmlItem);
+//           }
+//           screenshotItems.push({url: item.url, htmlItems: htmlItemsWithScreenshotPath});
+//           await page.close();
+//       }
+//       await browser.close();
+//       deleteClonedProfiles(browserToRun)
+//       return screenshotItems;
+//   }
+
+//   export const processScreenshotData = (allIssues) => {
+//     const scannedUrls = allIssues.pagesScanned.map(page => page.url);
+//     const screenshotData = scannedUrls.map(scannedUrl => {
+//         let htmlItems = [];
+//         ['mustFix', 'goodToFix'].map((category) => {
+//             const ruleItems = allIssues.items[category].rules;
+//             ruleItems.map(ruleItem => {
+//                 const { rule, pagesAffected } = ruleItem;
+//                 pagesAffected.map(affectedPage => {
+//                     const { url, items } = affectedPage;
+//                     if (scannedUrl === url) {
+//                         items.forEach(item => {if (item.html) htmlItems.push({html: item.html, rule, category})});
+//                     }
+//                 })
+//             })
+//         })
+//         return {url: scannedUrl, htmlItems};
+//     })
+//     return screenshotData;
+// }
+
+// export const getScreenshotPaths = (screenshotItems, allIssues) => {
+//     screenshotItems.forEach(screenshotItem => {
+//         const { url: ssUrl, htmlItems: ssHtmlItems } = screenshotItem;
+//         ssHtmlItems.map(ssHtmlItem => {
+//           const {
+//             category: ssCategory,
+//             rule: ssRule,
+//             html: ssHtml,
+//             screenshotPath: ssPath
+//           } = ssHtmlItem;
+//           allIssues.items[ssCategory].rules = allIssues.items[ssCategory].rules
+//             .map(ruleItem => {
+//               const { rule, pagesAffected } = ruleItem;
+//                 if (rule === ssRule) {
+//                   ruleItem.pagesAffected = pagesAffected.map(affectedPage => {
+//                     const { url, items } = affectedPage;
+//                     if (ssUrl === url) {
+//                       affectedPage.items = items.map(htmlItem => {
+//                         const { html } = htmlItem;
+//                         if (ssHtml === html) htmlItem.screenshotPath = ssPath;
+//                         return htmlItem;
+//                       })
+//                     }
+//                     return affectedPage;
+//                   })
+//                 }
+//                 return ruleItem;
+//             })
+//         })
+//     });
+// }
+
+// const generateSelectors = (htmlItems) => {
+//     const htmlItemsWithSelectors = htmlItems.map((htmlItem) => {
+//         const { html } = htmlItem;
+//         const processedHTMLString = html.replaceAll('\n', '');
+//         const tagnameRegex =  /(?<=[<])\s*([a-zA-Z][^\s>/]*)\b/g;
+//         const tagNames = processedHTMLString.match(tagnameRegex);
+
+//         const dom = new JSDOM(processedHTMLString);
+//         const tag = tagNames[0]
+//         const elem = dom.window.document.querySelector(tag);
+
+//         const classAttrib = elem.getAttribute('class')?.trim();
+//         const idAttrib = elem.getAttribute('id');
+//         const titleAttrib = elem.getAttribute('title');
+//         const placeholderAttrib = elem.getAttribute('placeholder');
+//         const altAttrib = (tag === 'img') ? elem.getAttribute('alt') : null;
+//         const hrefAttrib = (tag === 'a') ? elem.getAttribute('href') : null;
+
+//         let children;
+//         if (tagNames.length > 1) {
+//             const childrenHTMLItems = Array.from(elem.children).map(child => {
+//                 return {
+//                     html: child.outerHTML,
+//                     rule: htmlItem.rule,
+//                     category: htmlItem.category
+//                 }
+//             });
+//             children = generateSelectors(childrenHTMLItems);
+//         }
+
+//         let textContent = elem.textContent.trim();
+//         let allTextContents = [];
+//         children?.map((child) => {
+//             if (child?.selector.allTextContents) allTextContents = [...allTextContents, ...child.selector.allTextContents]
+//         })
+
+//         if (allTextContents.includes(textContent)) {
+//             textContent = null;
+//         } else {
+//             if (textContent) allTextContents = [textContent, ...allTextContents];
+//         }
+
+//         const selector = {
+//             tag,
+//             processedHTMLString,
+//             ...(textContent && {textContent}),
+//             ...(allTextContents.length > 0 && {allTextContents}),
+//             ...(classAttrib && {classAttrib}),
+//             ...(idAttrib && {idAttrib}),
+//             ...(titleAttrib && {titleAttrib}),
+//             ...(placeholderAttrib && {placeholderAttrib}),
+//             ...(altAttrib && {altAttrib}),
+//             ...(hrefAttrib && {hrefAttrib}),
+//             ...(children && {children}),
+//         }
+
+//         htmlItem.selector = selector;
+//         return htmlItem;
+//     })
+//     return htmlItemsWithSelectors;
+// }
+
+// const generateInitialLocator = (page, selector) => {
+//     const {
+//         tag,
+//         textContent,
+//         classAttrib,
+//         idAttrib,
+//         titleAttrib,
+//         placeholderAttrib,
+//         altAttrib,
+//         children
+//     } = selector;
+
+//     let locator = page.locator(tag);
+//     if (classAttrib) {
+//         const classSelector = classAttrib.replaceAll(/\s+/g, '.').replace(/^/, '.').replaceAll(':', '\\:').replaceAll('(', '\\(').replaceAll(')', '\\)');
+//         locator = locator.and(page.locator(classSelector))
+//     }
+//     if (idAttrib) locator = locator.and(page.locator(`#${idAttrib}`));
+//     if (textContent) locator = locator.and(page.getByText(textContent));
+//     if (titleAttrib) locator = locator.and(page.getByTitle(titleAttrib));
+//     if (placeholderAttrib) locator = locator.and(page.getByPlaceHolder(placeholderAttrib));
+//     if (altAttrib) locator = locator.and(page.getByAltText(altAttrib));
+
+//     if (children) {
+//         let currLocator = locator;
+//         for (const child of children) {
+//             const childLocator = generateInitialLocator(page, child.selector);
+//             locator = locator.and(currLocator.filter({ has: childLocator })); // figure this out tmr!
+//         }
+//     }
+//     return locator;
+// }
+
+// const resolveLocators = async (locator, classAttrib, hrefAttrib) => {
+//     const locatorCount = await locator.count();
+//     if (locatorCount > 1) {
+//         let locators = [];
+//         const allLocators = await locator.all();
+//         for (let nth = 0; nth < locatorCount; nth++) {
+//             const currLocator = allLocators[nth];
+//             const isVisible = await currLocator.isVisible();
+//             if (isVisible) {
+//                 let classIsExactMatch, hrefIsExactMatch;
+//                 if (classAttrib) classIsExactMatch = (await currLocator.getAttribute('class')) === classAttrib;
+//                 if (hrefAttrib) hrefIsExactMatch = (await currLocator.getAttribute('href')) === hrefAttrib;
+
+//                 if (classAttrib && hrefAttrib) {
+//                     if (classIsExactMatch && hrefIsExactMatch) locators.push(currLocator);
+//                 } else if (classAttrib) {
+//                     if (classIsExactMatch) locators.push(currLocator);
+//                 } else if (hrefAttrib) {
+//                     if (hrefIsExactMatch) locators.push(currLocator);
+//                 } else {
+//                     locators.push(currLocator);
+//                 }
+//             }
+//         }
+//         return locators.length === 1 ? locators[0] : null;
+//     } else {
+//         return locator;
+//     }
+// }
+
+// const getLocators = async (page, selector) => {
+//     const locator = generateInitialLocator(page, selector);
+//     const locators = await resolveLocators(locator, selector.classAttrib, selector.hrefAttrib);
+//     return locators;
+// }