aria-ease 3.0.2 → 4.0.0

package/README.md

@@ -172,7 +172,7 @@ updateAccordionTriggerAriaAttributes(
   "accordion-container", // Container ID
   "accordion-trigger", // Shared class for triggers
   accordionStates, // State array
-  0 // Index of trigger that changed
+  0, // Index of trigger that changed
 );
 ```
 
@@ -223,7 +223,7 @@ function handleCheckboxClick(index) {
     "checkbox-group",
     "custom-checkbox",
     checkboxStates,
-    index
+    index,
   );
 }
 ```
@@ -314,14 +314,14 @@ Aria-Ease includes a built-in testing framework for automated accessibility vali
 import { testUiComponent } from "aria-ease/test";
 
 // In your test file (Vitest, Jest, etc.)
-test("menu is accessible", async () => {
-  const { container } = render(<MyMenu />);
+test("combobox is accessible", async () => {
+  const { container } = render(<Combobox />);
 
   // Runs axe-core + contract tests
   const result = await testUiComponent(
-    "menu",
+    "combobox",
     container,
-    "http://localhost:3000" // Optional: full E2E with Playwright
+    "http://localhost:3000", // Optional: full E2E with Playwright
   );
 
   expect(result.violations).toHaveLength(0);

package/bin/cli.cjs

@@ -13261,7 +13261,7 @@ async function runContractTests(componentName, component) {
   const staticFailed = 0;
   reporter.reportStatic(staticPassed, staticFailed);
   reporter.summary(failures);
-  return { passes, failures };
+  return { passes, failures, skipped };
 }
 var import_promises, import_meta;
 var init_contractTestRunner = __esm({
@@ -13308,6 +13308,7 @@ async function runContractTestsPlaywright(componentName, url) {
   reporter.start(componentName, totalTests);
   const failures = [];
   const passes = [];
+  const skipped = [];
   let browser = null;
   try {
     browser = await import_playwright3.chromium.launch({ headless: true });
@@ -13315,13 +13316,13 @@ async function runContractTestsPlaywright(componentName, url) {
     const page = await context.newPage();
     await page.goto(url, {
       waitUntil: "domcontentloaded",
-      timeout: 6e4
+      timeout: 9e4
     });
     const mainSelector = componentContract.selectors.trigger || componentContract.selectors.input || componentContract.selectors.container;
     if (!mainSelector) {
       throw new Error(`No main selector (trigger, input, or container) found in contract for ${componentName}`);
     }
-    await page.waitForSelector(mainSelector, { timeout: 6e4 });
+    await page.waitForSelector(mainSelector, { timeout: 9e4 });
     if (componentName === "menu" && componentContract.selectors.trigger) {
       await page.waitForFunction(
         (selector) => {
@@ -13329,7 +13330,7 @@ async function runContractTestsPlaywright(componentName, url) {
           return trigger && trigger.getAttribute("data-menu-initialized") === "true";
         },
         componentContract.selectors.trigger,
-        { timeout: 5e3 }
+        { timeout: 6e3 }
       ).catch(() => {
         console.warn("Menu initialization signal not detected, continuing with tests...");
       });
@@ -13419,11 +13420,43 @@ async function runContractTestsPlaywright(componentName, url) {
             if (componentContract.selectors.input) {
               const inputElement = page.locator(componentContract.selectors.input).first();
               await inputElement.clear();
-              await page.waitForTimeout(50);
+              await page.waitForTimeout(100);
+            }
+          }
+        }
+      }
+      let shouldSkipTest = false;
+      for (const act of action) {
+        if (act.type === "keypress" && (act.target === "submenuTrigger" || act.target === "submenu")) {
+          const submenuSelector = componentContract.selectors[act.target];
+          if (submenuSelector) {
+            const submenuCount = await page.locator(submenuSelector).count();
+            if (submenuCount === 0) {
+              reporter.reportTest(dynamicTest, "skip", `Skipping test - ${act.target} element not found (optional submenu test)`);
+              shouldSkipTest = true;
+              break;
+            }
+          }
+        }
+      }
+      if (!shouldSkipTest) {
+        for (const assertion of assertions) {
+          if (assertion.target === "submenu" || assertion.target === "submenuTrigger") {
+            const submenuSelector = componentContract.selectors[assertion.target];
+            if (submenuSelector) {
+              const submenuCount = await page.locator(submenuSelector).count();
+              if (submenuCount === 0) {
+                reporter.reportTest(dynamicTest, "skip", `Skipping test - ${assertion.target} element not found (optional submenu test)`);
+                shouldSkipTest = true;
+                break;
+              }
             }
           }
         }
       }
+      if (shouldSkipTest) {
+        continue;
+      }
       for (const act of action) {
         if (act.type === "focus") {
           const focusSelector = componentContract.selectors[act.target];
@@ -13432,7 +13465,7 @@ async function runContractTestsPlaywright(componentName, url) {
             continue;
           }
           await page.locator(focusSelector).first().focus();
-          await page.waitForTimeout(50);
+          await page.waitForTimeout(100);
         }
         if (act.type === "type" && act.value) {
           const typeSelector = componentContract.selectors[act.target];
@@ -13441,7 +13474,7 @@ async function runContractTestsPlaywright(componentName, url) {
             continue;
           }
           await page.locator(typeSelector).first().fill(act.value);
-          await page.waitForTimeout(50);
+          await page.waitForTimeout(100);
         }
         if (act.type === "click") {
           if (act.target === "document") {
@@ -13491,7 +13524,7 @@ async function runContractTestsPlaywright(componentName, url) {
           if (act.target === "focusable" && ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Escape"].includes(keyValue)) {
             await page.waitForTimeout(100);
             await page.keyboard.press(keyValue);
-            await page.waitForTimeout(50);
+            await page.waitForTimeout(100);
           } else {
             const keypressSelector = componentContract.selectors[act.target];
             if (!keypressSelector) {
@@ -13520,7 +13553,7 @@ async function runContractTestsPlaywright(componentName, url) {
               continue;
             }
             await relativeElement.hover();
-            await page.waitForTimeout(50);
+            await page.waitForTimeout(100);
           } else {
             const hoverSelector = componentContract.selectors[act.target];
             if (!hoverSelector) {
@@ -13528,7 +13561,7 @@ async function runContractTestsPlaywright(componentName, url) {
               continue;
             }
             await page.locator(hoverSelector).first().hover();
-            await page.waitForTimeout(50);
+            await page.waitForTimeout(100);
           }
         }
         await page.waitForTimeout(100);
@@ -13670,7 +13703,7 @@ async function runContractTestsPlaywright(componentName, url) {
   } finally {
     if (browser) await browser.close();
   }
-  return { passes, failures };
+  return { passes, failures, skipped };
 }
 var import_playwright3, import_fs, import_meta2;
 var init_contractTestRunnerPlaywright = __esm({
@@ -13687,15 +13720,49 @@ var init_contractTestRunnerPlaywright = __esm({
 
 // src/utils/test/src/test.ts
 async function testUiComponent(componentName, component, url) {
-  const results = await (0, import_jest_axe.axe)(component);
+  if (!componentName || typeof componentName !== "string") {
+    throw new Error("\u274C testUiComponent requires a valid componentName (string)");
+  }
+  if (!component || !(component instanceof HTMLElement)) {
+    throw new Error("\u274C testUiComponent requires a valid component (HTMLElement)");
+  }
+  if (url && typeof url !== "string") {
+    throw new Error("\u274C testUiComponent url parameter must be a string");
+  }
+  let results;
+  try {
+    results = await (0, import_jest_axe.axe)(component);
+  } catch (error) {
+    throw new Error(
+      `\u274C Axe accessibility scan failed
+Error: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
   let contract;
-  if (url) {
-    console.log(`\u{1F3AD} Running Playwright E2E tests on ${url}`);
-    const { runContractTestsPlaywright: runContractTestsPlaywright2 } = await Promise.resolve().then(() => (init_contractTestRunnerPlaywright(), contractTestRunnerPlaywright_exports));
-    contract = await runContractTestsPlaywright2(componentName, url);
-  } else {
-    console.log(`\u{1F9EA} Running jsdom tests (limited event handling)`);
-    contract = await runContractTests(componentName, component);
+  try {
+    if (url) {
+      console.log(`\u{1F3AD} Running Playwright E2E tests on ${url}`);
+      try {
+        new URL(url);
+      } catch {
+        throw new Error(
+          `\u274C Invalid URL format: "${url}"
+URL must include protocol (e.g., "http://localhost:5173/test")`
+        );
+      }
+      const { runContractTestsPlaywright: runContractTestsPlaywright2 } = await Promise.resolve().then(() => (init_contractTestRunnerPlaywright(), contractTestRunnerPlaywright_exports));
+      contract = await runContractTestsPlaywright2(componentName, url);
+    } else {
+      console.log(`\u{1F9EA} Running jsdom tests (limited event handling)`);
+      console.log(`Some tests may be skipped or yield false positives/negatives.
+For full coverage, run with a URL to enable Playwright E2E tests.`);
+      contract = await runContractTests(componentName, component);
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      throw error;
+    }
+    throw new Error(`\u274C Contract test execution failed: ${String(error)}`);
   }
   const result = {
     violations: results.violations,
@@ -13706,10 +13773,11 @@ async function testUiComponent(componentName, component, url) {
     const mode = url ? "Playwright" : "jsdom";
     throw new Error(
       `
-\u274C ${contract.failures.length} assertion${contract.failures.length > 1 ? "s" : ""} failed (${mode} mode)
-\u2705 ${contract.passes.length} assertion${contract.passes.length > 1 ? "s" : ""} passed
+\u274C ${contract.failures.length} accessibility contract test${contract.failures.length > 1 ? "s" : ""} failed (${mode} mode)
+\u2705 ${contract.passes.length} test${contract.passes.length > 1 ? "s" : ""} passed
 
-\u{1F4CB} Review the detailed test report above for specific failures.`
+\u{1F4CB} Review the detailed test report above for specific failures.
+\u{1F4A1} Contract tests validate ARIA attributes and keyboard interactions per W3C APG guidelines.`
     );
   }
   if (results.violations.length > 0) {

package/bin/cli.js

@@ -204,7 +204,7 @@ program.command("audit").description("Run axe-core powered accessibility audit o
   console.log(chalk.green("\n\u{1F389} All audits completed."));
 });
 program.command("test").description("Run core a11y accessibility standard tests on UI components").action(async () => {
-  const { runTest } = await import("./test-Q7W3WQEA.js");
+  const { runTest } = await import("./test-45KMD4F4.js");
   runTest();
 });
 program.command("help").description("Display help information").action(() => {

package/bin/{contractTestRunnerPlaywright-TLQZGKW7.js → contractTestRunnerPlaywright-EZLNNJV5.js}

@@ -35,6 +35,7 @@ async function runContractTestsPlaywright(componentName, url) {
   reporter.start(componentName, totalTests);
   const failures = [];
   const passes = [];
+  const skipped = [];
   let browser = null;
   try {
     browser = await chromium.launch({ headless: true });
@@ -42,13 +43,13 @@ async function runContractTestsPlaywright(componentName, url) {
     const page = await context.newPage();
     await page.goto(url, {
       waitUntil: "domcontentloaded",
-      timeout: 6e4
+      timeout: 9e4
     });
     const mainSelector = componentContract.selectors.trigger || componentContract.selectors.input || componentContract.selectors.container;
     if (!mainSelector) {
       throw new Error(`No main selector (trigger, input, or container) found in contract for ${componentName}`);
     }
-    await page.waitForSelector(mainSelector, { timeout: 6e4 });
+    await page.waitForSelector(mainSelector, { timeout: 9e4 });
     if (componentName === "menu" && componentContract.selectors.trigger) {
       await page.waitForFunction(
         (selector) => {
@@ -56,7 +57,7 @@ async function runContractTestsPlaywright(componentName, url) {
           return trigger && trigger.getAttribute("data-menu-initialized") === "true";
         },
         componentContract.selectors.trigger,
-        { timeout: 5e3 }
+        { timeout: 6e3 }
       ).catch(() => {
         console.warn("Menu initialization signal not detected, continuing with tests...");
       });
@@ -146,11 +147,43 @@ async function runContractTestsPlaywright(componentName, url) {
             if (componentContract.selectors.input) {
               const inputElement = page.locator(componentContract.selectors.input).first();
               await inputElement.clear();
-              await page.waitForTimeout(50);
+              await page.waitForTimeout(100);
             }
           }
         }
       }
+      let shouldSkipTest = false;
+      for (const act of action) {
+        if (act.type === "keypress" && (act.target === "submenuTrigger" || act.target === "submenu")) {
+          const submenuSelector = componentContract.selectors[act.target];
+          if (submenuSelector) {
+            const submenuCount = await page.locator(submenuSelector).count();
+            if (submenuCount === 0) {
+              reporter.reportTest(dynamicTest, "skip", `Skipping test - ${act.target} element not found (optional submenu test)`);
+              shouldSkipTest = true;
+              break;
+            }
+          }
+        }
+      }
+      if (!shouldSkipTest) {
+        for (const assertion of assertions) {
+          if (assertion.target === "submenu" || assertion.target === "submenuTrigger") {
+            const submenuSelector = componentContract.selectors[assertion.target];
+            if (submenuSelector) {
+              const submenuCount = await page.locator(submenuSelector).count();
+              if (submenuCount === 0) {
+                reporter.reportTest(dynamicTest, "skip", `Skipping test - ${assertion.target} element not found (optional submenu test)`);
+                shouldSkipTest = true;
+                break;
+              }
+            }
+          }
+        }
+      }
+      if (shouldSkipTest) {
+        continue;
+      }
       for (const act of action) {
         if (act.type === "focus") {
           const focusSelector = componentContract.selectors[act.target];
@@ -159,7 +192,7 @@ async function runContractTestsPlaywright(componentName, url) {
             continue;
           }
           await page.locator(focusSelector).first().focus();
-          await page.waitForTimeout(50);
+          await page.waitForTimeout(100);
         }
         if (act.type === "type" && act.value) {
           const typeSelector = componentContract.selectors[act.target];
@@ -168,7 +201,7 @@ async function runContractTestsPlaywright(componentName, url) {
             continue;
           }
           await page.locator(typeSelector).first().fill(act.value);
-          await page.waitForTimeout(50);
+          await page.waitForTimeout(100);
         }
         if (act.type === "click") {
           if (act.target === "document") {
@@ -218,7 +251,7 @@ async function runContractTestsPlaywright(componentName, url) {
           if (act.target === "focusable" && ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Escape"].includes(keyValue)) {
             await page.waitForTimeout(100);
             await page.keyboard.press(keyValue);
-            await page.waitForTimeout(50);
+            await page.waitForTimeout(100);
           } else {
             const keypressSelector = componentContract.selectors[act.target];
             if (!keypressSelector) {
@@ -247,7 +280,7 @@ async function runContractTestsPlaywright(componentName, url) {
               continue;
             }
             await relativeElement.hover();
-            await page.waitForTimeout(50);
+            await page.waitForTimeout(100);
           } else {
             const hoverSelector = componentContract.selectors[act.target];
             if (!hoverSelector) {
@@ -255,7 +288,7 @@ async function runContractTestsPlaywright(componentName, url) {
               continue;
             }
             await page.locator(hoverSelector).first().hover();
-            await page.waitForTimeout(50);
+            await page.waitForTimeout(100);
           }
         }
         await page.waitForTimeout(100);
@@ -397,7 +430,7 @@ async function runContractTestsPlaywright(componentName, url) {
   } finally {
     if (browser) await browser.close();
   }
-  return { passes, failures };
+  return { passes, failures, skipped };
 }
 export {
   runContractTestsPlaywright

package/bin/{test-Q7W3WQEA.js → test-45KMD4F4.js}

@@ -12741,20 +12741,54 @@ async function runContractTests(componentName, component) {
   const staticFailed = 0;
   reporter.reportStatic(staticPassed, staticFailed);
   reporter.summary(failures);
-  return { passes, failures };
+  return { passes, failures, skipped };
 }
 
 // src/utils/test/src/test.ts
 async function testUiComponent(componentName, component, url) {
-  const results = await axe(component);
+  if (!componentName || typeof componentName !== "string") {
+    throw new Error("\u274C testUiComponent requires a valid componentName (string)");
+  }
+  if (!component || !(component instanceof HTMLElement)) {
+    throw new Error("\u274C testUiComponent requires a valid component (HTMLElement)");
+  }
+  if (url && typeof url !== "string") {
+    throw new Error("\u274C testUiComponent url parameter must be a string");
+  }
+  let results;
+  try {
+    results = await axe(component);
+  } catch (error) {
+    throw new Error(
+      `\u274C Axe accessibility scan failed
+Error: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
   let contract;
-  if (url) {
-    console.log(`\u{1F3AD} Running Playwright E2E tests on ${url}`);
-    const { runContractTestsPlaywright } = await import("./contractTestRunnerPlaywright-TLQZGKW7.js");
-    contract = await runContractTestsPlaywright(componentName, url);
-  } else {
-    console.log(`\u{1F9EA} Running jsdom tests (limited event handling)`);
-    contract = await runContractTests(componentName, component);
+  try {
+    if (url) {
+      console.log(`\u{1F3AD} Running Playwright E2E tests on ${url}`);
+      try {
+        new URL(url);
+      } catch {
+        throw new Error(
+          `\u274C Invalid URL format: "${url}"
+URL must include protocol (e.g., "http://localhost:5173/test")`
+        );
+      }
+      const { runContractTestsPlaywright } = await import("./contractTestRunnerPlaywright-EZLNNJV5.js");
+      contract = await runContractTestsPlaywright(componentName, url);
+    } else {
+      console.log(`\u{1F9EA} Running jsdom tests (limited event handling)`);
+      console.log(`Some tests may be skipped or yield false positives/negatives.
+For full coverage, run with a URL to enable Playwright E2E tests.`);
+      contract = await runContractTests(componentName, component);
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      throw error;
+    }
+    throw new Error(`\u274C Contract test execution failed: ${String(error)}`);
   }
   const result = {
     violations: results.violations,
@@ -12765,10 +12799,11 @@ async function testUiComponent(componentName, component, url) {
     const mode = url ? "Playwright" : "jsdom";
     throw new Error(
       `
-\u274C ${contract.failures.length} assertion${contract.failures.length > 1 ? "s" : ""} failed (${mode} mode)
-\u2705 ${contract.passes.length} assertion${contract.passes.length > 1 ? "s" : ""} passed
+\u274C ${contract.failures.length} accessibility contract test${contract.failures.length > 1 ? "s" : ""} failed (${mode} mode)
+\u2705 ${contract.passes.length} test${contract.passes.length > 1 ? "s" : ""} passed
 
-\u{1F4CB} Review the detailed test report above for specific failures.`
+\u{1F4CB} Review the detailed test report above for specific failures.
+\u{1F4A1} Contract tests validate ARIA attributes and keyboard interactions per W3C APG guidelines.`
     );
   }
   if (results.violations.length > 0) {

package/dist/{contractTestRunnerPlaywright-7U2O33SR.js → contractTestRunnerPlaywright-UQQI5MYS.js}

@@ -33,6 +33,7 @@ async function runContractTestsPlaywright(componentName, url) {
   reporter.start(componentName, totalTests);
   const failures = [];
   const passes = [];
+  const skipped = [];
   let browser = null;
   try {
     browser = await chromium.launch({ headless: true });
@@ -40,13 +41,13 @@ async function runContractTestsPlaywright(componentName, url) {
     const page = await context.newPage();
     await page.goto(url, {
       waitUntil: "domcontentloaded",
-      timeout: 6e4
+      timeout: 9e4
     });
     const mainSelector = componentContract.selectors.trigger || componentContract.selectors.input || componentContract.selectors.container;
     if (!mainSelector) {
       throw new Error(`No main selector (trigger, input, or container) found in contract for ${componentName}`);
     }
-    await page.waitForSelector(mainSelector, { timeout: 6e4 });
+    await page.waitForSelector(mainSelector, { timeout: 9e4 });
     if (componentName === "menu" && componentContract.selectors.trigger) {
       await page.waitForFunction(
         (selector) => {
@@ -54,7 +55,7 @@ async function runContractTestsPlaywright(componentName, url) {
           return trigger && trigger.getAttribute("data-menu-initialized") === "true";
         },
         componentContract.selectors.trigger,
-        { timeout: 5e3 }
+        { timeout: 6e3 }
       ).catch(() => {
         console.warn("Menu initialization signal not detected, continuing with tests...");
       });
@@ -144,11 +145,43 @@ async function runContractTestsPlaywright(componentName, url) {
             if (componentContract.selectors.input) {
               const inputElement = page.locator(componentContract.selectors.input).first();
               await inputElement.clear();
-              await page.waitForTimeout(50);
+              await page.waitForTimeout(100);
             }
           }
         }
       }
+      let shouldSkipTest = false;
+      for (const act of action) {
+        if (act.type === "keypress" && (act.target === "submenuTrigger" || act.target === "submenu")) {
+          const submenuSelector = componentContract.selectors[act.target];
+          if (submenuSelector) {
+            const submenuCount = await page.locator(submenuSelector).count();
+            if (submenuCount === 0) {
+              reporter.reportTest(dynamicTest, "skip", `Skipping test - ${act.target} element not found (optional submenu test)`);
+              shouldSkipTest = true;
+              break;
+            }
+          }
+        }
+      }
+      if (!shouldSkipTest) {
+        for (const assertion of assertions) {
+          if (assertion.target === "submenu" || assertion.target === "submenuTrigger") {
+            const submenuSelector = componentContract.selectors[assertion.target];
+            if (submenuSelector) {
+              const submenuCount = await page.locator(submenuSelector).count();
+              if (submenuCount === 0) {
+                reporter.reportTest(dynamicTest, "skip", `Skipping test - ${assertion.target} element not found (optional submenu test)`);
+                shouldSkipTest = true;
+                break;
+              }
+            }
+          }
+        }
+      }
+      if (shouldSkipTest) {
+        continue;
+      }
       for (const act of action) {
         if (act.type === "focus") {
           const focusSelector = componentContract.selectors[act.target];
@@ -157,7 +190,7 @@ async function runContractTestsPlaywright(componentName, url) {
             continue;
           }
           await page.locator(focusSelector).first().focus();
-          await page.waitForTimeout(50);
+          await page.waitForTimeout(100);
         }
         if (act.type === "type" && act.value) {
           const typeSelector = componentContract.selectors[act.target];
@@ -166,7 +199,7 @@ async function runContractTestsPlaywright(componentName, url) {
             continue;
           }
           await page.locator(typeSelector).first().fill(act.value);
-          await page.waitForTimeout(50);
+          await page.waitForTimeout(100);
         }
         if (act.type === "click") {
           if (act.target === "document") {
@@ -216,7 +249,7 @@ async function runContractTestsPlaywright(componentName, url) {
           if (act.target === "focusable" && ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Escape"].includes(keyValue)) {
             await page.waitForTimeout(100);
             await page.keyboard.press(keyValue);
-            await page.waitForTimeout(50);
+            await page.waitForTimeout(100);
           } else {
             const keypressSelector = componentContract.selectors[act.target];
             if (!keypressSelector) {
@@ -245,7 +278,7 @@ async function runContractTestsPlaywright(componentName, url) {
               continue;
             }
             await relativeElement.hover();
-            await page.waitForTimeout(50);
+            await page.waitForTimeout(100);
           } else {
             const hoverSelector = componentContract.selectors[act.target];
             if (!hoverSelector) {
@@ -253,7 +286,7 @@ async function runContractTestsPlaywright(componentName, url) {
               continue;
             }
             await page.locator(hoverSelector).first().hover();
-            await page.waitForTimeout(50);
+            await page.waitForTimeout(100);
           }
         }
         await page.waitForTimeout(100);
@@ -395,7 +428,7 @@ async function runContractTestsPlaywright(componentName, url) {
   } finally {
     if (browser) await browser.close();
   }
-  return { passes, failures };
+  return { passes, failures, skipped };
 }
 export {
   runContractTestsPlaywright