docs: Update component testing scenarios (angular#56388)

This update goes through half of the component-scenarios guide and makes
relevant updates to examples.

Updates include:

* Use signals in examples
* Advise and use `await fixture.whenStable` more frequently than
  `detectChanges`
* Use and advise mocks and spies more sparingly
* Remove `waitForAsync` and jasmine `done` guidance - The ecosystem has evolved
  and these aren't needed
* Remove marble testing for rxjs - this belongs in rxjs documentation,
  not in Angular
* Remove class-only component testing. This approach is not advisable
  for components.

related to angular#48510

PR Close angular#56388

Author: atscott

adev/src/content/examples/testing/src/app/banner/banner.component.detect-changes.spec.ts

@@ -15,7 +15,6 @@ describe('BannerComponent (AutoChangeDetect)', () => {
   beforeEach(() => {
     // #docregion auto-detect
     TestBed.configureTestingModule({
-      imports: [BannerComponent],
       providers: [{provide: ComponentFixtureAutoDetect, useValue: true}],
     });
     // #enddocregion auto-detect
@@ -30,15 +29,18 @@ describe('BannerComponent (AutoChangeDetect)', () => {
     expect(h1.textContent).toContain(comp.title);
   });
 
-  it('should still see original title after comp.title change', () => {
+  it('should still see original title after comp.title change', async () => {
     const oldTitle = comp.title;
-    comp.title = 'Test Title';
-    // Displayed title is old because Angular didn't hear the change :(
+    const newTitle = 'Test Title';
+    comp.title.set(newTitle);
+    // Displayed title is old because Angular didn't yet run change detection
     expect(h1.textContent).toContain(oldTitle);
+    await fixture.whenStable();
+    expect(h1.textContent).toContain(newTitle);
   });
 
   it('should display updated title after detectChanges', () => {
-    comp.title = 'Test Title';
+    comp.title.set('Test Title');
     fixture.detectChanges(); // detect changes explicitly
     expect(h1.textContent).toContain(comp.title);
   });

adev/src/content/examples/testing/src/app/banner/banner.component.ts

@@ -1,13 +1,13 @@
-import {Component} from '@angular/core';
+import {Component, signal} from '@angular/core';
 
 // #docregion component
 @Component({
   standalone: true,
   selector: 'app-banner',
-  template: '<h1>{{title}}</h1>',
+  template: '<h1>{{title()}}</h1>',
   styles: ['h1 { color: green; font-size: 350%}'],
 })
 export class BannerComponent {
-  title = 'Test Tour of Heroes';
+  title = signal('Test Tour of Heroes');
 }
 // #enddocregion component

adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts

@@ -12,39 +12,25 @@ import {DashboardHeroComponent} from './dashboard-hero.component';
 
 beforeEach(addMatchers);
 
-describe('DashboardHeroComponent class only', () => {
-  // #docregion class-only
-  it('raises the selected event when clicked', () => {
-    const comp = new DashboardHeroComponent();
-    const hero: Hero = {id: 42, name: 'Test'};
-    comp.hero = hero;
-
-    comp.selected.pipe(first()).subscribe((selectedHero: Hero) => expect(selectedHero).toBe(hero));
-    comp.click();
-  });
-  // #enddocregion class-only
-});
-
 describe('DashboardHeroComponent when tested directly', () => {
   let comp: DashboardHeroComponent;
   let expectedHero: Hero;
   let fixture: ComponentFixture<DashboardHeroComponent>;
   let heroDe: DebugElement;
   let heroEl: HTMLElement;
 
-  beforeEach(waitForAsync(() => {
+  beforeEach(() => {
     // #docregion setup, config-testbed
     TestBed.configureTestingModule({
       providers: appProviders,
-      imports: [DashboardHeroComponent],
-    })
-      // #enddocregion setup, config-testbed
-      .compileComponents();
-  }));
+    });
+    // #enddocregion setup, config-testbed
+  });
 
-  beforeEach(() => {
+  beforeEach(async () => {
     // #docregion setup
     fixture = TestBed.createComponent(DashboardHeroComponent);
+    fixture.autoDetectChanges();
     comp = fixture.componentInstance;
 
     // find the hero's DebugElement and element
@@ -55,10 +41,10 @@ describe('DashboardHeroComponent when tested directly', () => {
     expectedHero = {id: 42, name: 'Test Name'};
 
     // simulate the parent setting the input property with that hero
-    comp.hero = expectedHero;
+    fixture.componentRef.setInput('hero', expectedHero);
 
-    // trigger initial data binding
-    fixture.detectChanges();
+    // wait for initial data binding
+    await fixture.whenStable();
     // #enddocregion setup
   });
 
@@ -72,7 +58,7 @@ describe('DashboardHeroComponent when tested directly', () => {
   // #docregion click-test
   it('should raise selected event when clicked (triggerEventHandler)', () => {
     let selectedHero: Hero | undefined;
-    comp.selected.pipe(first()).subscribe((hero: Hero) => (selectedHero = hero));
+    comp.selected.subscribe((hero: Hero) => (selectedHero = hero));
 
     // #docregion trigger-event-handler
     heroDe.triggerEventHandler('click');
@@ -84,7 +70,7 @@ describe('DashboardHeroComponent when tested directly', () => {
   // #docregion click-test-2
   it('should raise selected event when clicked (element.click)', () => {
     let selectedHero: Hero | undefined;
-    comp.selected.pipe(first()).subscribe((hero: Hero) => (selectedHero = hero));
+    comp.selected.subscribe((hero: Hero) => (selectedHero = hero));
 
     heroEl.click();
     expect(selectedHero).toBe(expectedHero);
@@ -94,7 +80,7 @@ describe('DashboardHeroComponent when tested directly', () => {
   // #docregion click-test-3
   it('should raise selected event when clicked (click helper with DebugElement)', () => {
     let selectedHero: Hero | undefined;
-    comp.selected.pipe(first()).subscribe((hero: Hero) => (selectedHero = hero));
+    comp.selected.subscribe((hero: Hero) => (selectedHero = hero));
 
     click(heroDe); // click helper with DebugElement
 
@@ -104,7 +90,7 @@ describe('DashboardHeroComponent when tested directly', () => {
 
   it('should raise selected event when clicked (click helper with native element)', () => {
     let selectedHero: Hero | undefined;
-    comp.selected.pipe(first()).subscribe((hero: Hero) => (selectedHero = hero));
+    comp.selected.subscribe((hero: Hero) => (selectedHero = hero));
 
     click(heroEl); // click helper with native element
 

adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.ts

@@ -1,5 +1,5 @@
 // #docregion
-import {Component, EventEmitter, Input, Output} from '@angular/core';
+import {Component, input, output} from '@angular/core';
 import {UpperCasePipe} from '@angular/common';
 
 import {Hero} from '../model/hero';
@@ -10,18 +10,18 @@ import {Hero} from '../model/hero';
   selector: 'dashboard-hero',
   template: `
     <button type="button" (click)="click()" class="hero">
-      {{ hero.name | uppercase }}
+      {{ hero().name | uppercase }}
     </button>
   `,
   styleUrls: ['./dashboard-hero.component.css'],
   imports: [UpperCasePipe],
 })
 // #docregion class
 export class DashboardHeroComponent {
-  @Input() hero!: Hero;
-  @Output() selected = new EventEmitter<Hero>();
+  hero = input.required<Hero>();
+  selected = output<Hero>();
   click() {
-    this.selected.emit(this.hero);
+    this.selected.emit(this.hero());
   }
 }
 // #enddocregion component, class

adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts

@@ -172,7 +172,8 @@ function heroModuleSetup() {
     }));
 
     // #docregion title-case-pipe
-    it('should convert hero name to Title Case', () => {
+    it('should convert hero name to Title Case', async () => {
+      harness.fixture.autoDetectChanges();
       // get the name's input and display elements from the DOM
       const hostElement: HTMLElement = harness.routeNativeElement!;
       const nameInput: HTMLInputElement = hostElement.querySelector('input')!;
@@ -184,8 +185,8 @@ function heroModuleSetup() {
       // Dispatch a DOM event so that Angular learns of input value change.
       nameInput.dispatchEvent(new Event('input'));
 
-      // Tell Angular to update the display binding through the title pipe
-      harness.detectChanges();
+      // Wait for Angular to update the display binding through the title pipe
+      await harness.fixture.whenStable();
 
       expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
     });

adev/src/content/examples/testing/src/app/model/user.service.ts

@@ -1,7 +1,7 @@
-import {Injectable} from '@angular/core';
+import {Injectable, signal} from '@angular/core';
 
-@Injectable()
+@Injectable({providedIn: 'root'})
 export class UserService {
-  isLoggedIn = true;
-  user = {name: 'Sam Spade'};
+  isLoggedIn = signal(true);
+  user = signal({name: 'Sam Spade'});
 }

adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts

@@ -3,7 +3,7 @@ import {fakeAsync, ComponentFixture, TestBed, tick, waitForAsync} from '@angular
 
 import {asyncData, asyncError} from '../../testing';
 
-import {of, throwError} from 'rxjs';
+import {Subject, defer, of, throwError} from 'rxjs';
 import {last} from 'rxjs/operators';
 
 import {TwainComponent} from './twain.component';
@@ -25,21 +25,21 @@ describe('TwainComponent', () => {
 
   // #docregion setup
   beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [TwainComponent],
+      providers: [TwainService],
+    });
     testQuote = 'Test Quote';
 
     // #docregion spy
     // Create a fake TwainService object with a `getQuote()` spy
-    const twainService = jasmine.createSpyObj('TwainService', ['getQuote']);
+    const twainService = TestBed.inject(TwainService);
     // Make the spy return a synchronous Observable with the test data
-    getQuoteSpy = twainService.getQuote.and.returnValue(of(testQuote));
+    getQuoteSpy = spyOn(twainService, 'getQuote').and.returnValue(of(testQuote));
     // #enddocregion spy
 
-    TestBed.configureTestingModule({
-      imports: [TwainComponent],
-      providers: [{provide: TwainService, useValue: twainService}],
-    });
-
     fixture = TestBed.createComponent(TwainComponent);
+    fixture.autoDetectChanges();
     component = fixture.componentInstance;
     quoteEl = fixture.nativeElement.querySelector('.twain');
   });
@@ -54,8 +54,8 @@ describe('TwainComponent', () => {
 
     // The quote would not be immediately available if the service were truly async.
     // #docregion sync-test
-    it('should show quote after component initialized', () => {
-      fixture.detectChanges(); // onInit()
+    it('should show quote after component initialized', async () => {
+      await fixture.whenStable(); // onInit()
 
       // sync spy result shows testQuote immediately after init
       expect(quoteEl.textContent).toBe(testQuote);
@@ -67,12 +67,20 @@ describe('TwainComponent', () => {
     // Use `fakeAsync` because the component error calls `setTimeout`
     // #docregion error-test
     it('should display error when TwainService fails', fakeAsync(() => {
-      // tell spy to return an error observable
-      getQuoteSpy.and.returnValue(throwError(() => new Error('TwainService test failure')));
+      // tell spy to return an error observable after a timeout
+      getQuoteSpy.and.returnValue(
+        defer(() => {
+          return new Promise((resolve, reject) => {
+            setTimeout(() => {
+              reject('TwainService test failure');
+            });
+          });
+        }),
+      );
       fixture.detectChanges(); // onInit()
       // sync spy errors immediately after init
 
-      tick(); // flush the component's setTimeout()
+      tick(); // flush the setTimeout()
 
       fixture.detectChanges(); // update errorMessage within setTimeout()
 
@@ -120,46 +128,18 @@ describe('TwainComponent', () => {
     }));
     // #enddocregion fake-async-test
 
-    // #docregion waitForAsync-test
-    it('should show quote after getQuote (waitForAsync)', waitForAsync(() => {
+    // #docregion async-test
+    it('should show quote after getQuote (async)', async () => {
       fixture.detectChanges(); // ngOnInit()
       expect(quoteEl.textContent).withContext('should show placeholder').toBe('...');
 
-      fixture.whenStable().then(() => {
-        // wait for async getQuote
-        fixture.detectChanges(); // update view with quote
-        expect(quoteEl.textContent).toBe(testQuote);
-        expect(errorMessage()).withContext('should not show error').toBeNull();
-      });
-    }));
-    // #enddocregion waitForAsync-test
-
-    // #docregion quote-done-test
-    it('should show last quote (quote done)', (done: DoneFn) => {
-      fixture.detectChanges();
-
-      component.quote.pipe(last()).subscribe(() => {
-        fixture.detectChanges(); // update view with quote
-        expect(quoteEl.textContent).toBe(testQuote);
-        expect(errorMessage()).withContext('should not show error').toBeNull();
-        done();
-      });
-    });
-    // #enddocregion quote-done-test
-
-    // #docregion spy-done-test
-    it('should show quote after getQuote (spy done)', (done: DoneFn) => {
-      fixture.detectChanges();
-
-      // the spy's most recent call returns the observable with the test quote
-      getQuoteSpy.calls.mostRecent().returnValue.subscribe(() => {
-        fixture.detectChanges(); // update view with quote
-        expect(quoteEl.textContent).toBe(testQuote);
-        expect(errorMessage()).withContext('should not show error').toBeNull();
-        done();
-      });
+      await fixture.whenStable();
+      // wait for async getQuote
+      fixture.detectChanges(); // update view with quote
+      expect(quoteEl.textContent).toBe(testQuote);
+      expect(errorMessage()).withContext('should not show error').toBeNull();
     });
-    // #enddocregion spy-done-test
+    // #enddocregion async-test
 
     it('should display error when TwainService fails', fakeAsync(() => {
       // tell spy to return an async error observable

adev/src/content/examples/testing/src/app/twain/twain.component.ts

@@ -1,5 +1,5 @@
 // #docregion
-import {Component, OnInit} from '@angular/core';
+import {Component, OnInit, signal} from '@angular/core';
 import {AsyncPipe} from '@angular/common';
 import {sharedImports} from '../shared/shared';
 
@@ -16,16 +16,16 @@ import {TwainService} from './twain.service';
       <i>{{ quote | async }}</i>
     </p>
     <button type="button" (click)="getQuote()">Next quote</button>
-    @if (errorMessage) {
-      <p class="error">{{ errorMessage }}</p>
+    @if (errorMessage()) {
+      <p class="error">{{ errorMessage() }}</p>
     }`,
   // #enddocregion template
   styles: ['.twain { font-style: italic; } .error { color: red; }'],
   imports: [AsyncPipe, sharedImports],
 })
 export class TwainComponent implements OnInit {
-  errorMessage!: string;
-  quote!: Observable<string>;
+  errorMessage = signal('');
+  quote?: Observable<string>;
 
   constructor(private twainService: TwainService) {}
 
@@ -35,12 +35,11 @@ export class TwainComponent implements OnInit {
 
   // #docregion get-quote
   getQuote() {
-    this.errorMessage = '';
+    this.errorMessage.set('');
     this.quote = this.twainService.getQuote().pipe(
       startWith('...'),
       catchError((err: any) => {
-        // Wait a turn because errorMessage already set once this turn
-        setTimeout(() => (this.errorMessage = err.message || err.toString()));
+        this.errorMessage.set(err.message || err.toString());
         return of('...'); // reset message to placeholder
       }),
     );