feat(dom): toContainHTML

packages/dom/src/lib/ElementAssertion.ts

@@ -2,7 +2,7 @@ import { Assertion, AssertionError } from "@assertive-ts/core";
 import equal from "fast-deep-equal";
 
 import { getAccessibleDescription, isValidAriaPressed } from "./helpers/accessibility";
-import { isButtonElement, isElementEmpty } from "./helpers/dom";
+import { isButtonElement, isElementEmpty, normalizeHtml } from "./helpers/dom";
 import { getExpectedAndReceivedStyles } from "./helpers/styles";
 
 export class ElementAssertion<T extends Element> extends Assertion<T> {
@@ -434,6 +434,51 @@ export class ElementAssertion<T extends Element> extends Assertion<T> {
     });
   }
 
+  /**
+   * Asserts that the element contains the specified HTML.
+   *
+   * The expected HTML is normalized through a detached element before
+   * comparison, so differences in attribute quoting (single vs double quotes),
+   * tag case, and whitespace between attributes are ignored. Attribute ordering
+   * and whitespace within text content are still significant.
+   *
+   * @example
+   * ```
+   * expect(container).toContainHTML('<span>Hello</span>');
+   * expect(container).toContainHTML("<div class='foo'>Bar</div>");
+   * ```
+   *
+   * @param htmlText The HTML text that should be contained in the element
+   * @returns the assertion instance.
+   */
+  public toContainHTML(htmlText: string): this {
+    if (typeof htmlText !== "string") {
+      throw new Error(`.toContainHTML() expects a string value, got ${typeof htmlText}`);
+    }
+
+    if (htmlText === "") {
+      throw new Error(".toContainHTML() expects a non-empty string");
+    }
+
+    const error = new AssertionError({
+      actual: this.actual,
+      expected: htmlText,
+      message: `Expected the element to contain HTML: ${htmlText}`,
+    });
+
+    const invertedError = new AssertionError({
+      actual: this.actual,
+      expected: htmlText,
+      message: `Expected the element NOT to contain HTML: ${htmlText}`,
+    });
+
+    return this.execute({
+      assertWhen: this.actual.outerHTML.includes(normalizeHtml(htmlText, this.actual.ownerDocument)),
+      error,
+      invertedError,
+    });
+  }
+
   /**
    * Helper method to assert the presence or absence of class names.
    *

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

@@ -5,6 +5,13 @@ export function isElementEmpty(element: Element): boolean {
   return nonCommentChildNodes.length === 0;
 }
 
+export function normalizeHtml(htmlText: string, ownerDocument: Document): string {
+  const div = ownerDocument.createElement("div");
+  div.innerHTML = htmlText;
+
+  return div.innerHTML;
+}
+
 export function isButtonElement(element: Element): boolean {
   const roles = (element.getAttribute("role") || "")
     .split(" ")

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

@@ -8,6 +8,7 @@ import { NestedElementsTest } from "./fixtures/NestedElementsTest";
 import { PressedTestComponent } from "./fixtures/PressedTestComponent";
 import { SimpleTest } from "./fixtures/SimpleTest";
 import { WithAttributesTest } from "./fixtures/WithAttributesTest";
+import { ContainHtmlTestComponent } from "./fixtures/containHtmlTestComponent";
 import { DescriptionTestComponent } from "./fixtures/descriptionTestComponent";
 import { FocusTestComponent } from "./fixtures/focusTestComponent";
 
@@ -823,4 +824,84 @@ describe("[Unit] ElementAssertion.test.ts", () => {
       });
     });
   });
+
+  describe(".toContainHTML", () => {
+    context("when the element contains the expected HTML", () => {
+      it("returns the assertion instance", () => {
+        const { getByTestId } = render(<ContainHtmlTestComponent />);
+        const container = getByTestId("container");
+        const test = new ElementAssertion(container);
+
+        expect(test.toContainHTML('<span data-testid="child-span">Hello World</span>')).toBeEqual(test);
+
+        expect(() => test.not.toContainHTML('<span data-testid="child-span">Hello World</span>'))
+          .toThrowError(AssertionError)
+          .toHaveMessage('Expected the element NOT to contain HTML: <span data-testid="child-span">Hello World</span>');
+      });
+    });
+
+    context("when the element contains nested HTML", () => {
+      it("returns the assertion instance", () => {
+        const { getByTestId } = render(<ContainHtmlTestComponent />);
+        const container = getByTestId("container");
+        const test = new ElementAssertion(container);
+
+        expect(test.toContainHTML("<p>Nested content</p>")).toBeEqual(test);
+
+        expect(() => test.not.toContainHTML("<p>Nested content</p>"))
+          .toThrowError(AssertionError)
+          .toHaveMessage("Expected the element NOT to contain HTML: <p>Nested content</p>");
+      });
+    });
+
+    context("when the expected HTML differs only in formatting", () => {
+      it("normalizes quotes and tag case before comparing", () => {
+        const { getByTestId } = render(<ContainHtmlTestComponent />);
+        const container = getByTestId("container");
+        const test = new ElementAssertion(container);
+
+        expect(test.toContainHTML("<span data-testid='child-span'>Hello World</span>")).toBeEqual(test);
+        expect(test.toContainHTML('<SPAN data-testid="child-span">Hello World</SPAN>')).toBeEqual(test);
+        expect(test.toContainHTML("<div  class='nested'><p>Nested content</p></div>")).toBeEqual(test);
+      });
+    });
+
+    context("when the element does not contain the expected HTML", () => {
+      it("throws an assertion error", () => {
+        const { getByTestId } = render(<ContainHtmlTestComponent />);
+        const container = getByTestId("container");
+        const test = new ElementAssertion(container);
+
+        expect(() => test.toContainHTML("<div>Not present</div>"))
+          .toThrowError(AssertionError)
+          .toHaveMessage("Expected the element to contain HTML: <div>Not present</div>");
+
+        expect(test.not.toContainHTML("<div>Not present</div>")).toBeEqual(test);
+      });
+    });
+
+    context("when a non-string value is passed", () => {
+      it("throws an error", () => {
+        const { getByTestId } = render(<ContainHtmlTestComponent />);
+        const container = getByTestId("container");
+        const test = new ElementAssertion(container);
+
+        expect(() => test.toContainHTML(123 as unknown as string))
+          .toThrowError(Error)
+          .toHaveMessage(".toContainHTML() expects a string value, got number");
+      });
+    });
+
+    context("when an empty string is passed", () => {
+      it("throws an error", () => {
+        const { getByTestId } = render(<ContainHtmlTestComponent />);
+        const container = getByTestId("container");
+        const test = new ElementAssertion(container);
+
+        expect(() => test.toContainHTML(""))
+          .toThrowError(Error)
+          .toHaveMessage(".toContainHTML() expects a non-empty string");
+      });
+    });
+  });
 });

packages/dom/test/unit/lib/fixtures/containHtmlTestComponent.tsx

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+
+export function ContainHtmlTestComponent(): ReactElement {
+  return (
+    <div data-testid="container">
+      <span data-testid="child-span">{"Hello World"}</span>
+      <div className="nested">
+        <p>{"Nested content"}</p>
+      </div>
+    </div>
+  );
+}