feat: Add .setLegacyMode (#356)

* feat(wdjs): Add .setLegacyMode

* feat(wdio): add setLegacyMode

* feat(puppeteer): Add setLegacyMode

* feat(playwright): Add setLegacyMode

* chore: upgrade package-lock

packages/playwright/README.md

@@ -68,6 +68,21 @@ Constructor for the AxeBuilder helper. You must pass an instance of Playwright a
 const builder = new AxeBuilder({ page });
 ```
 
+### AxeBuilder#analyze(): Promise<axe.Results | Error>
+
+Performs analysis and passes any encountered error and/or the result object.
+
+```js
+new AxeBuilder({ page })
+  .analyze()
+  .then(results => {
+    console.log(results);
+  })
+  .catch(e => {
+    // Do something with error
+  });
+```
+
 ### AxeBuilder#include(selector: String)
 
 Adds a CSS selector to the list of elements to include in analysis
@@ -124,17 +139,16 @@ Skips verification of the rules provided. Accepts a String of a single rule ID o
 new AxeBuilder({ page }).disableRules('color-contrast');
 ```
 
-### AxeBuilder#analyze(): Promise<axe.Results | Error>
+### AxeBuilder#setLegacyMode(legacyMode: boolean = true)
 
-Performs analysis and passes any encountered error and/or the result object.
+Set the frame testing method to "legacy mode". In this mode, axe will not open a blank page in which to aggregate its results. This can be used in an environment where opening a blank page is causes issues.
+
+With legacy mode turned on, axe will fall back to its test solution prior to the 4.3 release, but with cross-origin frame testing disabled. The `frame-tested` rule will report which frames were untested.
+
+**Important** Use of `.setLegacyMode()` is a last resort. If you find there is no other solution, please [report this as an issue](https://github.com/dequelabs/axe-core-npm/issues/).
 
 ```js
-new AxeBuilder({ page })
-  .analyze()
-  .then(results => {
-    console.log(results);
-  })
-  .catch(e => {
-    // Do something with error
-  });
+const axe = new AxeBuilder({ page }).setLegacyMode();
+const result = await axe.analyze();
+axe.setLegacyMode(false); // Disables legacy mode
 ```

packages/playwright/src/index.ts

@@ -22,6 +22,8 @@ export default class AxeBuilder {
   private excludes: string[];
   private option: RunOptions;
   private source: string;
+  private legacyMode = false;
+
   constructor({ page, axeSource }: AxePlaywrightParams) {
     const axePath = require.resolve('axe-core');
     const source = fs.readFileSync(axePath, 'utf-8');
@@ -122,6 +124,18 @@ export default class AxeBuilder {
     return this;
   }
 
+  /**
+   * Use frameMessenger with <same_origin_only>
+   *
+   * This disables use of axe.runPartial() which is called in each frame, and
+   * axe.finishRun() which is called in a blank page. This uses axe.run() instead,
+   * but with the restriction that cross-origin frames will not be tested.
+   */
+  public setLegacyMode(legacyMode = true): this {
+    this.legacyMode = legacyMode;
+    return this;
+  }
+
   /**
    * Perform analysis and retrieve results. *Does not chain.*
    * @return Promise<Result | Error>
@@ -138,7 +152,7 @@ export default class AxeBuilder {
 
     let results: AxeResults;
 
-    if (!runPartialDefined) {
+    if (!runPartialDefined || this.legacyMode) {
       results = await this.runLegacy(context);
       return results;
     }
@@ -169,12 +183,12 @@ export default class AxeBuilder {
 
   private script(): string {
     return `
-        ${this.source}
-        axe.configure({ 
-          allowedOrigins: ['<unsafe_all_origins>'], 
-          branding: { application: 'playwright' }
-        })
-        `;
+      ${this.source}
+      axe.configure({
+        ${this.legacyMode ? '' : 'allowedOrigins: ["<unsafe_all_origins>"],'}
+        branding: { application: 'playwright' }
+      })
+    `;
   }
 
   private async runLegacy(context: ContextObject): Promise<AxeResults> {

packages/playwright/tests/axe-playwright.spec.ts

@@ -397,6 +397,50 @@ describe('@axe-core/playwright', () => {
     });
   });
 
+  describe('setLegacyMode', () => {
+    const runPartialThrows = `;axe.runPartial = () => { throw new Error("No runPartial")}`;
+    it('runs legacy mode when used', async () => {
+      await page.goto(`${addr}/external/index.html`);
+      const results = await new AxeBuilder({
+        page,
+        axeSource: axeSource + runPartialThrows
+      })
+        .setLegacyMode()
+        .analyze();
+      assert.isNotNull(results);
+    });
+
+    it('prevents cross-origin frame testing', async () => {
+      await page.goto(`${addr}/external/cross-origin.html`);
+      const results = await new AxeBuilder({
+        page,
+        axeSource: axeSource + runPartialThrows
+      })
+        .withRules('frame-tested')
+        .setLegacyMode()
+        .analyze();
+
+      const frameTested = results.incomplete.find(
+        ({ id }) => id === 'frame-tested'
+      );
+      assert.ok(frameTested);
+    });
+
+    it('can be disabled again', async () => {
+      await page.goto(`${addr}/external/cross-origin.html`);
+      const results = await new AxeBuilder({ page })
+        .withRules('frame-tested')
+        .setLegacyMode()
+        .setLegacyMode(false)
+        .analyze();
+
+      const frameTested = results.incomplete.find(
+        ({ id }) => id === 'frame-tested'
+      );
+      assert.isUndefined(frameTested);
+    });
+  });
+
   describe('for versions without axe.runPartial', () => {
     describe('analyze', () => {
       it('returns results', async () => {
@@ -426,6 +470,21 @@ describe('@axe-core/playwright', () => {
         }
         assert.isNotNull(error);
       });
+
+      it('tests cross-origin pages', async () => {
+        await page.goto(`${addr}/external/cross-origin.html`);
+        const results = await new AxeBuilder({
+          page,
+          axeSource: axeLegacySource
+        })
+          .withRules('frame-tested')
+          .analyze();
+
+        const frameTested = results.incomplete.find(
+          ({ id }) => id === 'frame-tested'
+        );
+        assert.isUndefined(frameTested);
+      });
     });
 
     describe('frame tests', () => {

packages/puppeteer/README.md

@@ -87,6 +87,34 @@ const builder = new AxePuppeteer(page, axeSource);
 
 Note that you might need to bypass the Content Security Policy in some cases.
 
+### AxePuppeteer#analyze([callback: (Error | null[, Object]) => void])
+
+Performs analysis and passes any encountered error and/or the result object to the provided callback function or promise function. **Does not chain as the operation is asynchronous**
+
+Using the returned promise (optional):
+
+```js
+new AxePuppeteer(page)
+  .analyze()
+  .then(function (results) {
+    console.log(results);
+  })
+  .catch(err => {
+    // Handle error somehow
+  });
+```
+
+Using a callback function
+
+```js
+new AxePuppeteer(page).analyze(function (err, results) {
+  if (err) {
+    // Handle error somehow
+  }
+  console.log(results);
+});
+```
+
 ### AxePuppeteer#include(selector: string | string[])
 
 Adds a CSS selector to the list of elements to include in analysis
@@ -184,30 +212,16 @@ const results = await new AxePuppeteer(page).configure(config).analyze();
 console.log(results);
 ```
 
-### AxePuppeteer#analyze([callback: (Error | null[, Object]) => void])
-
-Performs analysis and passes any encountered error and/or the result object to the provided callback function or promise function. **Does not chain as the operation is asynchronous**
+### AxePuppeteer#setLegacyMode(legacyMode: boolean = true)
 
-Using the returned promise (optional):
+Set the frame testing method to "legacy mode". In this mode, axe will not open a blank page in which to aggregate its results. This can be used in an environment where opening a blank page is causes issues.
 
-```js
-new AxePuppeteer(page)
-  .analyze()
-  .then(function (results) {
-    console.log(results);
-  })
-  .catch(err => {
-    // Handle error somehow
-  });
-```
+With legacy mode turned on, axe will fall back to its test solution prior to the 4.3 release, but with cross-origin frame testing disabled. The `frame-tested` rule will report which frames were untested.
 
-Using a callback function
+**Important** Use of `.setLegacyMode()` is a last resort. If you find there is no other solution, please [report this as an issue](https://github.com/dequelabs/axe-core-npm/issues/).
 
 ```js
-new AxePuppeteer(page).analyze(function (err, results) {
-  if (err) {
-    // Handle error somehow
-  }
-  console.log(results);
-});
+const axe = new AxePuppeteer(page).setLegacyMode();
+const result = await axe.analyze();
+axe.setLegacyMode(false); // Disables legacy mode
 ```

packages/puppeteer/src/axePuppeteer.ts

@@ -28,6 +28,7 @@ export class AxePuppeteer {
   private config: Spec | null;
   private disabledFrameSelectors: string[];
   private page: Page | undefined;
+  private legacyMode = false;
 
   constructor(pageFrame: Page | Frame, source?: string) {
     if ('mainFrame' in pageFrame) {
@@ -130,6 +131,11 @@ export class AxePuppeteer {
     return this;
   }
 
+  public setLegacyMode(legacyMode = true): this {
+    this.legacyMode = legacyMode;
+    return this;
+  }
+
   public async analyze(): Promise<AxeResults>;
   public async analyze<T extends AnalyzeCB>(
     callback?: T
@@ -162,7 +168,11 @@ export class AxePuppeteer {
     await frameSourceInject(frame, axeSource, config);
 
     const runPartialSupported = await frame.evaluate(axeRunPartialSupport);
-    if (runPartialSupported !== true || this.page === undefined) {
+    if (
+      runPartialSupported !== true ||
+      this.page === undefined ||
+      this.legacyMode
+    ) {
       return this.runLegacy(context);
     }
     const partialRunner = await this.runPartialRecursive(frame, context);
@@ -226,14 +236,21 @@ export class AxePuppeteer {
     const options = this.axeOptions as JSONObject;
     const selector = iframeSelector(this.disabledFrameSelectors);
     const source = this.axeSource;
-    await injectJS(this.frame, { source, selector });
+    let config = this.config;
 
+    if (!this.legacyMode) {
+      config = {
+        ...(config || {}),
+        allowedOrigins: ['<unsafe_all_origins>']
+      };
+    }
+
+    await injectJS(this.frame, { source, selector });
     await injectJS(this.frame, {
       source: axeConfigure,
       selector,
-      args: [this.config]
+      args: [config]
     });
-
     return this.frame.evaluate(axeRunLegacy, context, options);
   }
 }

packages/puppeteer/src/browser.ts

@@ -25,7 +25,6 @@ export function axeConfigure(config?: Axe.Spec): void {
     window.axe.configure(config);
   }
   window.axe.configure({
-    allowedOrigins: ['<unsafe_all_origins>'],
     branding: { application: 'axe-puppeteer' }
   });
 }

packages/puppeteer/test/axePuppeteer.test.ts

@@ -694,6 +694,44 @@ describe('AxePuppeteer', function () {
     });
   });
 
+  describe('setLegacyMode', () => {
+    const runPartialThrows = `;axe.runPartial = () => { throw new Error("No runPartial")}`;
+    it('runs legacy mode when used', async () => {
+      await page.goto(`${addr}/external/index.html`);
+      const results = await new AxePuppeteer(page, axeSource + runPartialThrows)
+        .setLegacyMode()
+        .analyze();
+      assert.isNotNull(results);
+    });
+
+    it('prevents cross-origin frame testing', async () => {
+      await page.goto(`${addr}/external/cross-origin.html`);
+      const results = await new AxePuppeteer(page, axeSource + runPartialThrows)
+        .withRules('frame-tested')
+        .setLegacyMode()
+        .analyze();
+
+      const frameTested = results.incomplete.find(
+        ({ id }) => id === 'frame-tested'
+      );
+      assert.ok(frameTested);
+    });
+
+    it('can be disabled again', async () => {
+      await page.goto(`${addr}/external/cross-origin.html`);
+      const results = await new AxePuppeteer(page)
+        .withRules('frame-tested')
+        .setLegacyMode()
+        .setLegacyMode(false)
+        .analyze();
+
+      const frameTested = results.incomplete.find(
+        ({ id }) => id === 'frame-tested'
+      );
+      assert.isUndefined(frameTested);
+    });
+  });
+
   describe('without runPartial', () => {
     let axe403Source: string;
     before(() => {
@@ -739,5 +777,17 @@ describe('AxePuppeteer', function () {
       assert.equal(results.violations[0].id, 'label');
       assert.lengthOf(results.violations[0].nodes, 2);
     });
+
+    it('tests cross-origin pages', async () => {
+      await page.goto(`${addr}/external/cross-origin.html`);
+      const results = await new AxePuppeteer(page, axe403Source)
+        .withRules('frame-tested')
+        .analyze();
+
+      const frameTested = results.incomplete.find(
+        ({ id }) => id === 'frame-tested'
+      );
+      assert.isUndefined(frameTested);
+    });
   });
 });