feat(dom): toHaveAccessibleDescription

packages/dom/package.json

@@ -35,6 +35,7 @@
     "test": "NODE_ENV=test mocha"
   },
   "dependencies": {
+    "dom-accessibility-api": "^0.5.16",
     "fast-deep-equal": "^3.1.3",
     "tslib": "^2.8.1"
   },

packages/dom/src/lib/ElementAssertion.ts

@@ -1,7 +1,12 @@
 import { Assertion, AssertionError } from "@assertive-ts/core";
+import { computeAccessibleDescription } from "dom-accessibility-api";
 import equal from "fast-deep-equal";
 
-import { getAccessibleDescription, isValidAriaPressed } from "./helpers/accessibility";
+import {
+  describeAccessibleExpectation,
+  isValidAriaPressed,
+  matchesAccessibleExpectation,
+} from "./helpers/accessibility";
 import { isButtonElement, isElementEmpty, normalizeHtml } from "./helpers/dom";
 import { getExpectedAndReceivedStyles } from "./helpers/styles";
 
@@ -293,63 +298,51 @@ export class ElementAssertion<T extends Element> extends Assertion<T> {
   /**
    * Asserts that the element has an accessible description.
    *
-   * The accessible description is computed from the `aria-describedby`
-   * attribute, which references one or more elements by ID. The text
-   * content of those elements is combined to form the description.
+   * The accessible description is computed following the
+   * [accname](https://www.w3.org/TR/accname/) specification, taking
+   * into account `aria-describedby`, `aria-description`, and `title`,
+   * among others.
    *
    * @example
    * ```
    * // Check if element has any description
-   * expect(element).toHaveDescription();
+   * expect(element).toHaveAccessibleDescription();
    *
    * // Check if element has specific description text
-   * expect(element).toHaveDescription('Expected description text');
+   * expect(element).toHaveAccessibleDescription("Expected description text");
    *
    * // Check if element description matches a regex pattern
-   * expect(element).toHaveDescription(/description pattern/i);
+   * expect(element).toHaveAccessibleDescription(/description pattern/i);
    * ```
    *
    * @param expectedDescription
    * - Optional expected description (string or RegExp).
    * @returns the assertion instance.
    */
-
-  public toHaveDescription(expectedDescription?: RegExp | string): this {
-    const description = getAccessibleDescription(this.actual);
+  public toHaveAccessibleDescription(expectedDescription?: RegExp | string): this {
+    const description = computeAccessibleDescription(this.actual);
     const hasExpectedValue = expectedDescription !== undefined;
 
-    const matchesExpectation = (desc: string): boolean => {
-      if (!hasExpectedValue) {
-        return Boolean(desc);
-      }
-      return expectedDescription instanceof RegExp
-        ? expectedDescription.test(desc)
-        : desc === expectedDescription;
-    };
-
-    const formatExpectation = (isRegExp: boolean): string =>
-      isRegExp ? `matching ${expectedDescription}` : `"${expectedDescription}"`;
+    const expectation = describeAccessibleExpectation(expectedDescription);
 
     const error = new AssertionError({
       actual: description,
       expected: expectedDescription,
       message: hasExpectedValue
-        ? `Expected the element to have description ${formatExpectation(expectedDescription instanceof RegExp)}, `
-        + `but received "${description}"`
-        : "Expected the element to have a description",
+        ? `Expected the element to have accessible description ${expectation}, but received "${description}"`
+        : "Expected the element to have an accessible description",
     });
 
     const invertedError = new AssertionError({
       actual: description,
       expected: expectedDescription,
       message: hasExpectedValue
-        ? `Expected the element NOT to have description ${formatExpectation(expectedDescription instanceof RegExp)}, `
-        + `but received "${description}"`
-        : `Expected the element NOT to have a description, but received "${description}"`,
+        ? `Expected the element NOT to have accessible description ${expectation}, but received "${description}"`
+        : `Expected the element NOT to have an accessible description, but received "${description}"`,
     });
 
     return this.execute({
-      assertWhen: matchesExpectation(description),
+      assertWhen: matchesAccessibleExpectation(description, expectedDescription),
       error,
       invertedError,
     });

packages/dom/src/lib/helpers/accessibility.ts

@@ -1,35 +1,24 @@
-function normalizeText(text: string): string {
-  return text.replace(/\s+/g, " ").trim();
+export function isValidAriaPressed(element: Element): boolean {
+  const pressedAttribute = element.getAttribute("aria-pressed");
+  return pressedAttribute !== null && ["true", "false", "mixed"].includes(pressedAttribute);
 }
 
-export function getAccessibleDescription(actual: Element): string {
-  const ariaDescribedBy = actual.getAttribute("aria-describedby");
-
-  if (!ariaDescribedBy) {
-    return "";
+export function matchesAccessibleExpectation(actual: string, expected?: RegExp | string): boolean {
+  if (expected === undefined) {
+    return Boolean(actual);
   }
 
-  const descriptionIds = ariaDescribedBy.split(/\s+/).filter(Boolean);
-
-  const getElementText = (id: string): null | string => {
-    const element = actual.ownerDocument.getElementById(id);
-
-    if (!element || !element.textContent) {
-      return null;
-    }
-
-    return element.textContent;
-  };
-
-  const combinedText = descriptionIds
-    .map(getElementText)
-    .filter((text): text is string => text !== null)
-    .join(" ");
-
-  return normalizeText(combinedText);
+  return expected instanceof RegExp
+    ? expected.test(actual)
+    : actual === expected;
 }
 
-export function isValidAriaPressed(element: Element): boolean {
-  const pressedAttribute = element.getAttribute("aria-pressed");
-  return pressedAttribute !== null && ["true", "false", "mixed"].includes(pressedAttribute);
+export function describeAccessibleExpectation(expected?: RegExp | string): string {
+  if (expected === undefined) {
+    return "";
+  }
+
+  return expected instanceof RegExp
+    ? `matching ${expected}`
+    : `"${expected}"`;
 }

packages/dom/src/lib/helpers/dom.ts

@@ -5,6 +5,8 @@ export function isElementEmpty(element: Element): boolean {
   return nonCommentChildNodes.length === 0;
 }
 
+// Callers are internal: the public assertions already reject non-string
+// and empty `htmlText` values before reaching here.
 export function normalizeHtml(htmlText: string, ownerDocument: Document): string {
   const div = ownerDocument.createElement("div");
   div.innerHTML = htmlText;

packages/dom/test/unit/lib/ElementAssertion.test.tsx

@@ -469,19 +469,22 @@ describe("[Unit] ElementAssertion.test.ts", () => {
     });
   });
 
-  describe(".toHaveDescription", () => {
+  describe(".toHaveAccessibleDescription", () => {
     context("when checking for any description", () => {
       context("when the element has a description", () => {
         it("returns the assertion instance", () => {
           const { getByTestId } = render(<DescriptionTestComponent />);
           const button = getByTestId("button-single");
           const test = new ElementAssertion(button);
 
-          expect(test.toHaveDescription()).toBeEqual(test);
+          expect(test.toHaveAccessibleDescription()).toBeEqual(test);
 
-          expect(() => test.not.toHaveDescription())
+          expect(() => test.not.toHaveAccessibleDescription())
             .toThrowError(AssertionError)
-            .toHaveMessage('Expected the element NOT to have a description, but received "This is a description"');
+            .toHaveMessage(
+              "Expected the element NOT to have an accessible description, "
+              + 'but received "This is a description"',
+            );
         });
       });
 
@@ -491,11 +494,11 @@ describe("[Unit] ElementAssertion.test.ts", () => {
           const button = getByTestId("button-no-description");
           const test = new ElementAssertion(button);
 
-          expect(() => test.toHaveDescription())
+          expect(() => test.toHaveAccessibleDescription())
             .toThrowError(AssertionError)
-            .toHaveMessage("Expected the element to have a description");
+            .toHaveMessage("Expected the element to have an accessible description");
 
-          expect(test.not.toHaveDescription()).toBeEqual(test);
+          expect(test.not.toHaveAccessibleDescription()).toBeEqual(test);
         });
       });
     });
@@ -507,12 +510,12 @@ describe("[Unit] ElementAssertion.test.ts", () => {
           const button = getByTestId("button-single");
           const test = new ElementAssertion(button);
 
-          expect(test.toHaveDescription("This is a description")).toBeEqual(test);
+          expect(test.toHaveAccessibleDescription("This is a description")).toBeEqual(test);
 
-          expect(() => test.not.toHaveDescription("This is a description"))
+          expect(() => test.not.toHaveAccessibleDescription("This is a description"))
             .toThrowError(AssertionError)
             .toHaveMessage(
-              'Expected the element NOT to have description "This is a description", '
+              'Expected the element NOT to have accessible description "This is a description", '
               + 'but received "This is a description"',
             );
         });
@@ -524,12 +527,12 @@ describe("[Unit] ElementAssertion.test.ts", () => {
           const button = getByTestId("button-multiple");
           const test = new ElementAssertion(button);
 
-          expect(test.toHaveDescription("This is a description Additional info")).toBeEqual(test);
+          expect(test.toHaveAccessibleDescription("This is a description Additional info")).toBeEqual(test);
 
-          expect(() => test.not.toHaveDescription("This is a description Additional info"))
+          expect(() => test.not.toHaveAccessibleDescription("This is a description Additional info"))
             .toThrowError(AssertionError)
             .toHaveMessage(
-              'Expected the element NOT to have description "This is a description Additional info", '
+              'Expected the element NOT to have accessible description "This is a description Additional info", '
               + 'but received "This is a description Additional info"',
             );
         });
@@ -541,13 +544,14 @@ describe("[Unit] ElementAssertion.test.ts", () => {
           const button = getByTestId("button-single");
           const test = new ElementAssertion(button);
 
-          expect(() => test.toHaveDescription("Wrong description"))
+          expect(() => test.toHaveAccessibleDescription("Wrong description"))
             .toThrowError(AssertionError)
             .toHaveMessage(
-              'Expected the element to have description "Wrong description", but received "This is a description"',
+              'Expected the element to have accessible description "Wrong description", '
+              + 'but received "This is a description"',
             );
 
-          expect(test.not.toHaveDescription("Wrong description")).toBeEqual(test);
+          expect(test.not.toHaveAccessibleDescription("Wrong description")).toBeEqual(test);
         });
       });
     });
@@ -559,12 +563,12 @@ describe("[Unit] ElementAssertion.test.ts", () => {
           const button = getByTestId("button-single");
           const test = new ElementAssertion(button);
 
-          expect(test.toHaveDescription(/description/i)).toBeEqual(test);
+          expect(test.toHaveAccessibleDescription(/description/i)).toBeEqual(test);
 
-          expect(() => test.not.toHaveDescription(/description/i))
+          expect(() => test.not.toHaveAccessibleDescription(/description/i))
             .toThrowError(AssertionError)
             .toHaveMessage(
-              "Expected the element NOT to have description matching /description/i, "
+              "Expected the element NOT to have accessible description matching /description/i, "
               + 'but received "This is a description"',
             );
         });
@@ -576,14 +580,14 @@ describe("[Unit] ElementAssertion.test.ts", () => {
           const button = getByTestId("button-single");
           const test = new ElementAssertion(button);
 
-          expect(() => test.toHaveDescription(/wrong pattern/))
+          expect(() => test.toHaveAccessibleDescription(/wrong pattern/))
             .toThrowError(AssertionError)
             .toHaveMessage(
-              "Expected the element to have description matching /wrong pattern/, "
+              "Expected the element to have accessible description matching /wrong pattern/, "
               + 'but received "This is a description"',
             );
 
-          expect(test.not.toHaveDescription(/wrong pattern/)).toBeEqual(test);
+          expect(test.not.toHaveAccessibleDescription(/wrong pattern/)).toBeEqual(test);
         });
       });
     });

yarn.lock

@@ -51,6 +51,7 @@ __metadata:
     "@types/react": "npm:^18.3.3"
     "@types/react-dom": "npm:^18.3.0"
     "@types/react-test-renderer": "npm:^18"
+    dom-accessibility-api: "npm:^0.5.16"
     fast-deep-equal: "npm:^3.1.3"
     jsdom: "npm:^24.0.0"
     jsdom-global: "npm:^3.0.2"
@@ -5655,7 +5656,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"dom-accessibility-api@npm:^0.5.9":
+"dom-accessibility-api@npm:^0.5.16, dom-accessibility-api@npm:^0.5.9":
   version: 0.5.16
   resolution: "dom-accessibility-api@npm:0.5.16"
   checksum: 10/377b4a7f9eae0a5d72e1068c369c99e0e4ca17fdfd5219f3abd32a73a590749a267475a59d7b03a891f9b673c27429133a818c44b2e47e32fec024b34274e2ca