Introduce waitForFocus DOM Helper

Convinient helper that resolves when a target receives focus. Useful for
verifying keyboard navigation handling and default focus.

Uses the pull based waitUntil helper to support the element not being in
the DOM when invoking the helper.

Alternatives without this helper is asserting `document.activeElement` is
the target. It usually work, but there are cases it focus may happne
async. The element isn't in view yet.

Author: mogstad

addon/src/dom/wait-for-focus.ts

@@ -0,0 +1,61 @@
+import waitUntil from '../wait-until.ts';
+import getElement from './-get-element.ts';
+import {
+  type IDOMElementDescriptor,
+  lookupDescriptorData,
+} from 'dom-element-descriptors';
+import getDescription from './-get-description.ts';
+
+export interface Options {
+  timeout?: number;
+  count?: number | null;
+  timeoutMessage?: string;
+}
+
+/**
+  Used to wait for a particular selector to receive focus. Useful for verifying
+  keyboard navigation handling and default focus behaviour, without having to
+  think about timing issues.
+
+  @param {string|IDOMElementDescriptor} target the selector or DOM element descriptor to wait receiving focus
+  @param {Object} [options] the options to be used
+  @param {number} [options.timeout=1000] the time to wait (in ms) for a match
+  @param {string} [options.timeoutMessage='waitForFocus timed out waiting for selector'] the message to use in the reject on timeout
+  @return {Promise<Element>} resolves when the element received focus
+
+  @example
+  <caption>
+    Waiting until a selector receive focus:
+  </caption>
+  await waitForFocus('.my-selector', { timeout: 2000 })
+*/
+export default function waitForFocus(
+  target: string | IDOMElementDescriptor,
+  options: Options = {},
+): Promise<Element> {
+  return Promise.resolve().then(() => {
+    if (typeof target !== 'string' && !lookupDescriptorData(target)) {
+      throw new Error(
+        'Must pass a selector or DOM element descriptor to `waitFor`.',
+      );
+    }
+
+    const { timeout = 1000 } = options;
+    let { timeoutMessage } = options;
+
+    if (!timeoutMessage) {
+      const description = getDescription(target);
+      timeoutMessage = `waitForFocus timed out waiting for selector "${description}"`;
+    }
+
+    return waitUntil(
+      () => {
+        const element = getElement(target);
+        if (element && element === document.activeElement) {
+          return document.activeElement as HTMLElement;
+        }
+      },
+      { timeout, timeoutMessage },
+    );
+  });
+}

addon/src/index.ts

@@ -74,6 +74,8 @@ export { default as find } from './dom/find.ts';
 export { default as findAll } from './dom/find-all.ts';
 export { default as typeIn } from './dom/type-in.ts';
 export { default as scrollTo } from './dom/scroll-to.ts';
+export { default as waitForFocus } from './dom/wait-for-focus.ts';
+
 export type { Target } from './dom/-target.ts';
 
 // Declaration-merge for our internal purposes.

test-app/tests/unit/dom/wait-for-focus-test.js

@@ -0,0 +1,138 @@
+import { module, test } from 'qunit';
+import {
+  waitForFocus,
+  setupContext,
+  teardownContext,
+  find,
+} from '@ember/test-helpers';
+import hasEmberVersion from '@ember/test-helpers/has-ember-version';
+import { registerDescriptorData } from 'dom-element-descriptors';
+
+module('DOM Helper: waitForFocus', function (hooks) {
+  if (!hasEmberVersion(2, 4)) {
+    return;
+  }
+
+  let context, rootElement;
+
+  hooks.beforeEach(function () {
+    context = {};
+    rootElement = document.getElementById('ember-testing');
+  });
+
+  hooks.afterEach(async function () {
+    // only teardown if setupContext was called
+    if (context.owner) {
+      await teardownContext(context);
+    }
+    document.getElementById('ember-testing').innerHTML = '';
+  });
+
+  class SelectorData {
+    constructor(selector) {
+      this.selector = selector;
+    }
+
+    get elements() {
+      return rootElement.querySelectorAll(this.selector);
+    }
+  }
+
+  class SelectorDescriptor {
+    constructor(selector) {
+      registerDescriptorData(this, new SelectorData(selector));
+    }
+  }
+
+  test('wait for selector without context set', async function (assert) {
+    assert.rejects(
+      waitForFocus('.something'),
+      /Must setup rendering context before attempting to interact with elements/
+    );
+  });
+
+  test('wait for focus using descriptor without context set', async function (assert) {
+    assert.rejects(
+      waitForFocus('.something'),
+      /Must setup rendering context before attempting to interact with elements/
+    );
+  });
+
+  test('wait for focus using descriptor', async function (assert) {
+    rootElement.innerHTML = `<input class="something">`;
+    await setupContext(context);
+
+    let waitPromise = waitForFocus(new SelectorDescriptor('.something'));
+
+    setTimeout(() => {
+      find('.something').focus();
+    }, 10);
+
+    let element = await waitPromise;
+
+    assert.ok(element, 'returns element');
+    assert.equal(element, find('.something'));
+  });
+
+  test('resolves when the element is already focused', async function (assert) {
+    rootElement.innerHTML = `<input class="something">`;
+    await setupContext(context);
+
+    find('.something').focus();
+
+    let waitPromise = waitForFocus('.something');
+    let element = await waitPromise;
+
+    assert.ok(element, 'returns element');
+    assert.equal(element, find('.something'));
+  });
+
+  test('wait for focus using selector', async function (assert) {
+    rootElement.innerHTML = `<input class="something">`;
+
+    await setupContext(context);
+
+    let waitPromise = waitForFocus('.something');
+
+    setTimeout(() => {
+      find('.something').focus();
+    }, 10);
+
+    let element = await waitPromise;
+
+    assert.ok(element, 'returns element');
+    assert.equal(element, find('.something'));
+  });
+
+  test('wait for selector with timeout', async function (assert) {
+    assert.expect(2);
+
+    await setupContext(context);
+
+    let start = Date.now();
+    try {
+      await waitForFocus('.something', { timeout: 100 });
+    } catch (error) {
+      let end = Date.now();
+      assert.ok(end - start >= 100, 'timed out after correct time');
+      assert.equal(
+        error.message,
+        'waitForFocus timed out waiting for selector ".something"'
+      );
+    }
+  });
+
+  test('wait for selector with timeoutMessage', async function (assert) {
+    assert.expect(1);
+
+    await setupContext(context);
+
+    try {
+      await waitForFocus('.something', {
+        timeoutMessage: '.something timed out',
+      });
+    } catch (error) {
+      assert.equal(error.message, '.something timed out');
+    }
+  });
+});

