From e77fb1fb148c859d28932b348dbc484c2c0eb05b Mon Sep 17 00:00:00 2001
From: Charles <19598772+clydin@users.noreply.github.com>
Date: Wed, 19 Nov 2025 19:40:35 -0500
Subject: [PATCH] docs: separate Zone.js-specific testing utilities into new
guide
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`.
---
adev/src/app/routing/sub-navigation-data.ts | 5 +++++
.../src/content/guide/testing/utility-apis.md | 19 +++++++++----------
.../testing/zone-js-testing-utilities.md | 15 +++++++++++++++
3 files changed, 29 insertions(+), 10 deletions(-)
create mode 100644 adev/src/content/guide/testing/zone-js-testing-utilities.md
diff --git a/adev/src/app/routing/sub-navigation-data.ts b/adev/src/app/routing/sub-navigation-data.ts
index b5e3435dc58..de37284805f 100644
--- a/adev/src/app/routing/sub-navigation-data.ts
+++ b/adev/src/app/routing/sub-navigation-data.ts
@@ -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',
diff --git a/adev/src/content/guide/testing/utility-apis.md b/adev/src/content/guide/testing/utility-apis.md
index 899c3459263..38a72b333b4 100644
--- a/adev/src/content/guide/testing/utility-apis.md
+++ b/adev/src/content/guide/testing/utility-apis.md
@@ -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.
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.
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
diff --git a/adev/src/content/guide/testing/zone-js-testing-utilities.md b/adev/src/content/guide/testing/zone-js-testing-utilities.md
new file mode 100644
index 00000000000..d22cae86eee
--- /dev/null
+++ b/adev/src/content/guide/testing/zone-js-testing-utilities.md
@@ -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.
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. |