feat: add methods to test deferrable views (#426)

BREAKING CHANGE:

Requires Angular v17 to test deferrable views.

Author: timdeschryver

README.md

@@ -164,11 +164,11 @@ You may also be interested in installing `jest-dom` so you can use
 
 | Angular | Angular Testing Library |
 | ------- | ----------------------- |
-| 17.x    | 13.x, 14.x              |
-| 16.x    | 13.x, 14.x              |
-| >= 15.1 | 13.x \|\| 14.x          |
-| < 15.1  | 11.x \|\| 12.x          |
-| 14.x    | 11.x \|\| 12.x          |
+| 17.x    | 15.x, 14.x, 13.x        |
+| 16.x    | 14.x, 13.x              |
+| >= 15.1 | 14.x, 13.x              |
+| < 15.1  | 12.x, 11.x              |
+| 14.x    | 12.x, 11.x              |
 
 ## Guiding Principles
 

apps/example-app/src/app/examples/21-deferable-view.component.ts

@@ -0,0 +1,25 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-deferable-view-child',
+  template: ` <p>Hello from deferred child component</p> `,
+  standalone: true,
+})
+export class DeferableViewChildComponent {}
+
+@Component({
+  template: `
+    @defer (on timer(2s)) {
+        <app-deferable-view-child />
+    } @placeholder {
+        <p>Hello from placeholder</p>
+    } @loading {
+        <p>Hello from loading</p>
+    } @error {
+        <p>Hello from error</p>
+    }
+  `,
+  imports: [DeferableViewChildComponent],
+  standalone: true,
+})
+export class DeferableViewComponent {}

apps/example-app/src/app/examples/21-deferable-view.spec.ts

@@ -0,0 +1,23 @@
+import { render, screen } from '@testing-library/angular';
+import { DeferBlockState } from '@angular/core/testing';
+import { DeferableViewComponent } from './21-deferable-view.component';
+
+test('renders deferred views based on state', async () => {
+  const { renderDeferBlock } = await render(DeferableViewComponent);
+
+  expect(screen.getByText(/Hello from placeholder/i)).toBeInTheDocument();
+
+  await renderDeferBlock(DeferBlockState.Loading);
+  expect(screen.getByText(/Hello from loading/i)).toBeInTheDocument();
+
+  await renderDeferBlock(DeferBlockState.Complete);
+  expect(screen.getByText(/Hello from deferred child component/i)).toBeInTheDocument();
+});
+
+test('initially renders deferred views based on given state', async () => {
+  await render(DeferableViewComponent, {
+    deferBlockStates: DeferBlockState.Error,
+  });
+
+  expect(screen.getByText(/Hello from error/i)).toBeInTheDocument();
+});

projects/testing-library/package.json

@@ -29,10 +29,10 @@
     "migrations": "./schematics/migrations/migration.json"
   },
   "peerDependencies": {
-    "@angular/common": ">= 15.1.0 || >= 16.0.0 || >= 17.0.0",
-    "@angular/platform-browser": ">= 15.1.0 || >= 16.0.0 || >= 17.0.0",
-    "@angular/router": ">= 15.1.0 || >= 16.0.0 || >= 17.0.0",
-    "@angular/core": ">= 15.1.0 || >= 16.0.0 || >= 17.0.0"
+    "@angular/common": ">= 17.0.0",
+    "@angular/platform-browser": ">= 17.0.0",
+    "@angular/router": ">= 17.0.0",
+    "@angular/core": ">= 17.0.0"
   },
   "dependencies": {
     "@testing-library/dom": "^9.0.0",

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

@@ -1,5 +1,5 @@
 import { Type, DebugElement } from '@angular/core';
-import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { ComponentFixture, DeferBlockState, TestBed } from '@angular/core/testing';
 import { Routes } from '@angular/router';
 import { BoundFunction, Queries, queries, Config as dtlConfig, PrettyDOMOptions } from '@testing-library/dom';
 
@@ -63,6 +63,11 @@ export interface RenderResult<ComponentType, WrapperType = ComponentType> extend
       'componentProperties' | 'componentInputs' | 'componentOutputs' | 'detectChangesOnRender'
     >,
   ) => Promise<void>;
+  /**
+   * @description
+   * Set the state of a deferrable block.
+   */
+  renderDeferBlock: (deferBlockState: DeferBlockState, deferBlockIndex?: number) => Promise<void>;
 }
 
 export interface RenderComponentOptions<ComponentType, Q extends Queries = typeof queries> {
@@ -363,6 +368,8 @@ export interface RenderComponentOptions<ComponentType, Q extends Queries = typeo
    * })
    */
   configureTestBed?: (testbed: TestBed) => void;
