TestBed beforeEach docs aren't coherent with CLI Generate

📚 Docs or angular.io bug report

Description

The docs on Calling compileComponents (https://angular.io/guide/testing-components-scenarios#calling-compilecomponents) specify the following :

beforeEach(waitForAsync(() => {
  TestBed
      .configureTestingModule({
        declarations: [BannerComponent],
      })
      .compileComponents()
      .then(() => {
        fixture = TestBed.createComponent(BannerComponent);
        component = fixture.componentInstance;
        h1 = fixture.nativeElement.querySelector('h1');
      });
}));

but the v11 cli generates the following :

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      declarations: [ MyComponent ]
    })
    .compileComponents();
  });

  beforeEach(() => {
    fixture = TestBed.createComponent(MyComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

So my question is what is the good practice here ? And if we can just async/await compileComponents why the docs specify to use waitForAsync ?

And in the cli v11 generated file since we’re awaiting compileComponents can’t we merge both beforeEach in the async one ? Like this

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      declarations: [ MyComponent ]
    })
    .compileComponents();

    fixture = TestBed.createComponent(MyComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

🌍 Your Environment

Angular CLI: 11.0.1 Node: 12.13.1 OS: win32 x64

Angular: 11.0.0 … animations, common, compiler, compiler-cli, core, forms … platform-browser, platform-browser-dynamic, router Ivy Workspace: Yes

Package Version

@angular-devkit/architect 0.1100.1 @angular-devkit/build-angular 0.1100.1 @angular-devkit/core 11.0.1 @angular-devkit/schematics 11.0.1 @angular/cli 11.0.1 @schematics/angular 11.0.1 @schematics/update 0.1100.1 rxjs 6.6.3 typescript 4.0.5

[petebacondarwin]

It’s not a dumb question at all! I asked the same recently.

One thing to be aware of is that async-await will literally only wait for the promises that are either awaited or returned from the function before continuing, while waitForAsync() will also wait for the NgZone to “settle”, which includes waiting for things like setTimeout(), XHR requests, and other macro tasks to complete.

From the point of view of compileComponents() it returns a Promise that literally only resolves when the compilation is complete, so async-await is enough.

But in your own tests you might like to ensure that your async test does not exit until certain macro tasks have completed. A trivial and artificial example:

it('should wait for all the time-out handlers to complete', waitForAsync(() => {
  let count = 0;
  setTimeout(() => count++, 100);
  setTimeout(() => count++, 100);
  setTimeout(() => count++, 100);
  setTimeout(() => expect(count).toEqual(3), 500);
}));

Without the waitForAsync() the expectation would never be checked.

Of course this example would be much better to do like:

it('should wait for all the time-out handlers to complete', done => {
  let count = 0;
  setTimeout(() => count++, 100);
  setTimeout(() => count++, 100);
  setTimeout(() => count++, 100);
  setTimeout(() => {
    expect(count).toEqual(3);
    done();
  }, 500);
});

[petebacondarwin]

@iRealNirmal - I think we could update the docs to match the CLI. But @alan-agius4 and I think we could probably also consolidate the two beforeEach blocks in new projects…

Also I just want to check with the FW team that we do actually want to use async () => {...} here rather than waitForAsync(() => { ... }), since they have slightly different semantics