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,59 @@
+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.
+
+  @param {string|IDOMElementDescriptor} target the selector or DOM element descriptor to wait for
+  @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 is rendered:
+  </caption>
+  await waitFor('.my-selector', { timeout: 2000 })
+*/
+export default function waitForFocus(
+  target: string | IDOMElementDescriptor,
+  options: Options = {},
+): Promise<Element | 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');
+    }
+  });
+});