microsoft · mshoho · Feb 5, 2026 · Feb 2, 2026 · Feb 2, 2026 · Feb 2, 2026
@@ -12,6 +12,9 @@ env:
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+          contents: read
+          pull-requests: write
 
     steps:
       - uses: actions/checkout@v3
@@ -21,15 +24,77 @@ jobs:
         with:
           node-version: 22.x
 
-      - run: npm install
-      - run: npx playwright install
-      - run: npm run type-check
-      - run: npm run build
-      - run: npm run lint
-      - run: npm run format
-      - name: "Run tests"
+      - name: Install dependencies
+        run: npm install
+
+      - name: Install Playwright browsers
+        run: npx playwright install
+
+      - name: Type check
+        run: npm run type-check
+
+      - name: Build
+        run: npm run build
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Format check
+        run: npm run format
+
+      - name: Run tests
         run: npm run test
-      - name: "Check for unstaged changes"
+
+      - name: Check for unstaged changes
+        run: |
+          git status --porcelain
+          git diff-index --quiet HEAD -- || exit 1
+
+  playwright-tools:
+    runs-on: ubuntu-latest
+    permissions:
+          contents: read
+          pull-requests: write
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Use Node.js 22
+        uses: actions/setup-node@v3
+        with:
+          node-version: 22.x
+
+      - name: Install root dependencies
+        run: npm install
+
+      - name: Install dependencies
+        working-directory: tools/playwright
+        run: npm install
+
+      - name: Install Playwright browsers
+        working-directory: tools/playwright
+        run: npx playwright install --with-deps chromium
+
+      - name: Type check
+        working-directory: tools/playwright
+        run: npm run type-check
+
+      - name: Build
+        working-directory: tools/playwright
+        run: npm run build
+
+      - name: Lint
+        working-directory: tools/playwright
+        run: npm run lint
+
+      - name: Format check
+        working-directory: tools/playwright
+        run: npm run format
+
+      - name: Run tests
+        working-directory: tools/playwright
+        run: npm run test
+
+      - name: Check for unstaged changes
         run: |
           git status --porcelain
           git diff-index --quiet HEAD -- || exit 1
@@ -11,3 +11,6 @@ tsconfig.tsbuildinfo
 /blob-report/
 /playwright/.cache/
 /logs/
+
+# Debug logs
+codespace-telemetry-debug.log
@@ -1,4 +1,6 @@
 # Ignore artifacts:
 dist
 node_modules
+test-results
+.test-output
 *.yml
@@ -40,10 +40,14 @@ export interface AbleDOMProps {
     ): void;
     onIssueRemoved?(element: HTMLElement, rule: ValidationRule): void;
   };
