diff --git a/packages/dom/src/lib/ElementAssertion.ts b/packages/dom/src/lib/ElementAssertion.ts index bac4feb..afeb032 100644 --- a/packages/dom/src/lib/ElementAssertion.ts +++ b/packages/dom/src/lib/ElementAssertion.ts @@ -4,11 +4,14 @@ import equal from "fast-deep-equal"; import { describeAccessibleExpectation, + isValidAriaCheckedStrict, isValidAriaPressed, matchesAccessibleExpectation, } from "./helpers/accessibility"; import { isButtonElement, + isCheckableInput, + isCheckboxInput, isElementEmpty, isElementOrAncestorDisabled, normalizeHtml, @@ -432,6 +435,88 @@ export class ElementAssertion extends Assertion { }); } + /** + * Asserts that the element is checked. + * + * Valid for ``, ``, or elements + * with a valid `aria-checked` attribute ("true" or "false") and + * a checkable role (`checkbox`, `radio`, or `switch`). + * + * @example + * // Native checkbox + * expect(element).toBeChecked(); + * expect(element).not.toBeChecked(); + * + * // ARIA checkbox + * expect(element).toBeChecked(); // when aria-checked="true" + * + * @returns the assertion instance. + */ + public toBeChecked(): this { + const isNativeCheckable = isCheckableInput(this.actual); + const isAriaCheckable = isValidAriaCheckedStrict(this.actual); + if (!isNativeCheckable && !isAriaCheckable) { + throw new Error( + "Only checkbox/radio inputs or valid aria-checked elements can be used with .toBeChecked()", + ); + } + const isChecked = isNativeCheckable + ? (this.actual as unknown as HTMLInputElement).checked + : this.actual.getAttribute("aria-checked") === "true"; + const error = new AssertionError({ + actual: this.actual, + message: "Expected the element to be checked", + }); + const invertedError = new AssertionError({ + actual: this.actual, + message: "Expected the element to NOT be checked", + }); + return this.execute({ + assertWhen: isChecked, + error, + invertedError, + }); + } + + /** + * Asserts that the element is partially checked (indeterminate). + * + * Valid for `` or elements with `role="checkbox"` + * and `aria-checked="mixed"`. + * + * @example + * expect(element).toBePartiallyChecked(); + * expect(element).not.toBePartiallyChecked(); + * + * @returns the assertion instance. + */ + public toBePartiallyChecked(): this { + const isNativeCheckbox = isCheckboxInput(this.actual); + const isAriaCheckbox = this.actual.getAttribute("role") === "checkbox"; + if (!isNativeCheckbox && !isAriaCheckbox) { + throw new Error( + "Only checkbox inputs or checkbox-role elements can be used with .toBePartiallyChecked()", + ); + } + const isPartiallyChecked = isNativeCheckbox + ? (this.actual as unknown as HTMLInputElement).indeterminate + || this.actual.getAttribute("aria-checked") === "mixed" + : this.actual.getAttribute("aria-checked") === "mixed"; + const error = new AssertionError({ + actual: this.actual, + message: "Expected the element to be partially checked", + }); + const invertedError = new AssertionError({ + actual: this.actual, + message: "Expected the element to NOT be partially checked", + }); + return this.execute({ + assertWhen: isPartiallyChecked, + error, + invertedError, + }); + } + /** * Asserts that the element contains the specified HTML. * diff --git a/packages/dom/src/lib/helpers/accessibility.ts b/packages/dom/src/lib/helpers/accessibility.ts index 421ac83..7cf0942 100644 --- a/packages/dom/src/lib/helpers/accessibility.ts +++ b/packages/dom/src/lib/helpers/accessibility.ts @@ -3,6 +3,14 @@ export function isValidAriaPressed(element: Element): boolean { return pressedAttribute !== null && ["true", "false", "mixed"].includes(pressedAttribute); } +export function isValidAriaCheckedStrict(element: Element): boolean { + const checkedAttribute = element.getAttribute("aria-checked"); + const role = element.getAttribute("role") ?? ""; + return ["checkbox", "radio", "switch"].includes(role) + && checkedAttribute !== null + && ["true", "false"].includes(checkedAttribute); +} + export function matchesAccessibleExpectation(actual: string, expected?: RegExp | string): boolean { if (expected === undefined) { return Boolean(actual); diff --git a/packages/dom/src/lib/helpers/dom.ts b/packages/dom/src/lib/helpers/dom.ts index cf2d4c5..310f770 100644 --- a/packages/dom/src/lib/helpers/dom.ts +++ b/packages/dom/src/lib/helpers/dom.ts @@ -28,6 +28,18 @@ export function isButtonElement(element: Element): boolean { return isNativeButton || hasButtonRole; } +export function isCheckableInput(element: Element): boolean { + const tagName = element.tagName.toLowerCase(); + const type = element.getAttribute("type"); + return tagName === "input" && (type === "checkbox" || type === "radio"); +} + +export function isCheckboxInput(element: Element): boolean { + const tagName = element.tagName.toLowerCase(); + const type = element.getAttribute("type"); + return tagName === "input" && type === "checkbox"; +} + const FORM_TAGS = [ "fieldset", "input", diff --git a/packages/dom/test/unit/lib/ElementAssertion.test.tsx b/packages/dom/test/unit/lib/ElementAssertion.test.tsx index 08bbcea..e370b9a 100644 --- a/packages/dom/test/unit/lib/ElementAssertion.test.tsx +++ b/packages/dom/test/unit/lib/ElementAssertion.test.tsx @@ -3,6 +3,7 @@ import { render } from "@testing-library/react"; import { ElementAssertion } from "../../../src/lib/ElementAssertion"; +import { CheckedTestComponent } from "./fixtures/CheckedTestComponent"; import { DisabledTestComponent } from "./fixtures/DisabledTestComponent"; import { HaveClassTest } from "./fixtures/HaveClassTest"; import { NestedElementsTest } from "./fixtures/NestedElementsTest"; @@ -830,6 +831,274 @@ describe("[Unit] ElementAssertion.test.ts", () => { }); }); + describe(".toBeChecked", () => { + context("when the element is a native checkbox", () => { + context("when the checkbox is checked", () => { + it("returns the assertion instance", () => { + const { getByTestId } = render(); + const checkbox = getByTestId("checkbox-checked"); + const test = new ElementAssertion(checkbox); + + expect(test.toBeChecked()).toBeEqual(test); + + expect(() => test.not.toBeChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to NOT be checked"); + }); + }); + + context("when the checkbox is not checked", () => { + it("throws an assertion error", () => { + const { getByTestId } = render(); + const checkbox = getByTestId("checkbox-unchecked"); + const test = new ElementAssertion(checkbox); + + expect(() => test.toBeChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to be checked"); + + expect(test.not.toBeChecked()).toBeEqual(test); + }); + }); + }); + + context("when the element is a native radio", () => { + context("when the radio is checked", () => { + it("returns the assertion instance", () => { + const { getByTestId } = render(); + const radio = getByTestId("radio-checked"); + const test = new ElementAssertion(radio); + + expect(test.toBeChecked()).toBeEqual(test); + + expect(() => test.not.toBeChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to NOT be checked"); + }); + }); + + context("when the radio is not checked", () => { + it("throws an assertion error", () => { + const { getByTestId } = render(); + const radio = getByTestId("radio-unchecked"); + const test = new ElementAssertion(radio); + + expect(() => test.toBeChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to be checked"); + + expect(test.not.toBeChecked()).toBeEqual(test); + }); + }); + }); + + context("when the element has role=\"checkbox\" with aria-checked", () => { + context("when aria-checked is \"true\"", () => { + it("returns the assertion instance", () => { + const { getByTestId } = render(); + const div = getByTestId("aria-checkbox-checked"); + const test = new ElementAssertion(div); + + expect(test.toBeChecked()).toBeEqual(test); + + expect(() => test.not.toBeChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to NOT be checked"); + }); + }); + + context("when aria-checked is \"false\"", () => { + it("throws an assertion error", () => { + const { getByTestId } = render(); + const div = getByTestId("aria-checkbox-unchecked"); + const test = new ElementAssertion(div); + + expect(() => test.toBeChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to be checked"); + + expect(test.not.toBeChecked()).toBeEqual(test); + }); + }); + }); + + context("when the element has role=\"switch\" with aria-checked", () => { + context("when aria-checked is \"true\"", () => { + it("returns the assertion instance", () => { + const { getByTestId } = render(); + const div = getByTestId("aria-switch-checked"); + const test = new ElementAssertion(div); + + expect(test.toBeChecked()).toBeEqual(test); + + expect(() => test.not.toBeChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to NOT be checked"); + }); + }); + + context("when aria-checked is \"false\"", () => { + it("throws an assertion error", () => { + const { getByTestId } = render(); + const div = getByTestId("aria-switch-unchecked"); + const test = new ElementAssertion(div); + + expect(() => test.toBeChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to be checked"); + + expect(test.not.toBeChecked()).toBeEqual(test); + }); + }); + }); + + context("when the element has role=\"radio\" with aria-checked", () => { + context("when aria-checked is \"true\"", () => { + it("returns the assertion instance", () => { + const { getByTestId } = render(); + const div = getByTestId("aria-radio-checked"); + const test = new ElementAssertion(div); + + expect(test.toBeChecked()).toBeEqual(test); + + expect(() => test.not.toBeChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to NOT be checked"); + }); + }); + + context("when aria-checked is \"false\"", () => { + it("throws an assertion error", () => { + const { getByTestId } = render(); + const div = getByTestId("aria-radio-unchecked"); + const test = new ElementAssertion(div); + + expect(() => test.toBeChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to be checked"); + + expect(test.not.toBeChecked()).toBeEqual(test); + }); + }); + }); + + context("when the element has aria-checked but no valid checkable role", () => { + it("throws a plain Error", () => { + const { getByTestId } = render(); + const div = getByTestId("non-checkable-element"); + (div).setAttribute("aria-checked", "true"); + const test = new ElementAssertion(div); + + expect(() => test.toBeChecked()).toThrowError(Error); + }); + }); + + context("when the element is not a valid checkable element", () => { + it("throws a plain Error", () => { + const { getByTestId } = render(); + const div = getByTestId("non-checkable-element"); + const test = new ElementAssertion(div); + + expect(() => test.toBeChecked()).toThrowError(Error); + }); + }); + }); + + describe(".toBePartiallyChecked", () => { + context("when the element is a native checkbox", () => { + context("when the checkbox is indeterminate", () => { + it("returns the assertion instance", () => { + const { getByTestId } = render(); + const checkbox = getByTestId("checkbox-indeterminate") as HTMLInputElement; + checkbox.indeterminate = true; + const test = new ElementAssertion(checkbox); + + expect(test.toBePartiallyChecked()).toBeEqual(test); + + expect(() => test.not.toBePartiallyChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to NOT be partially checked"); + }); + }); + + context("when the checkbox is not indeterminate", () => { + it("throws an assertion error", () => { + const { getByTestId } = render(); + const checkbox = getByTestId("checkbox-checked"); + const test = new ElementAssertion(checkbox); + + expect(() => test.toBePartiallyChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to be partially checked"); + + expect(test.not.toBePartiallyChecked()).toBeEqual(test); + }); + }); + }); + + context("when the element has role=\"checkbox\" with aria-checked", () => { + context("when aria-checked is \"mixed\"", () => { + it("returns the assertion instance", () => { + const { getByTestId } = render(); + const div = getByTestId("aria-checkbox-mixed"); + const test = new ElementAssertion(div); + + expect(test.toBePartiallyChecked()).toBeEqual(test); + + expect(() => test.not.toBePartiallyChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to NOT be partially checked"); + }); + }); + + context("when aria-checked is \"true\"", () => { + it("throws an assertion error", () => { + const { getByTestId } = render(); + const div = getByTestId("aria-checkbox-checked"); + const test = new ElementAssertion(div); + + expect(() => test.toBePartiallyChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to be partially checked"); + + expect(test.not.toBePartiallyChecked()).toBeEqual(test); + }); + }); + + context("when aria-checked is \"false\"", () => { + it("throws an assertion error", () => { + const { getByTestId } = render(); + const div = getByTestId("aria-checkbox-unchecked"); + const test = new ElementAssertion(div); + + expect(() => test.toBePartiallyChecked()) + .toThrowError(AssertionError) + .toHaveMessage("Expected the element to be partially checked"); + + expect(test.not.toBePartiallyChecked()).toBeEqual(test); + }); + }); + }); + + context("when the element is not a valid checkbox element", () => { + it("throws a plain Error for a plain div", () => { + const { getByTestId } = render(); + const div = getByTestId("non-checkable-element"); + const test = new ElementAssertion(div); + + expect(() => test.toBePartiallyChecked()).toThrowError(Error); + }); + + it("throws a plain Error for a radio input", () => { + const { getByTestId } = render(); + const radio = getByTestId("radio-checked"); + const test = new ElementAssertion(radio); + + expect(() => test.toBePartiallyChecked()).toThrowError(Error); + }); + }); + }); + describe(".toContainHTML", () => { context("when the element contains the expected HTML", () => { it("returns the assertion instance", () => { diff --git a/packages/dom/test/unit/lib/fixtures/CheckedTestComponent.tsx b/packages/dom/test/unit/lib/fixtures/CheckedTestComponent.tsx new file mode 100644 index 0000000..23a776e --- /dev/null +++ b/packages/dom/test/unit/lib/fixtures/CheckedTestComponent.tsx @@ -0,0 +1,34 @@ +import type { ReactElement } from "react"; + +export function CheckedTestComponent(): ReactElement { + return ( +
+ {/* Native checkbox variants */} + + + + {/* Native radio variants */} + + + + {/* ARIA checkbox variants */} +
{"Checked"}
+
{"Unchecked"}
+
{"Mixed"}
+ + {/* ARIA radio variants */} +
{"Checked"}
+
{"Unchecked"}
+ + {/* ARIA switch variants */} +
{"On"}
+
{"Off"}
+ + {/* Element for indeterminate test (set programmatically in test) */} + + + {/* Invalid elements */} +
{"Not checkable"}
+
+ ); +}