feat: add wait feature

depracates: waitForDomChange and waitForElement"

Author: timdeschryver

projects/testing-library/src/lib/models.ts

@@ -6,6 +6,7 @@ import {
   FireObject,
   Queries,
   queries,
+  wait,
   waitForElement,
   waitForElementToBeRemoved,
   waitForDomChange,
@@ -67,13 +68,15 @@ export interface RenderResult<ComponentType, WrapperType = ComponentType>
    */
   rerender: (componentProperties: Partial<ComponentType>) => void;
   /**
+   * @deprecated `waitForDomChange` has been deprecated. Use `wait` instead: https://testing-library.com/docs/dom-testing-library/api-async#wait.
    * @description
    * Wait for the DOM to change.
    *
    * For more info see https://testing-library.com/docs/dom-testing-library/api-async#waitfordomchange
    */
   waitForDomChange: typeof waitForDomChange;
   /**
+   * @deprecated `waitForElement` has been deprecated. Use a `find*` query (preferred: https://testing-library.com/docs/dom-testing-library/api-queries#findby) or use `wait` instead (it's the same API, so you can find/replace): https://testing-library.com/docs/dom-testing-library/api-async#wait
    * @description
    * Wait for DOM elements to appear, disappear, or change.
    *
@@ -87,6 +90,13 @@ export interface RenderResult<ComponentType, WrapperType = ComponentType>
    * For more info see https://testing-library.com/docs/dom-testing-library/api-async#waitforelementtoberemoved
    */
   waitForElementToBeRemoved: typeof waitForElementToBeRemoved;
+  /**
+   * @description
+   * When in need to wait for non-deterministic periods of time you can use wait, to wait for your expectations to pass.
+   *
+   * For more info see https://testing-library.com/docs/dom-testing-library/api-async#wait
+   */
+  wait: typeof wait;
 }
 
 export interface RenderComponentOptions<ComponentType, Q extends Queries = typeof queries> {

projects/testing-library/src/lib/testing-library.ts

@@ -13,6 +13,7 @@ import {
   waitForDomChange,
   waitForElement,
   waitForElementToBeRemoved,
+  wait,
 } from '@testing-library/dom';
 import { RenderComponentOptions, RenderDirectiveOptions, RenderResult } from './models';
 import { createSelectOptions, createType, tab } from './user-events';
@@ -111,11 +112,11 @@ export async function render<SutType, WrapperType = SutType>(
     detectChanges();
   };
 
-  let router = routes ? (TestBed.get<Router>(Router) as Router) : null;
-  const zone = TestBed.get<NgZone>(NgZone) as NgZone;
+  let router = routes ? TestBed.inject(Router) : null;
+  const zone = TestBed.inject(NgZone);
   const navigate = async (elementOrPath: Element | string, basePath = '') => {
     if (!router) {
-      router = TestBed.get<Router>(Router) as Router;
+      router = TestBed.inject(Router);
     }
 
     const href = typeof elementOrPath === 'string' ? elementOrPath : elementOrPath.getAttribute('href');
@@ -126,41 +127,75 @@ export async function render<SutType, WrapperType = SutType>(
     return result;
   };
 
-  function componentWaitForDomChange(options?: {
-    container?: HTMLElement;
-    timeout?: number;
-    mutationObserverOptions?: MutationObserverInit;
-  }): Promise<void> {
-    const interval = setInterval(detectChanges, 10);
-    return waitForDomChange({ container: fixture.nativeElement, ...options }).finally(() => clearInterval(interval));
+  function componentWait(
+    callback: () => void,
+    options: {
+      container?: HTMLElement;
+      timeout?: number;
+      interval?: number;
+      mutationObserverOptions?: {
+        subtree: boolean;
+        childList: boolean;
+        attributes: boolean;
+        characterData: boolean;
+      };
+    } = { container: fixture.nativeElement, interval: 50 },
+  ): Promise<void> {
+    const interval = setInterval(detectChanges, options.interval);
+    return wait(callback, options).finally(() => clearInterval(interval));
+  }
+
+  function componentWaitForDomChange(
+    options: {
+      container?: HTMLElement;
+      timeout?: number;
+      interval?: number;
+      mutationObserverOptions?: {
+        subtree: boolean;
+        childList: boolean;
+        attributes: boolean;
+        characterData: boolean;
+      };
+    } = { container: fixture.nativeElement, interval: 50 },
+  ): Promise<void> {
+    const interval = setInterval(detectChanges, options.interval);
+    return waitForDomChange(options).finally(() => clearInterval(interval));
   }
 
   function componentWaitForElement<Result>(
     callback: () => Result,
-    options?: {
+    options: {
       container?: HTMLElement;
       timeout?: number;
-      mutationObserverOptions?: MutationObserverInit;
-    },
+      interval?: number;
+      mutationObserverOptions?: {
+        subtree: boolean;
+        childList: boolean;
+        attributes: boolean;
+        characterData: boolean;
+      };
+    } = { container: fixture.nativeElement, interval: 50 },
   ): Promise<Result> {
-    const interval = setInterval(detectChanges, 10);
-    return waitForElement(callback, { container: fixture.nativeElement, ...options }).finally(() =>
-      clearInterval(interval),
-    );
+    const interval = setInterval(detectChanges, options.interval);
+    return waitForElement(callback, options).finally(() => clearInterval(interval));
   }
 
   function componentWaitForElementToBeRemoved<Result>(
     callback: () => Result,
-    options?: {
+    options: {
       container?: HTMLElement;
       timeout?: number;
-      mutationObserverOptions?: MutationObserverInit;
-    },
+      interval?: number;
+      mutationObserverOptions?: {
+        subtree: boolean;
+        childList: boolean;
+        attributes: boolean;
+        characterData: boolean;
+      };
+    } = { container: fixture.nativeElement, interval: 50 },
   ): Promise<Result> {
-    const interval = setInterval(detectChanges, 10);
-    return waitForElementToBeRemoved(callback, { container: fixture.nativeElement, ...options }).finally(() =>
-      clearInterval(interval),
-    );
+    const interval = setInterval(detectChanges, options.interval);
+    return waitForElementToBeRemoved(callback, options).finally(() => clearInterval(interval));
   }
 
   return {
@@ -174,6 +209,7 @@ export async function render<SutType, WrapperType = SutType>(
     type: createType(eventsWithDetectChanges),
     selectOptions: createSelectOptions(eventsWithDetectChanges),
     tab,
+    wait: componentWait,
     waitForDomChange: componentWaitForDomChange,
     waitForElement: componentWaitForElement,
     waitForElementToBeRemoved: componentWaitForElementToBeRemoved,

projects/testing-library/tests/wait.spec.ts

@@ -0,0 +1,39 @@
+import { Component } from '@angular/core';
+import { timer } from 'rxjs';
+import { render } from '../src/public_api';
+
+@Component({
+  selector: 'fixture',
+  template: `
+    <button data-testid="button" (click)="load()">Load</button>
+    <div>{{ result }}</div>
+  `,
+})
+class FixtureComponent {
+  result = '';
+
+  load() {
+    timer(500).subscribe(() => (this.result = 'Success'));
+  }
+}
+
+test('waits for assertion to become true', async () => {
+  const { queryByText, getByTestId, click, wait, getByText } = await render(FixtureComponent);
+
+  expect(queryByText('Success')).toBeNull();
+
+  click(getByTestId('button'));
+
+  await wait(() => getByText('Success'));
+  getByText('Success');
+});
+
+test('allows to override options', async () => {
+  const { getByTestId, click, wait, getByText } = await render(FixtureComponent);
+
+  click(getByTestId('button'));
+
+  await expect(wait(() => getByText('Success'), { timeout: 200 })).rejects.toThrow(
+    /Unable to find an element with the text: Success/i,
+  );
+});