+  // Expose the created AbleDOM instance as window.ableDOMInstanceForTesting,
+  // in order for abledom-playwright to be able to automatically grab notifications
+  // during the tests.
+  exposeInstanceForTesting?: boolean;
 }
 
 export class AbleDOM {
-  private _win: Window;
+  private _win: Window & { ableDOMInstanceForTesting?: AbleDOM };
   private _isDisposed = false;
   private _props: AbleDOMProps | undefined = undefined;
   private _observer: MutationObserver;
@@ -68,6 +72,11 @@ export class AbleDOM {
 
   constructor(win: Window, props: AbleDOMProps = {}) {
     this._win = win;
+
+    if (props.exposeInstanceForTesting) {
+      this._win.ableDOMInstanceForTesting = this;
+    }
+
     this._props = props;
 
     const _elementsToValidate: Set<HTMLElementWithAbleDOM> = new Set();

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Exposed Instance - Headless</title>
+    <script type="module" src="./exposed-headless.ts"></script>
+  </head>
+  <body>
+    <h1>Exposed Instance - Headless</h1>
+    <button id="button-1">Button1</button>
+  </body>
+</html>
@@ -0,0 +1,17 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AbleDOM, FocusableElementLabelRule } from "abledom";
+import { initIdleProp, getAbleDOMCallbacks } from "../utils";
+
+// Create AbleDOM with headless: true (hide UI) and expose instance for testing
+const ableDOM = new AbleDOM(window, {
+  headless: true,
+  exposeInstanceForTesting: true,
+  callbacks: getAbleDOMCallbacks(),
+});
+initIdleProp(ableDOM);
+ableDOM.addRule(new FocusableElementLabelRule());
+ableDOM.start();
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Exposed Instance - With UI</title>
+    <script type="module" src="./exposed-with-ui.ts"></script>
+  </head>
+  <body>
+    <h1>Exposed Instance - With UI</h1>
+    <button id="button-1">Button1</button>
+  </body>
+</html>
@@ -0,0 +1,17 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AbleDOM, FocusableElementLabelRule } from "abledom";
+import { initIdleProp, getAbleDOMCallbacks } from "../utils";
+
+// Create AbleDOM with headless: false (show UI) and expose instance for testing
+const ableDOM = new AbleDOM(window, {
+  headless: false,
+  exposeInstanceForTesting: true,
+  callbacks: getAbleDOMCallbacks(),
+});
+initIdleProp(ableDOM);
+ableDOM.addRule(new FocusableElementLabelRule());
+ableDOM.start();
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Instance Not Exposed</title>
+    <script type="module" src="./not-exposed.ts"></script>
+  </head>
+  <body>
+    <h1>Instance Not Exposed</h1>
+    <button id="button-1">Button1</button>
+  </body>
+</html>
@@ -0,0 +1,16 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AbleDOM, FocusableElementLabelRule } from "abledom";
+import { initIdleProp, getAbleDOMCallbacks } from "../utils";
+
+// Create AbleDOM without exposing instance for testing
+const ableDOM = new AbleDOM(window, {
+  headless: true,
+  callbacks: getAbleDOMCallbacks(),
+});
+initIdleProp(ableDOM);
+ableDOM.addRule(new FocusableElementLabelRule());
+ableDOM.start();
@@ -0,0 +1,143 @@
+/*!
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { test, expect } from "@playwright/test";
+import { loadTestPage, issueSelector } from "../utils";
+
+interface WindowWithAbleDOMInstance extends Window {
+  ableDOMInstanceForTesting?: {
+    idle: () => Promise<unknown[]>;
+    highlightElement: (element: HTMLElement, scrollIntoView: boolean) => void;
+  };
+}
+
+test.describe("exposeInstanceForTesting prop", () => {
+  test("exposeInstanceForTesting: true with headless: false should expose instance and show UI", async ({
+    page,
+  }) => {
+    await loadTestPage(page, "tests/testingMode/exposed-with-ui.html");
+
+    // Check that the instance is exposed
+    const hasInstance = await page.evaluate(() => {
+      return (
+        typeof (window as WindowWithAbleDOMInstance)
+          .ableDOMInstanceForTesting !== "undefined"
+      );
+    });
+    expect(hasInstance).toBe(true);
+
+    // Check that the instance has the expected methods
+    const hasIdleMethod = await page.evaluate(() => {
+      return (
+        typeof (window as WindowWithAbleDOMInstance).ableDOMInstanceForTesting
+          ?.idle === "function"
+      );
+    });
+    expect(hasIdleMethod).toBe(true);
+
+    // Create an issue by removing the button text
+    await page.evaluate(() => {
+      const btn = document.getElementById("button-1");
+      if (btn) {
+        btn.innerText = "";
+      }
+    });
+
+    // Wait for AbleDOM to process
+    await page.evaluate(async () => {
+      await (
+        window as WindowWithAbleDOMInstance
+      ).ableDOMInstanceForTesting?.idle();
+    });
+
+    // With headless: false, the UI should be visible
+    const issueCount = await page.$$(issueSelector);
+    expect(issueCount.length).toBeGreaterThan(0);
+  });
+
+  test("exposeInstanceForTesting: true with headless: true should expose instance but hide UI", async ({
+    page,
+  }) => {
+    await loadTestPage(page, "tests/testingMode/exposed-headless.html");
+
+    // Check that the instance is exposed
+    const hasInstance = await page.evaluate(() => {
+      return (
+        typeof (window as WindowWithAbleDOMInstance)
+          .ableDOMInstanceForTesting !== "undefined"
+      );
+    });
+    expect(hasInstance).toBe(true);
+
+    // Check that the instance has the expected methods
+    const hasIdleMethod = await page.evaluate(() => {
+      return (
+        typeof (window as WindowWithAbleDOMInstance).ableDOMInstanceForTesting
+          ?.idle === "function"
+      );
+    });
+    expect(hasIdleMethod).toBe(true);
+
+    // Create an issue by removing the button text
+    await page.evaluate(() => {
+      const btn = document.getElementById("button-1");
+      if (btn) {
+        btn.innerText = "";
+      }
+    });
+
+    // Wait for AbleDOM to process
+    await page.evaluate(async () => {
+      await (
+        window as WindowWithAbleDOMInstance
+      ).ableDOMInstanceForTesting?.idle();
+    });
+
+    // With headless: true, the UI should NOT be visible
+    const issueCount = await page.$$(issueSelector);
+    expect(issueCount.length).toBe(0);
+  });
+
+  test("without exposeInstanceForTesting should NOT expose instance", async ({
+    page,
+  }) => {
+    await loadTestPage(page, "tests/testingMode/not-exposed.html");
+
+    // Check that the instance is NOT exposed
+    const hasInstance = await page.evaluate(() => {
+      return (
+        typeof (window as WindowWithAbleDOMInstance)
+          .ableDOMInstanceForTesting !== "undefined"
+      );
+    });
+    expect(hasInstance).toBe(false);
+  });
+
+  test("exposed instance idle() should return issues", async ({ page }) => {
+    await loadTestPage(page, "tests/testingMode/exposed-headless.html");
+
+    // Create an issue
+    await page.evaluate(() => {
+      const btn = document.getElementById("button-1");
+      if (btn) {
+        btn.innerText = "";
+      }
+    });
+
+    // Use the exposed instance to get issues
+    const issues = await page.evaluate(async () => {
+      const instance = (window as WindowWithAbleDOMInstance)
+        .ableDOMInstanceForTesting;
+      const result = await instance?.idle();
+      return result?.map((issue) => ({
+        id: (issue as { id?: string }).id,
+        message: (issue as { message?: string }).message,
+      }));
+    });
+
+    expect(issues).toBeDefined();
+    expect(issues!.length).toBe(1);
+    expect(issues![0].id).toBe("focusable-element-label");
+  });
+});
@@ -20,8 +20,10 @@ interface WindowWithAbleDOMData extends Window {
   >;
 }
 
-export interface ValidationIssueForTestsIdle
-  extends Omit<ValidationIssue, "element"> {
+export interface ValidationIssueForTestsIdle extends Omit<
+  ValidationIssue,
+  "element"
+> {
   element?: string;
 }
 

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.test-output/
+test-results/