@axe-core/webdriverjs 4.3.3-alpha.224 → 4.3.3-alpha.228

package/README.md

@@ -6,13 +6,25 @@ Previous versions of this program were maintained at [dequelabs/axe-webdriverjs]
 
 ## Getting Started
 
-Install [Node.js](https://docs.npmjs.com/getting-started/installing-node) if you haven't already. For running axe-webdriverjs tests read more about [setting up your environment](CONTRIBUTING.md).
+Install [Node.js](https://docs.npmjs.com/getting-started/installing-node) if you haven't already.
 
 > Download and install any necessary browser drivers on your machine's PATH. [More on Webdriver setup](https://www.selenium.dev/documentation/en/webdriver/).
 
 Install Selenium Webdriver: `npm install selenium-webdriver --no-save`
 
-Install @axe-core/webdriverjs and its dependencies: `npm install @axe-core/webdriverjs`
+Install @axe-core/webdriverjs and its dependencies:
+
+NPM:
+
+```console
+npm install @axe-core/webdriverjs
+```
+
+Yarn:
+
+```console
+yarn add @axe-core/webdriverjs
+```
 
 ## Usage
 
@@ -162,3 +174,13 @@ const axe = new AxeBuilder(driver).setLegacyMode();
 const result = await axe.analyze();
 axe.setLegacyMode(false); // Disables legacy mode
 ```
+
+### WebdriverJS Example
+
+We have created an example [test suite](https://github.com/dequelabs/axe-core-npm/tree/develop/packages/webdriverjs/tests/examples/webdriverjs-example.ts) showcasing the functionality of axe-core WebdriverJS.
+
+To run the test:
+
+- Navigate to: `/webdriverjs/tests/example`
+- Install node modules: `npm install`
+- Run tests: `npm test`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axe-core/webdriverjs",
-  "version": "4.3.3-alpha.224+14e5125",
+  "version": "4.3.3-alpha.228+0e566c2",
   "description": "Provides a method to inject and analyze web pages using axe",
   "contributors": [
     {
@@ -27,6 +27,9 @@
       "name": "Michael Siek (me@michaelsiek.com)"
     }
   ],
+  "files": [
+    "/dist"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/dequelabs/axe-core-npm.git"
@@ -105,5 +108,5 @@
     "functions": 85,
     "lines": 85
   },
-  "gitHead": "14e512551506a333b0249049c3c08c605b2026c3"
+  "gitHead": "0e566c246a4a3ab0e5b7b129fbf7006bb67aa7b6"
 }

package/.eslintrc.js

@@ -1,13 +0,0 @@
-module.exports = {
-  overrides: [
-    {
-      files: 'src/test/**/*.ts',
-      env: {
-        mocha: true
-      },
-      rules: {
-        '@typescript-eslint/no-var-requires': 'off'
-      }
-    }
-  ]
-};

package/error-handling.md

@@ -1,52 +0,0 @@
-# Error Handling
-
-## Table of Content
-
-1. [Having an Out-of-date Driver](#having-an-out-of-date-driver)
-2. [Having Popup blockers enabled](#having-popup-blockers-enabled)
-3. [AxeBuilder.setLegacyMode(legacy: boolean)](#axebuildersetlegacymodelegacy-boolean)
-
-Version 4.3.0 and above of the axe-core integrations use a new technique when calling `AxeBuilder.analyze()` which opens a new window at the end of a run. Many of the issues outlined in this document address common problems with this technique and their potential solutions.
-
-### Having an Out-of-date Driver
-
-A common problem is having an out-of-date driver. To fix this issue make sure that your local install of [geckodriver](https://github.com/mozilla/geckodriver/releases) or [chromedriver](https://chromedriver.chromium.org/downloads) is up-to-date.
-
-An example error message for this problem will include a message about `switchToWindow`.
-
-Example:
-
-```console
-(node:17566) UnhandledPromiseRejectionWarning: Error: Malformed type for "handle" parameter of command switchToWindow
-Expected: string
-Actual: undefined
-```
-
-### Having Popup blockers enabled
-
-Popup blockers prevent us from opening the new window when calling `AxeBuilder.analyze()`. The default configuration for most automation testing libraries should allow popups. Please make sure that you do not explicitly enable popup blockers which may cause an issue while running the tests.
-
-### AxeBuilder.setLegacyMode(legacy: boolean)
-
-If for some reason you are unable to run the new `AxeBuilder.analyze` technique without errors, axe provides a new chainable method that allows you to run the legacy version of `AxeBuilder.analyze`. When using this method axe excludes accessibility issues that may occur in cross-domain frames and iframes.
-
-**Please Note:** `AxeBuilder.setLegacyMode` is deprecated and will be removed in v5.0. Please report any errors you may have while running `AxeBuilder.analyze` so that they can be fixed before the legacy version is removed.
-
-#### Example:
-
-```js
-const AxeBuilder = require('@axe-core/webdriverjs');
-const WebDriver = require('selenium-webdriver');
-(async () => {
-  const driver = new WebDriver.Builder().forBrowser('chrome').build();
-  await driver.get('https://dequeuniversity.com/demo/mars/');
-  const results = await new AxeBuilder(driver, null, {
-    noSandbox: true
-  })
-    // enables legacy mode
-    .setLegacyMode()
-    .analyze();
-  console.log(results);
-  await driver.quit();
-})();
-```

package/example-with-callback.js

@@ -1,15 +0,0 @@
-const AxeBuilder = require('@axe-core/webdriverjs');
-const WebDriver = require('selenium-webdriver');
-
-const driver = new WebDriver.Builder().forBrowser('chrome').build();
-
-driver.get('https://html5-sandbox.glitch.me/').then(() => {
-  const axe = new AxeBuilder(driver, null, { noSandbox: true });
-  axe.analyze(async (err, results) => {
-    if (err) {
-      // Handle error somehow
-    }
-    console.log(results);
-    await driver.quit();
-  });
-});

package/example.js

@@ -1,13 +0,0 @@
-const AxeBuilder = require('@axe-core/webdriverjs');
-const WebDriver = require('selenium-webdriver');
-
-// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-(async () => {
-  const driver = new WebDriver.Builder().forBrowser('chrome').build();
-  await driver.get('https://html5-sandbox.glitch.me/');
-  const results = await new AxeBuilder(driver, null, {
-    noSandbox: true
-  }).analyze();
-  console.log(results);
-  await driver.quit();
-})();

package/src/axe-injector.ts

@@ -1,191 +0,0 @@
-import type { WebDriver, WebElement } from 'selenium-webdriver';
-import { error } from 'selenium-webdriver';
-import { source } from 'axe-core';
-import type { AxeInjectorParams, BuilderOptions } from './types';
-const { StaleElementReferenceError } = error;
-
-export default class AxeInjectorLegacy {
-  private driver: WebDriver;
-  private axeSource: string;
-  private options: BuilderOptions;
-  private config: string;
-  private didLogError: boolean;
-  constructor({
-    driver,
-    axeSource,
-    builderOptions,
-    config
-  }: AxeInjectorParams) {
-    this.driver = driver;
-    this.axeSource = axeSource || source;
-    this.config = config ? JSON.stringify(config) : '';
-    this.options = builderOptions || {};
-    this.didLogError = false;
-
-    this.options.noSandbox =
-      typeof this.options.noSandbox === 'boolean'
-        ? this.options.noSandbox
-        : false;
-
-    this.options.logIframeErrors =
-      typeof this.options.logIframeErrors === 'boolean'
-        ? this.options.logIframeErrors
-        : false;
-  }
-
-  /**
-   * Checks to make sure that the error thrown was not a stale iframe
-   * @param {Error} error
-   * @returns {void}
-   */
-
-  private errorHandler(err: Error): void {
-    // We've already "warned" the user. No need to do it again (mostly for backwards compatibility)
-    if (this.didLogError) {
-      return;
-    }
-
-    this.didLogError = true;
-    let msg;
-    if (err instanceof StaleElementReferenceError) {
-      msg =
-        'Tried to inject into a removed iframe. This will not affect the analysis of the rest of the page but you might want to ensure the page has finished updating before starting the analysis.';
-    } else {
-      msg = 'Failed to inject axe-core into one of the iframes!';
-    }
-
-    if (this.options.logIframeErrors) {
-      console.error(msg);
-      return;
-    }
-
-    throw new Error(msg);
-  }
-
-  /**
-   * Get axe-core source and configurations
-   * @returns {String}
-   */
-
-  private get script(): string {
-    return `
-    ${this.axeSource}
-    ${this.config ? `axe.configure(${this.config})` : ''}
-    axe.configure({
-      branding: { application: 'webdriverjs' }
-    })
-    `;
-  }
-
-  /**
-   * Removes the `sandbox` attribute from iFrames
-   * @returns {Promise<void>}
-   */
-
-  private async sandboxBuster(): Promise<void> {
-    // outer promise needed because `executeAsyncScript`
-    // does not return a "real promise" (ManagedPromise)
-    // and we want to await it.
-    return new Promise((resolve, reject) => {
-      /* eslint-disable no-undef */
-      this.driver
-        // https://github.com/vercel/pkg/issues/676
-        // we need to pass a string vs a function so we manually stringified the function
-        .executeAsyncScript(
-          `
-          var callback = arguments[arguments.length - 1];
-          var iframes = Array.from(
-            document.querySelectorAll('iframe[sandbox]')
-          );
-          var removeSandboxAttr = clone => attr => {
-            if (attr.name === 'sandbox') return;
-            clone.setAttribute(attr.name, attr.value);
-          };
-          var replaceSandboxedIframe = iframe => {
-            var clone = document.createElement('iframe');
-            var promise = new Promise(
-              iframeLoaded => (clone.onload = iframeLoaded)
-            );
-            Array.from(iframe.attributes).forEach(removeSandboxAttr(clone));
-            iframe.parentElement.replaceChild(clone, iframe);
-            return promise;
-          };
-          Promise.all(iframes.map(replaceSandboxedIframe)).then(callback);
-        `
-        )
-        // resolve the outer promise
-        .then(() => resolve())
-        .catch(e => reject(e));
-    });
-  }
-
-  /**
-   * Injects into the provided `frame` and its child `frames`
-   * @param {WebElement[]} framePath
-   * @returns {Promise<void>}
-   */
-
-  private async handleFrame(framePath: WebElement[]): Promise<void> {
-    await this.driver.switchTo().defaultContent();
-
-    for (const frame of framePath) {
-      await this.driver.switchTo().frame(frame);
-    }
-    if (this.options.noSandbox) {
-      await this.sandboxBuster();
-    }
-
-    await this.driver.executeScript(this.script);
-
-    const ifs = await this.driver.findElements({ tagName: 'iframe' });
-    const fs = await this.driver.findElements({ tagName: 'frame' });
-    const frames = ifs.concat(fs);
-
-    for (const childFrames of frames) {
-      framePath.push(childFrames);
-      try {
-        await this.handleFrame(framePath);
-      } catch (error) {
-        this.errorHandler(error as Error);
-      } finally {
-        framePath.pop();
-      }
-    }
-  }
-
-  /**
-   * Injects into all frames
-   * @returns {Promise<void>}
-   */
-  public async injectIntoAllFrames(): Promise<void> {
-    // Ensure we're "starting" our loop at the top-most frame
-    await this.driver.switchTo().defaultContent();
-
-    // By default we do not remove the sandbox attr from iframe unless user specifies
-    if (this.options.noSandbox) {
-      // reinject any sandboxed iframes without the sandbox attribute so we can scan
-      await this.sandboxBuster();
-    }
-
-    // Inject the script into the top-level
-    // XXX: if this `executeScript` fails, we *want* to error, as we cannot run axe-core.
-    await this.driver.executeScript(this.script);
-
-    // Get all of <iframe>s and <frame>s at this level
-    const ifs = await this.driver.findElements({ tagName: 'iframe' });
-    const fs = await this.driver.findElements({ tagName: 'frame' });
-    const frames = ifs.concat(fs);
-
-    // Inject the script into all child frames. Handle errors to ensure we don't stop execution if we fail to inject.
-    for (const childFrame of frames) {
-      try {
-        await this.handleFrame([childFrame]);
-      } catch (err) {
-        this.errorHandler(err as Error);
-      }
-    }
-
-    // Move back to the top-most frame
-    return this.driver.switchTo().defaultContent();
-  }
-}

package/src/browser.ts

@@ -1,142 +0,0 @@
-import {
-  AxeResults,
-  ContextObject,
-  FrameContext,
-  RunOptions,
-  Spec,
-  PartialResult
-} from 'axe-core';
-import { WebDriver, WebElement } from 'selenium-webdriver';
-
-type FrameContextWeb = FrameContext & {
-  frame: WebElement;
-  href: string;
-};
-
-// https://github.com/vercel/pkg/issues/676
-// we need to pass a string vs a function so we manually stringified the function
-// There are no try/catch blocks needed in these scripts. If an error occurs
-// Selenium pass them onto the catch block.
-
-export function axeSourceInject(
-  driver: WebDriver,
-  axeSource: string,
-  config: Spec | null
-): Promise<{ runPartialSupported: boolean }> {
-  return promisify(
-    driver.executeScript<{ runPartialSupported: boolean }>(`
-      ${axeSource};
-      window.axe.configure({
-        branding: { application: 'webdriverjs' }
-      });
-      var config = ${JSON.stringify(config)};
-      if (config) {
-        window.axe.configure(config);
-      }
-      var runPartial = typeof window.axe.runPartial === 'function';
-      return { runPartialSupported: runPartial };
-    `)
-  );
-}
-
-export function axeRunPartial(
-  driver: WebDriver,
-  context: ContextObject,
-  options: RunOptions
-): Promise<string> {
-  return promisify(
-    driver.executeAsyncScript<string>(`
-      var callback = arguments[arguments.length - 1];
-      var context = ${JSON.stringify(context)} || document;
-      var options = ${JSON.stringify(options)} || {};
-      window.axe.runPartial(context, options).then(res => JSON.stringify(res)).then(callback);
-    `)
-  );
-}
-
-export function axeFinishRun(
-  driver: WebDriver,
-  axeSource: string,
-  config: Spec | null,
-  partialResults: Array<string>,
-  options: RunOptions
-): Promise<AxeResults> {
-  // Inject source and configuration a second time with a mock "this" context,
-  // to make it impossible to sniff the global window.axe for results.
-  return promisify(
-    driver
-      .executeAsyncScript<string>(
-        `
-      var callback = arguments[arguments.length - 1];
-
-      ${axeSource};
-      window.axe.configure({
-        branding: { application: 'webdriverjs' }
-      });
-      var config = ${JSON.stringify(config)};
-      if (config) {
-        window.axe.configure(config);
-      }
-
-      var partialResults = ${JSON.stringify(partialResults)};
-      partialResults = partialResults.map(res => JSON.parse(res));
-      var options = ${JSON.stringify(options || {})};
-      window.axe.finishRun(partialResults, options).then(res => JSON.stringify(res)).then(callback);
-    `
-      )
-      .then(res => JSON.parse(res))
-  );
-}
-
-export function axeGetFrameContext(
-  driver: WebDriver,
-  context: ContextObject
-): Promise<FrameContextWeb[]> {
-  return promisify(
-    driver.executeScript<FrameContextWeb[]>(`
-      var context = ${JSON.stringify(context)}
-      var frameContexts = window.axe.utils.getFrameContexts(context);
-      return frameContexts.map(function (frameContext) {
-        return Object.assign(frameContext, {
-          href: window.location.href, // For debugging
-          frame: axe.utils.shadowSelect(frameContext.frameSelector)
-        });
-      });
-    `)
-  );
-}
-
-export function axeRunLegacy(
-  driver: WebDriver,
-  context: ContextObject,
-  options: RunOptions,
-  config: Spec | null
-): Promise<AxeResults> {
-  // https://github.com/vercel/pkg/issues/676
-  // we need to pass a string vs a function so we manually stringified the function
-  return promisify(
-    driver
-      .executeAsyncScript<string>(
-        `
-      var callback = arguments[arguments.length - 1];
-      var context = ${JSON.stringify(context)} || document;
-      var options = ${JSON.stringify(options)} || {};
-      var config = ${JSON.stringify(config)} || null;
-      if (config) {
-        window.axe.configure(config);
-      }
-      window.axe.run(context, options).then(res => JSON.stringify(res)).then(callback);
-    `
-      )
-      .then(res => JSON.parse(res))
-  );
-}
-
-/**
- * Selenium-webdriver thenable aren't chainable. This fixes it.
- */
-function promisify<T>(thenable: Promise<T>): Promise<T> {
-  return new Promise((resolve, reject) => {
-    thenable.then(resolve, reject);
-  });
-}