Elgato_dark/angular
1
0
Fork 0
mirror of https://github.com/angular/angular synced 2026-05-24 09:28:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: separate Zone.js-specific testing utilities into new guide

Browse source 
This commit moves documentation for Zone.js-dependent testing utilities
(`waitForAsync`, `fakeAsync`, `tick`, `discardPeriodicTasks`, `flushMicrotasks`)
from `testing/utility-apis.md` to a new dedicated guide:
`testing/zone-js-testing-utilities.md`.
This commit is contained in:
Charles 2025-11-19 19:40:35 -05:00 committed by GitHub
parent 34e1fe235f
commit e77fb1fb14
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 29 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
adev/src/app/routing/sub-navigation-data.ts
View file

@ -600,6 +600,11 @@ const DOCS_SUB_NAVIGATION_DATA: NavigationItem[] = [
path: 'guide/testing/utility-apis',
contentPath: 'guide/testing/utility-apis',
},
{
label: 'Zone.js Testing Utilities',
path: 'guide/testing/zone-js-testing-utilities',
contentPath: 'guide/testing/zone-js-testing-utilities',
},
{
label: 'Component harnesses overview',
path: 'guide/testing/component-harnesses-overview',

19
adev/src/content/guide/testing/utility-apis.md
View file

@ -1,5 +1,7 @@
# Testing Utility APIs
NOTE: While this guide is being updated for Vitest, some descriptions and examples of utility APIs are currently presented within the context of Karma/Jasmine. We are actively working to provide Vitest equivalents and updated guidance where applicable.
This page describes the most useful Angular testing features.
The Angular testing utilities include the `TestBed`, the `ComponentFixture`, and a handful of functions that control the test environment.
@ -7,16 +9,13 @@ The [`TestBed`](#testbed-class-summary) and [`ComponentFixture`](#the-componentf
Here's a summary of the stand-alone functions, in order of likely utility:
| Function | Details |
| :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `waitForAsync` | Runs the body of a test \(`it`\) or setup \(`beforeEach`\) function within a special _async test zone_. See [waitForAsync](guide/testing/components-scenarios#waitForAsync). |
| `fakeAsync` | Runs the body of a test \(`it`\) within a special _fakeAsync test zone_, enabling a linear control flow coding style. See [fakeAsync](guide/testing/components-scenarios#fake-async). |
| `tick` | Simulates the passage of time and the completion of pending asynchronous activities by flushing both _timer_ and _micro-task_ queues within the _fakeAsync test zone_. The curious, dedicated reader might enjoy this lengthy blog post, ["_Tasks, microtasks, queues and schedules_"](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules). Accepts an optional argument that moves the virtual clock forward by the specified number of milliseconds, clearing asynchronous activities scheduled within that timeframe. See [tick](guide/testing/components-scenarios#tick). |
| `inject` | Injects one or more services from the current `TestBed` injector into a test function. It cannot inject a service provided by the component itself. See discussion of the [debugElement.injector](guide/testing/components-scenarios#get-injected-services). |
| `discardPeriodicTasks` | When a `fakeAsync()` test ends with pending timer event _tasks_ \(queued `setTimeOut` and `setInterval` callbacks\), the test fails with a clear error message. <br /> In general, a test should end with no queued tasks. When pending timer tasks are expected, call `discardPeriodicTasks` to flush the _task_ queue and avoid the error. |
| `flushMicrotasks` | When a `fakeAsync()` test ends with pending _micro-tasks_ such as unresolved promises, the test fails with a clear error message. <br /> In general, a test should wait for micro-tasks to finish. When pending microtasks are expected, call `flushMicrotasks` to flush the _micro-task_ queue and avoid the error. |
| `ComponentFixtureAutoDetect` | A provider token for a service that turns on [automatic change detection](guide/testing/components-scenarios#automatic-change-detection). |
| `getTestBed` | Gets the current instance of the `TestBed`. Usually unnecessary because the static class methods of the `TestBed` class are typically sufficient. The `TestBed` instance exposes a few rarely used members that are not available as static methods. |
| Function | Details |
| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inject` | Injects one or more services from the current `TestBed` injector into a test function. It cannot inject a service provided by the component itself. See discussion of the [debugElement.injector](guide/testing/components-scenarios#get-injected-services). |
| `ComponentFixtureAutoDetect` | A provider token for a service that turns on [automatic change detection](guide/testing/components-scenarios#automatic-change-detection). |
| `getTestBed` | Gets the current instance of the `TestBed`. Usually unnecessary because the static class methods of the `TestBed` class are typically sufficient. The `TestBed` instance exposes a few rarely used members that are not available as static methods. |
For handling complex asynchronous scenarios or testing legacy Zone.js-based applications, see the [Zone.js Testing Utilities](guide/testing/zone-js-testing-utilities) guide.
## `TestBed` class summary

15
adev/src/content/guide/testing/zone-js-testing-utilities.md Normal file
View file

@ -0,0 +1,15 @@
# Zone.js Testing Utilities
This guide describes testing utilities primarily used for managing and controlling async tasks in unit tests. These utilities are essentially the Zone.js-specific mock clock utilities, particularly relevant for controlling the flow of asynchronous operations within tests.
For general Angular testing utilities, including `TestBed` and `ComponentFixture`, see the [Testing Utility APIs](guide/testing/utility-apis) guide.
Here's a summary of Zone.js-specific functions:
| Function | Details |
| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `waitForAsync` | Tracks async tasks and completes the tests only once there are no longer any micro or macrotasks remaining in the test zone. See [waitForAsync](guide/testing/components-scenarios#waitForAsync). |
| `fakeAsync` | Runs the body of a test \(`it`\) within a special _fakeAsync test zone_, enabling a linear control flow coding style. See [fakeAsync](guide/testing/components-scenarios#fake-async). |
| `tick` | Simulates the passage of time and the completion of pending asynchronous activities by flushing both _timer_ and _micro-task_ queues within the _fakeAsync test zone_. The curious, dedicated reader might enjoy this lengthy blog post, ["_Tasks, microtasks, queues and schedules_"](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules). Accepts an optional argument that moves the virtual clock forward by the specified number of milliseconds, clearing asynchronous activities scheduled within that timeframe. See [tick](guide/testing/components-scenarios#tick). |
| `discardPeriodicTasks` | Discards any periodic tasks (e.g. `setInterval`) that were created inside the `fakeAsync` Zone. |
| `flushMicrotasks` | When a `fakeAsync()` test ends with pending _micro-tasks_ such as unresolved promises, the test fails with a clear error message. <br /> In general, a test should wait for micro-tasks to finish. When pending microtasks are expected, call `flushMicrotasks` to flush the _micro-task_ queue and avoid the error. |