feat: support shadow dom selectors

packages/cli/package.json

@@ -45,7 +45,7 @@
   ],
   "dependencies": {
     "@axe-core/webdriverjs": "^4.5.2",
-    "axe-core": "^4.5.2",
+    "axe-core": "^4.6.0",
     "chromedriver": "^106.0.1",
     "colors": "^1.4.0",
     "commander": "^9.4.1",

packages/playwright/package.json

@@ -39,15 +39,15 @@
     "prepare": "npm run build"
   },
   "dependencies": {
-    "axe-core": "^4.5.2"
+    "axe-core": "^4.6.0"
   },
   "devDependencies": {
     "@types/chai": "^4.3.3",
     "@types/express": "^4.17.14",
     "@types/mocha": "^10.0.0",
     "@types/node": "^18.8.3",
     "@types/test-listen": "^1.1.0",
-    "axe-test-fixtures": "github:dequelabs/axe-test-fixtures",
+    "axe-test-fixtures": "github:dequelabs/axe-test-fixtures#v1",
     "chai": "^4.3.6",
     "express": "^4.18.2",
     "mocha": "^10.0.0",

packages/playwright/src/index.ts

@@ -4,7 +4,11 @@ import type {
   RunOptions,
   AxeResults,
   SerialContextObject,
-  PartialResults
+  PartialResults,
+  ContextObject,
+  SerialSelectorList,
+  SerialSelector,
+  SerialFrameSelector
 } from 'axe-core';
 import { source } from 'axe-core';
 import { normalizeContext, analyzePage } from './utils';
@@ -16,11 +20,12 @@ import {
   axeShadowSelect
 } from './browser';
 import AxePartialRunner from './AxePartialRunner';
+type NewContextObject = ContextObject | SerialContextObject;
 
 export default class AxeBuilder {
   private page: Page;
-  private includes: string[][];
-  private excludes: string[][];
+  private includes: SerialSelectorList;
+  private excludes: SerialSelectorList;
   private option: RunOptions;
   private source: string;
   private legacyMode = false;
@@ -43,8 +48,7 @@ export default class AxeBuilder {
    * @returns this
    */
 
-  public include(selector: string | string[]): this {
-    selector = Array.isArray(selector) ? selector : [selector];
+  public include(selector: SerialFrameSelector): this {
     this.includes.push(selector);
     return this;
   }
@@ -56,8 +60,7 @@ export default class AxeBuilder {
    * @returns this
    */
 
-  public exclude(selector: string | string[]): this {
-    selector = Array.isArray(selector) ? selector : [selector];
+  public exclude(selector: SerialFrameSelector): this {
     this.excludes.push(selector);
     return this;
   }
@@ -148,6 +151,7 @@ export default class AxeBuilder {
   public async analyze(): Promise<AxeResults> {
     const context = normalizeContext(this.includes, this.excludes);
     const { page, option: options } = this;
+    console.log(JSON.stringify(context, null, 2));
 
     page.evaluate(this.script());
     const runPartialDefined = await page.evaluate<boolean>(

packages/playwright/src/types.ts

@@ -4,14 +4,15 @@ import type {
   AxeResults,
   ContextObject,
   CrossTreeSelector,
-  PartialResult
+  PartialResult,
+  SerialContextObject
 } from 'axe-core';
 
 export type PartialResults = PartialResult | null;
 
 export interface AnalyzePageParams {
-  context: ContextObject;
-  options: RunOptions | null;
+  context: SerialContextObject;
+  options: RunOptions;
 }
 
 export interface AxePlaywrightParams {

packages/playwright/src/utils.ts

@@ -1,4 +1,8 @@
-import type { AxeResults, SerialContextObject } from 'axe-core';
+import type {
+  AxeResults,
+  SerialContextObject,
+  SerialSelectorList
+} from 'axe-core';
 import type { AnalyzePageParams, AnalyzePageResponse } from './types';
 
 /**
@@ -9,11 +13,12 @@ import type { AnalyzePageParams, AnalyzePageResponse } from './types';
  */
 
 export const normalizeContext = (
-  includes: string[][],
-  excludes: string[][]
+  includes: SerialSelectorList,
+  excludes: SerialSelectorList
 ): SerialContextObject => {
   const base: SerialContextObject = {
-    exclude: []
+    exclude: [],
+    include: []
   };
   if (excludes.length && Array.isArray(base.exclude)) {
     base.exclude.push(...excludes);

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

@@ -2,7 +2,12 @@ import 'mocha';
 import fs from 'fs';
 import playwright from 'playwright';
 import express from 'express';
-import type { AxeResults } from 'axe-core';
+import type {
+  AxeResults,
+  Result,
+  SerialSelector,
+  SerialSelectorList
+} from 'axe-core';
 import testListen from 'test-listen';
 import { assert } from 'chai';
 import path from 'path';
@@ -426,7 +431,7 @@ describe('@axe-core/playwright', () => {
           return acc.concat(pass.nodes as any);
         }, [])
         .reduce((acc, node: any) => {
-          return acc.concat(node.target);
+          return acc.concat(node.target.flat(1));
         }, []);
     };
     it('with include and exclude', async () => {
@@ -557,6 +562,74 @@ describe('@axe-core/playwright', () => {
       assert.equal(res?.status(), 200);
       assert.deepEqual(actual[0], expected);
     });
+
+    it('with labelled frame', async () => {
+      await page.goto(`${addr}/external/context-include-exclude.html`);
+      const results = await new AxeBuilder({ page })
+        .include({ fromFrames: ['#ifr-inc-excl', 'html'] })
+        .exclude({ fromFrames: ['#ifr-inc-excl', '#foo-bar'] })
+        .include({ fromFrames: ['#ifr-inc-excl', '#foo-baz', 'html'] })
+        .exclude({ fromFrames: ['#ifr-inc-excl', '#foo-baz', 'input'] })
+        .analyze();
+      const labelResult = results.violations.find(
+        (r: Result) => r.id === 'label'
+      );
+      assert.isFalse(flatPassesTargets(results).includes('#foo-bar'));
+      assert.isFalse(flatPassesTargets(results).includes('input'));
+      assert.isUndefined(labelResult);
+    });
+
+    it('with include shadow DOM', async () => {
+      await page.goto(`${addr}/external/shadow-dom.html`);
+      const results = await new AxeBuilder({ page })
+        .include([['#shadow-root-1', '#shadow-button-1']])
+        .include([['#shadow-root-2', '#shadow-button-2']])
+        .analyze();
+      assert.isTrue(flatPassesTargets(results).includes('#shadow-button-1'));
+      assert.isTrue(flatPassesTargets(results).includes('#shadow-button-2'));
+      assert.isFalse(flatPassesTargets(results).includes('#button'));
+    });
+
+    it('with exclude shadow DOM', async () => {
+      await page.goto(`${addr}/external/shadow-dom.html`);
+      const results = await new AxeBuilder({ page })
+        .exclude([['#shadow-root-1', '#shadow-button-1']])
+        .exclude([['#shadow-root-2', '#shadow-button-2']])
+        .analyze();
+      assert.isFalse(flatPassesTargets(results).includes('#shadow-button-1'));
+      assert.isFalse(flatPassesTargets(results).includes('#shadow-button-2'));
+      assert.isTrue(flatPassesTargets(results).includes('#button'));
+    });
+
+    it('with labelled shadow DOM', async () => {
+      await page.goto(`${addr}/external/shadow-dom.html`);
+      const results = await new AxeBuilder({ page })
+        .include({ fromShadowDom: ['#shadow-root-1', '#shadow-button-1'] })
+        .exclude({ fromShadowDom: ['#shadow-root-2', '#shadow-button-2'] })
+        .analyze();
+      assert.isTrue(flatPassesTargets(results).includes('#shadow-button-1'));
+      assert.isFalse(flatPassesTargets(results).includes('#shadow-button-2'));
+    });
+
+    it('with labelled iframe and shadow DOM', async () => {
+      await page.goto(`${addr}/external/shadow-frames.html`);
+      const { violations } = await new AxeBuilder({ page })
+        .exclude({
+          fromFrames: [
+            {
+              fromShadowDom: ['#shadow-root', '#shadow-frame']
+            },
+            'input'
+          ]
+        })
+        .options({ runOnly: 'label' })
+        .analyze();
+      assert.equal(violations[0].id, 'label');
+      assert.lengthOf(violations[0].nodes, 2);
+      const nodes = violations[0].nodes;
+      assert.deepEqual(nodes[0].target, ['#light-frame', 'input']);
+      assert.deepEqual(nodes[1].target, ['#slotted-frame', 'input']);
+    });
   });
 
   describe('axe.finishRun errors', () => {