+
+  deferBlockStates?: DeferBlockState | { deferBlockState: DeferBlockState; deferBlockIndex: number }[];
 }
 
 export interface ComponentOverride<T> {

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

@@ -9,7 +9,7 @@ import {
   ApplicationInitStatus,
   isStandalone,
 } from '@angular/core';
-import { ComponentFixture, TestBed, tick } from '@angular/core/testing';
+import { ComponentFixture, DeferBlockState, TestBed, tick } from '@angular/core/testing';
 import { BrowserAnimationsModule, NoopAnimationsModule } from '@angular/platform-browser/animations';
 import { NavigationExtras, Router } from '@angular/router';
 import { RouterTestingModule } from '@angular/router/testing';
@@ -65,6 +65,7 @@ export async function render<SutType, WrapperType = SutType>(
     removeAngularAttributes = false,
     defaultImports = [],
     initialRoute = '',
+    deferBlockStates = undefined,
     configureTestBed = () => {
       /* noop*/
     },
@@ -160,10 +161,19 @@ export async function render<SutType, WrapperType = SutType>(
     }
   }
 
-  let fixture: ComponentFixture<SutType>;
   let detectChanges: () => void;
 
-  await renderFixture(componentProperties, componentInputs, componentOutputs);
+  const fixture = await renderFixture(componentProperties, componentInputs, componentOutputs);
+
+  if (deferBlockStates) {
+    if (Array.isArray(deferBlockStates)) {
+      for (const deferBlockState of deferBlockStates) {
+        await renderDeferBlock(fixture, deferBlockState.deferBlockState, deferBlockState.deferBlockIndex);
+      }
+    } else {
+      await renderDeferBlock(fixture, deferBlockStates);
+    }
+  }
 
   let renderedPropKeys = Object.keys(componentProperties);
   let renderedInputKeys = Object.keys(componentInputs);
@@ -210,60 +220,61 @@ export async function render<SutType, WrapperType = SutType>(
   };
 
   return {
-    // @ts-ignore: fixture assigned
     fixture,
     detectChanges: () => detectChanges(),
     navigate,
     rerender,
-    // @ts-ignore: fixture assigned
+    renderDeferBlock: async (deferBlockState: DeferBlockState, deferBlockIndex?: number) => {
+      await renderDeferBlock(fixture, deferBlockState, deferBlockIndex);
+    },
     debugElement: fixture.debugElement,
-    // @ts-ignore: fixture assigned
     container: fixture.nativeElement,
     debug: (element = fixture.nativeElement, maxLength, options) =>
       Array.isArray(element)
         ? element.forEach((e) => console.log(dtlPrettyDOM(e, maxLength, options)))
         : console.log(dtlPrettyDOM(element, maxLength, options)),
-    // @ts-ignore: fixture assigned
     ...replaceFindWithFindAndDetectChanges(dtlGetQueriesForElement(fixture.nativeElement, queries)),
   };
 
-  async function renderFixture(properties: Partial<SutType>, inputs: Partial<SutType>, outputs: Partial<SutType>) {
-    if (fixture) {
-      cleanupAtFixture(fixture);
-    }
-
-    fixture = await createComponent(componentContainer);
-    setComponentProperties(fixture, properties);
-    setComponentInputs(fixture, inputs);
-    setComponentOutputs(fixture, outputs);
+  async function renderFixture(
+    properties: Partial<SutType>,
+    inputs: Partial<SutType>,
+    outputs: Partial<SutType>,
+  ): Promise<ComponentFixture<SutType>> {
+    const createdFixture = await createComponent(componentContainer);
+    setComponentProperties(createdFixture, properties);
+    setComponentInputs(createdFixture, inputs);
+    setComponentOutputs(createdFixture, outputs);
 
     if (removeAngularAttributes) {
-      fixture.nativeElement.removeAttribute('ng-version');
-      const idAttribute = fixture.nativeElement.getAttribute('id');
+      createdFixture.nativeElement.removeAttribute('ng-version');
+      const idAttribute = createdFixture.nativeElement.getAttribute('id');
       if (idAttribute && idAttribute.startsWith('root')) {
-        fixture.nativeElement.removeAttribute('id');
+        createdFixture.nativeElement.removeAttribute('id');
       }
     }
 
-    mountedFixtures.add(fixture);
+    mountedFixtures.add(createdFixture);
 
     let isAlive = true;
-    fixture.componentRef.onDestroy(() => (isAlive = false));
+    createdFixture.componentRef.onDestroy(() => (isAlive = false));
 
-    if (hasOnChangesHook(fixture.componentInstance) && Object.keys(properties).length > 0) {
+    if (hasOnChangesHook(createdFixture.componentInstance) && Object.keys(properties).length > 0) {
       const changes = getChangesObj(null, componentProperties);
-      fixture.componentInstance.ngOnChanges(changes);
+      createdFixture.componentInstance.ngOnChanges(changes);
     }
 
     detectChanges = () => {
       if (isAlive) {
-        fixture.detectChanges();
+        createdFixture.detectChanges();
       }
     };
 
     if (detectChangesOnRender) {
       detectChanges();
     }
+
+    return createdFixture;
   }
 }
 
@@ -429,6 +440,30 @@ function addAutoImports<SutType>(
   return [...imports, ...components(), ...animations(), ...routing()];
 }
 
+async function renderDeferBlock<SutType>(
+  fixture: ComponentFixture<SutType>,
+  deferBlockState: DeferBlockState,
+  deferBlockIndex?: number,
+) {
+  const deferBlockFixtures = await fixture.getDeferBlocks();
+
+  if (deferBlockIndex !== undefined) {
+    if (deferBlockIndex < 0) {
+      throw new Error('deferBlockIndex must be a positive number');
+    }
+
+    const deferBlockFixture = deferBlockFixtures[deferBlockIndex];
+    if (!deferBlockFixture) {
+      throw new Error(`Could not find a deferrable block with index '${deferBlockIndex}'`);
+    }
+    await deferBlockFixture.render(deferBlockState);
+  } else {
+    for (const deferBlockFixture of deferBlockFixtures) {
+      await deferBlockFixture.render(deferBlockState);
+    }
+  }
+}
+
 /**
  * Wrap waitFor to invoke the Angular change detection cycle before invoking the callback
  */

projects/testing-library/tests/defer-blocks.spec.ts

@@ -0,0 +1,67 @@
+import { Component } from '@angular/core';
+import { DeferBlockState } from '@angular/core/testing';
+import { render, screen } from '../src/public_api';
+
+test('renders a defer block in different states using the official API', async () => {
+  const { fixture } = await render(FixtureComponent);
+
+  const deferBlockFixture = (await fixture.getDeferBlocks())[0];
+
+  await deferBlockFixture.render(DeferBlockState.Loading);
+  expect(screen.getByText(/loading/i)).toBeInTheDocument();
+  expect(screen.queryByText(/Defer block content/i)).not.toBeInTheDocument();
+
+  await deferBlockFixture.render(DeferBlockState.Complete);
+  expect(screen.getByText(/Defer block content/i)).toBeInTheDocument();
+  expect(screen.queryByText(/load/i)).not.toBeInTheDocument();
+});
+
+test('renders a defer block in different states using ATL', async () => {
+  const { renderDeferBlock } = await render(FixtureComponent);
+
+  await renderDeferBlock(DeferBlockState.Loading);
+  expect(screen.getByText(/loading/i)).toBeInTheDocument();
+  expect(screen.queryByText(/Defer block content/i)).not.toBeInTheDocument();
+
+  await renderDeferBlock(DeferBlockState.Complete, 0);
+  expect(screen.getByText(/Defer block content/i)).toBeInTheDocument();
+  expect(screen.queryByText(/load/i)).not.toBeInTheDocument();
+});
+
+test('renders a defer block initially in the loading state', async () => {
+  await render(FixtureComponent, {
+    deferBlockStates: DeferBlockState.Loading,
+  });
+
+  expect(screen.getByText(/loading/i)).toBeInTheDocument();
+  expect(screen.queryByText(/Defer block content/i)).not.toBeInTheDocument();
+});
+
+test('renders a defer block initially in the complete state', async () => {
+  await render(FixtureComponent, {
+    deferBlockStates: DeferBlockState.Complete,
+  });
+
+  expect(screen.getByText(/Defer block content/i)).toBeInTheDocument();
+  expect(screen.queryByText(/load/i)).not.toBeInTheDocument();
+});
+
+test('renders a defer block in an initial state using the array syntax', async () => {
+  await render(FixtureComponent, {
+    deferBlockStates: [{ deferBlockState: DeferBlockState.Complete, deferBlockIndex: 0 }],
+  });
+
+  expect(screen.getByText(/Defer block content/i)).toBeInTheDocument();
+  expect(screen.queryByText(/load/i)).not.toBeInTheDocument();
+});
+
+@Component({
+  template: `
+    @defer {
+    <p>Defer block content</p>
+    } @loading {
+    <p>Loading...</p>
+    }
+  `,
+})
+class FixtureComponent {}