type-tests/api.ts

@@ -1,4 +1,4 @@
-import { expectTypeOf } from 'expect-type';
+import { expectTypeOf } from "expect-type";
 
 import {
   // DOM Interaction Helpers
@@ -28,6 +28,7 @@ import {
   clearRender,
   // Wait Helpers
   waitFor,
+  waitForFocus,
   waitUntil,
   settled,
   isSettled,
@@ -73,12 +74,12 @@ import {
   type Hook,
   type HookLabel,
   type HookUnregister,
-} from '@ember/test-helpers';
-import type { Owner } from '@ember/test-helpers/build-owner';
-import type { DebugInfo as BackburnerDebugInfo } from '@ember/runloop/-private/backburner';
-import type { Resolver as EmberResolver } from '@ember/owner';
-import Application from '@ember/application';
-import type { IDOMElementDescriptor } from 'dom-element-descriptors';
+} from "@ember/test-helpers";
+import type { Owner } from "@ember/test-helpers/build-owner";
+import type { DebugInfo as BackburnerDebugInfo } from "@ember/runloop/-private/backburner";
+import type { Resolver as EmberResolver } from "@ember/owner";
+import Application from "@ember/application";
+import type { IDOMElementDescriptor } from "dom-element-descriptors";
 
 // DOM Interaction Helpers
 expectTypeOf(blur).toEqualTypeOf<(target?: Target) => Promise<void>>();
@@ -123,13 +124,13 @@ expectTypeOf(triggerEvent).toEqualTypeOf<
     target: Target,
     eventType: string,
     options?: Record<string, unknown>,
-    force?: boolean,
+    force?: boolean
   ) => Promise<void>
 >();
 expectTypeOf(triggerKeyEvent).toEqualTypeOf<
   (
     target: Target,
-    eventType: 'keydown' | 'keyup' | 'keypress',
+    eventType: "keydown" | "keyup" | "keypress",
     key: number | string,
     modifiers?: {
       ctrlKey?: boolean;
@@ -150,16 +151,16 @@ expectTypeOf(typeIn).toEqualTypeOf<
 >();
 
 // DOM Query Helpers
-expectTypeOf(find).toEqualTypeOf<Document['querySelector']>();
-expectTypeOf(find('a')).toEqualTypeOf<HTMLAnchorElement | SVGAElement | null>();
-expectTypeOf(find('div')).toEqualTypeOf<HTMLDivElement | null>();
-expectTypeOf(find('circle')).toEqualTypeOf<SVGCircleElement | null>();
-expectTypeOf(find('.corkscrew')).toEqualTypeOf<Element | null>();
+expectTypeOf(find).toEqualTypeOf<Document["querySelector"]>();
+expectTypeOf(find("a")).toEqualTypeOf<HTMLAnchorElement | SVGAElement | null>();
+expectTypeOf(find("div")).toEqualTypeOf<HTMLDivElement | null>();
+expectTypeOf(find("circle")).toEqualTypeOf<SVGCircleElement | null>();
+expectTypeOf(find(".corkscrew")).toEqualTypeOf<Element | null>();
 expectTypeOf(findAll).toEqualTypeOf<(selector: string) => Array<Element>>();
-expectTypeOf(findAll('a')).toEqualTypeOf<(HTMLAnchorElement | SVGAElement)[]>();
-expectTypeOf(findAll('div')).toEqualTypeOf<HTMLDivElement[]>();
-expectTypeOf(findAll('circle')).toEqualTypeOf<SVGCircleElement[]>();
-expectTypeOf(findAll('.corkscrew')).toEqualTypeOf<Element[]>();
+expectTypeOf(findAll("a")).toEqualTypeOf<(HTMLAnchorElement | SVGAElement)[]>();
+expectTypeOf(findAll("div")).toEqualTypeOf<HTMLDivElement[]>();
+expectTypeOf(findAll("circle")).toEqualTypeOf<SVGCircleElement[]>();
+expectTypeOf(findAll(".corkscrew")).toEqualTypeOf<Element[]>();
 expectTypeOf(getRootElement).toEqualTypeOf<() => Element | Document>();
 
 // Routing Helpers
@@ -187,9 +188,19 @@ expectTypeOf(waitFor).toEqualTypeOf<
     }
   ) => Promise<Element | Array<Element>>
 >();
+expectTypeOf(waitForFocus).toEqualTypeOf<
+  (
+    selector: string | IDOMElementDescriptor,
+    options?: {
+      timeout?: number;
+      timeoutMessage?: string;
+    }
+  ) => Promise<Element>
+>();
+
 expectTypeOf(waitUntil).toEqualTypeOf<
   <T>(
-    callback: () => T | void | false | 0 | '' | null | undefined,
+    callback: () => T | void | false | 0 | "" | null | undefined,
     options?: {
       timeout?: number;
       timeoutMessage?: string;