feat: add withAriaSupport option

lib/assertions.ts

@@ -20,6 +20,25 @@ export interface AssertionResult {
   message: string;
 }
 
+export interface DOMAssertionOptions {
+  /**
+   * Whether to also consider `aria-*` attributes in semantic assertion helpers.
+   *
+   * {@link https://www.w3.org/TR/wai-aria-1.1/#state_prop_def}
+   *
+   * @see DOMAssertions#isChecked
+   * @see DOMAssertions#isNotChecked
+   * @see DOMAssertions#isRequired
+   * @see DOMAssertions#isNotRequired
+   * @see DOMAssertions#isDisabled
+   * @see DOMAssertions#isNotDisabled
+   * @see DOMAssertions#isEnabled
+   * @see DOMAssertions#isValid
+   * @see DOMAssertions#isNotValid
+   */
+  withAriaSupport?: boolean;
+}
+
 export interface ExistsOptions {
   count: number;
 }
@@ -32,7 +51,8 @@ export default class DOMAssertions {
   constructor(
     private target: string | Element | null,
     private rootElement: Element | Document,
-    private testContext: Assert
+    private testContext: Assert,
+    private options: DOMAssertionOptions = {}
   ) {}
 
   /**
@@ -106,8 +126,9 @@ export default class DOMAssertions {
    * assert.dom('input.active').isChecked();
    *
    * @see {@link #isNotChecked}
+   * {@link https://www.w3.org/TR/wai-aria-1.1/#aria-checked}
    */
-  isChecked(message?: string): DOMAssertions {
+  isChecked(message?: string, options = {}): DOMAssertions {
     isChecked.call(this, message);
     return this;
   }
@@ -124,6 +145,7 @@ export default class DOMAssertions {
    * assert.dom('input.active').isNotChecked();
    *
    * @see {@link #isChecked}
+   * {@link https://www.w3.org/TR/wai-aria-1.1/#aria-checked}
    */
   isNotChecked(message?: string): DOMAssertions {
     isNotChecked.call(this, message);
@@ -172,9 +194,10 @@ export default class DOMAssertions {
    * assert.dom('input[type="text"]').isRequired();
    *
    * @see {@link #isNotRequired}
+   * {@link https://www.w3.org/TR/wai-aria-1.1/#aria-required}
    */
-  isRequired(message?: string): DOMAssertions {
-    isRequired.call(this, message);
+  isRequired(message?: string, options?: { withAriaSupport?: boolean }): DOMAssertions {
+    isRequired.call(this, message, options);
     return this;
   }
 
@@ -188,9 +211,10 @@ export default class DOMAssertions {
    * assert.dom('input[type="text"]').isNotRequired();
    *
    * @see {@link #isRequired}
+   * {@link https://www.w3.org/TR/wai-aria-1.1/#aria-required}
    */
-  isNotRequired(message?: string): DOMAssertions {
-    isNotRequired.call(this, message);
+  isNotRequired(message?: string, options?: { withAriaSupport?: boolean }): DOMAssertions {
+    isNotRequired.call(this, message, options);
     return this;
   }
 
@@ -207,9 +231,10 @@ export default class DOMAssertions {
    * assert.dom('.input').isValid();
    *
    * @see {@link #isValid}
+   * {@link https://www.w3.org/TR/wai-aria-1.1/#aria-invalid}
    */
-  isValid(message?: string): DOMAssertions {
-    isValid.call(this, message);
+  isValid(message?: string, options?: { withAriaSupport?: boolean }): DOMAssertions {
+    isValid.call(this, message, options);
     return this;
   }
 
@@ -226,9 +251,10 @@ export default class DOMAssertions {
    * assert.dom('.input').isNotValid();
    *
    * @see {@link #isValid}
+   * {@link https://www.w3.org/TR/wai-aria-1.1/#aria-invalid}
    */
-  isNotValid(message?: string): DOMAssertions {
-    isValid.call(this, message, { inverted: true });
+  isNotValid(message?: string, options?: { withAriaSupport?: boolean }): DOMAssertions {
+    isValid.call(this, message, { ...options, inverted: true });
     return this;
   }
 
@@ -577,9 +603,10 @@ export default class DOMAssertions {
    * assert.dom('.foo').isDisabled();
    *
    * @see {@link #isNotDisabled}
+   * {@link https://www.w3.org/TR/wai-aria-1.1/#aria-disabled}
    */
-  isDisabled(message?: string): DOMAssertions {
-    isDisabled.call(this, message);
+  isDisabled(message?: string, options?: { withAriaSupport?: boolean }): DOMAssertions {
+    isDisabled.call(this, message, options);
     return this;
   }
 
@@ -595,14 +622,15 @@ export default class DOMAssertions {
    * assert.dom('.foo').isNotDisabled();
    *
    * @see {@link #isDisabled}
+   * {@link https://www.w3.org/TR/wai-aria-1.1/#aria-disabled}
    */
-  isNotDisabled(message?: string): DOMAssertions {
-    isDisabled.call(this, message, { inverted: true });
+  isNotDisabled(message?: string, options?: { withAriaSupport?: boolean }): DOMAssertions {
+    isDisabled.call(this, message, { ...options, inverted: true });
     return this;
   }
 
-  isEnabled(message?: string): DOMAssertions {
-    return this.isNotDisabled(message);
+  isEnabled(message?: string, options?: { withAriaSupport?: boolean }): DOMAssertions {
+    return this.isNotDisabled(message, options);
   }
 
   /**

lib/assertions/is-checked.ts

@@ -1,6 +1,11 @@
 import elementToString from '../helpers/element-to-string';
 
-export default function checked(message?: string) {
+export default function checked(message?: string, options?: { withAriaSupport?: boolean }) {
+  let {
+    // @TODO: Remove inline default in favor of consistent global default.
+    withAriaSupport = this.options.withAriaSupport ?? true,
+  } = options;
+
   let element = this.findTargetElement();
   if (!element) return;
 
@@ -10,7 +15,7 @@ export default function checked(message?: string) {
   let result = isChecked;
 
   let hasCheckedProp = isChecked || isNotChecked;
-  if (!hasCheckedProp) {
+  if (withAriaSupport && !hasCheckedProp) {
     let ariaChecked = element.getAttribute('aria-checked');
     if (ariaChecked !== null) {
       result = ariaChecked === 'true';

lib/assertions/is-disabled.ts

@@ -1,5 +1,13 @@
-export default function isDisabled(message?: string, options: { inverted?: boolean } = {}) {
-  let { inverted } = options;
+export default function isDisabled(
+  message?: string,
+  options?: { inverted?: boolean; withAriaSupport?: boolean }
+) {
+  let {
+    inverted,
+
+    // @TODO: Remove inline default in favor of consistent global default.
+    withAriaSupport = this.options.withAriaSupport ?? false,
+  } = options;
 
   let element = this.findTargetElement();
   if (!element) return;
@@ -20,6 +28,13 @@ export default function isDisabled(message?: string, options: { inverted?: boole
 
   let result = element.disabled === !inverted;
 
+  if (withAriaSupport && !result) {
+    let ariaDisabled = element.getAttribute('aria-disabled');
+    if (ariaDisabled !== null) {
+      result = ariaDisabled === 'true';
+    }
+  }
+
   let actual =
     element.disabled === false
       ? `Element ${this.targetDescription} is not disabled`

lib/assertions/is-not-checked.ts

@@ -1,6 +1,11 @@
 import elementToString from '../helpers/element-to-string';
 
-export default function notChecked(message?: string) {
+export default function notChecked(message?: string, options?: { withAriaSupport?: boolean }) {
+  let {
+    // @TODO: Remove inline default in favor of consistent global default.
+    withAriaSupport = this.options.withAriaSupport ?? true,
+  } = options;
+
   let element = this.findTargetElement();
   if (!element) return;
 
@@ -10,7 +15,7 @@ export default function notChecked(message?: string) {
   let result = !isChecked;
 
   let hasCheckedProp = isChecked || isNotChecked;
-  if (!hasCheckedProp) {
+  if (withAriaSupport && !hasCheckedProp) {
     let ariaChecked = element.getAttribute('aria-checked');
     if (ariaChecked !== null) {
       result = ariaChecked !== 'true';

lib/assertions/is-not-required.ts

@@ -1,6 +1,11 @@
 import elementToString from '../helpers/element-to-string';
 
-export default function notRequired(message?: string) {
+export default function notRequired(message?: string, options?: { withAriaSupport?: boolean }) {
+  let {
+    // @TODO: Remove inline default in favor of consistent global default.
+    withAriaSupport = this.options.withAriaSupport ?? false,
+  } = options;
+
   let element = this.findTargetElement();
   if (!element) return;
 
@@ -15,6 +20,14 @@ export default function notRequired(message?: string) {
   }
 
   let result = element.required === false;
+
+  if (withAriaSupport && result) {
+    let ariaRequired = element.getAttribute('aria-required');
+    if (ariaRequired !== null) {
+      result = ariaRequired === 'false';
+    }
+  }
+
   let actual = !result ? 'required' : 'not required';
   let expected = 'not required';
 

lib/assertions/is-required.ts

@@ -1,6 +1,11 @@
 import elementToString from '../helpers/element-to-string';
 
-export default function required(message?: string) {
+export default function required(message?: string, options?: { withAriaSupport?: boolean }) {
+  let {
+    // @TODO: Remove inline default in favor of consistent global default.
+    withAriaSupport = this.options.withAriaSupport ?? false,
+  } = options;
+
   let element = this.findTargetElement();
   if (!element) return;
 
@@ -15,6 +20,14 @@ export default function required(message?: string) {
   }
 
   let result = element.required === true;
+
+  if (withAriaSupport && !result) {
+    let ariaRequired = element.getAttribute('aria-required');
+    if (ariaRequired !== null) {
+      result = ariaRequired === 'true';
+    }
+  }
+
   let actual = result ? 'required' : 'not required';
   let expected = 'required';
 

lib/assertions/is-valid.ts

@@ -1,6 +1,16 @@
 import elementToString from '../helpers/element-to-string';
 
-export default function isValid(message?: string, options: { inverted?: boolean } = {}) {
+export default function isValid(
+  message?: string,
+  options: { inverted?: boolean; withAriaSupport?: boolean } = {}
+) {
+  let {
+    inverted,
+
+    // @TODO: Remove inline default in favor of consistent global default.
+    withAriaSupport = this.options.withAriaSupport ?? false,
+  } = options;
+
   let element = this.findTargetElement();
   if (!element) return;
 
@@ -18,9 +28,22 @@ export default function isValid(message?: string, options: { inverted?: boolean
   }
 
   let validity = element.reportValidity() === true;
-  let result = validity === !options.inverted;
+  let result = validity === !inverted;
+
+  // https://www.w3.org/TR/wai-aria-1.1/#aria-invalid
+  if (withAriaSupport && result) {
+    let ariaInvalid = element.getAttribute('aria-invalid');
+    if (ariaInvalid !== null) {
+      if (inverted) {
+        result = ['grammar', 'spelling', 'true'].includes(ariaInvalid);
+      } else {
+        result = ariaInvalid === 'false';
+      }
+    }
+  }
+
   let actual = validity ? 'valid' : 'not valid';
-  let expected = options.inverted ? 'not valid' : 'valid';
+  let expected = inverted ? 'not valid' : 'valid';
 
   if (!message) {
     message = `Element ${elementToString(this.target)} is ${actual}`;

lib/helpers/test-assertions.ts

@@ -1,10 +1,10 @@
-import DOMAssertions, { AssertionResult } from '../assertions';
+import DOMAssertions, { AssertionResult, DOMAssertionOptions } from '../assertions';
 
 export default class TestAssertions {
   public results: AssertionResult[] = [];
 
-  dom(target: string | Element | null, rootElement?: Element) {
-    return new DOMAssertions(target, rootElement || document, this as any);
+  dom(target: string | Element | null, rootElement?: Element, options?: DOMAssertionOptions) {
+    return new DOMAssertions(target, rootElement || document, this as any, options);
   }
 
   pushResult(result: AssertionResult) {

lib/install.ts

@@ -1,8 +1,14 @@
-import DOMAssertions from './assertions';
+import DOMAssertions, { DOMAssertionOptions } from './assertions';
 import { getRootElement } from './root-element';
 
-export default function (assert: Assert) {
-  assert.dom = function (target?: string | Element | null, rootElement?: Element): DOMAssertions {
+export interface InstallOptions extends DOMAssertionOptions {}
+
+export default function (assert: Assert, options: InstallOptions = {}) {
+  assert.dom = function (
+    target?: string | Element | null,
+    rootElement?: Element,
+    options: DOMAssertionOptions = {}
+  ): DOMAssertions {
     if (!isValidRootElement(rootElement)) {
       throw new Error(`${rootElement} is not a valid root element`);
     }
@@ -13,7 +19,7 @@ export default function (assert: Assert) {
       target = rootElement instanceof Element ? rootElement : null;
     }
 
-    return new DOMAssertions(target, rootElement, this);
+    return new DOMAssertions(target, rootElement, this, options);
   };
 
   function isValidRootElement(element: any): element is Element {

lib/qunit-dom-modules.ts

@@ -1,14 +1,14 @@
-import install from './install';
+import install, { InstallOptions } from './install';
 import { overrideRootElement } from './root-element';
 
 export { default as install } from './install';
 
-interface SetupOptions {
+interface SetupOptions extends InstallOptions {
   getRootElement?: () => Element | null;
 }
 
 export function setup(assert: Assert, options: SetupOptions = {}) {
-  install(assert);
+  install(assert, options);
 
   const getRootElement =
     typeof options.getRootElement === 'function'

lib/qunit-dom.ts

@@ -1,13 +1,18 @@
 /* global QUnit */
 
 import type DOMAssertions from './assertions';
+import type { DOMAssertionOptions } from './assertions';
 import install from './install';
 
 export { setup } from './qunit-dom-modules';
 
 declare global {
   interface Assert {
-    dom(target?: string | Element | null, rootElement?: Element): DOMAssertions;
+    dom(
+      target?: string | Element | null,
+      rootElement?: Element,
+      options?: DOMAssertionOptions
+    ): DOMAssertions;
   }
 }