Most Angular tests using TanStack Query will involve services or components that call injectQuery/injectMutation.
TanStack Query's inject* functions integrate with PendingTasks which ensures the framework is aware of in-progress queries and mutations.
This means tests and SSR can wait until mutations and queries resolve. In unit tests you can use ApplicationRef.whenStable() or fixture.whenStable() to await query completion. This works for both Zone.js and Zoneless setups.
This adapter requires Angular 20.1 or later. It uses
PendingTasksto keep application stability open while observed work is pending.
TestBed setup#
Create a fresh QueryClient for every spec and return it from the provider factory. Keeping a reference makes it easy to inspect or clear the cache:
const queryClient = new QueryClient({
defaultOptions: {
queries: {
retry: false, // β
faster failure tests
},
},
})
TestBed.configureTestingModule({
providers: [provideTanStackQuery(() => queryClient)],
})
If your application's TanStack Query config is used in unit tests, make sure
withDevtoolsis not accidentally included in test providers. This can cause slow tests. It is best to keep test and production configs separate.
If you share helpers, remember to call queryClient.clear() (or build a new instance) in afterEach so data from one test never bleeds into another.
First query test#
Query tests typically run inside TestBed.runInInjectionContext, then wait for stability:
const appRef = TestBed.inject(ApplicationRef)
const query = TestBed.runInInjectionContext(() =>
injectQuery(() => ({
queryKey: ['greeting'],
queryFn: () => 'Hello',
})),
)
TestBed.tick() // Synchronize the test application
// Application is stable when queries are idle
await appRef.whenStable()
expect(query.status()).toBe('success')
expect(query.data()).toBe('Hello')
PendingTasks will have whenStable() resolve after the query settles. When using fake timers (Vitest), advance the clock and a microtask before awaiting stability:
await vi.advanceTimersByTimeAsync(0)
await Promise.resolve()
await appRef.whenStable()
Testing components#
For components, bootstrap them through TestBed.createComponent, then await fixture.whenStable():
const fixture = TestBed.createComponent(ExampleComponent)
fixture.autoDetectChanges()
await fixture.whenStable()
expect(fixture.componentInstance.query.data()).toEqual({ value: 42 })
In zone-based tests, enable fixture.autoDetectChanges() so component effects can run again
as the query settles. Zoneless fixtures enable automatic detection by default.
When using Angular Testing Library, its autoDetectChanges option runs change detection around
library operations; it does not call fixture.autoDetectChanges(). Enable the fixture's automatic
detection explicitly when awaiting stability in a zone-based component test.
Handling retries#
Retries slow failing tests because the default backoff runs three times. Set retry: false (or a specific number) through defaultOptions or per query to keep tests fast. If a query intentionally retries, assert on the final state rather than intermediate counts.
HttpClient & network stubs#
Angular's provideHttpClientTesting plays nicely with PendingTasks. Register it after
provideHttpClient, alongside the Query provider, and flush responses through
HttpTestingController:
TestBed.configureTestingModule({
providers: [
provideHttpClient(),
provideHttpClientTesting(),
provideTanStackQuery(() => queryClient),
],
})
const httpCtrl = TestBed.inject(HttpTestingController)
const query = TestBed.runInInjectionContext(() =>
injectQuery(() => ({
queryKey: ['todos'],
queryFn: () => lastValueFrom(TestBed.inject(HttpClient).get('/api/todos')),
})),
)
TestBed.tick() // Synchronize the test application so the request starts
const fixturePromise = TestBed.inject(ApplicationRef).whenStable()
httpCtrl.expectOne('/api/todos').flush([{ id: 1 }])
await fixturePromise
expect(query.data()).toEqual([{ id: 1 }])
httpCtrl.verify()
Mutations can start their HTTP request asynchronously, after their onMutate callbacks finish.
Wait for the request itself before flushing it. This Vitest example uses vi.waitFor:
const http = TestBed.inject(HttpClient)
const mutation = TestBed.runInInjectionContext(() =>
injectMutation(() => ({
mutationFn: (input: { email: string }) =>
lastValueFrom(http.post('/api/reset', input)),
})),
)
TestBed.tick()
mutation.mutate({ email: 'person@example.com' })
const request = await vi.waitFor(() => httpCtrl.expectOne('/api/reset'))
request.flush({ ok: true })
await TestBed.inject(ApplicationRef).whenStable()
expect(mutation.isSuccess()).toBe(true)
httpCtrl.verify()
Do not await stability before flushing a request controlled by the test: the unanswered request keeps the query or mutation stuck on pending.
Test observable results after normal Angular initialization and updates. For components, render
with fixture.autoDetectChanges() and await fixture.whenStable() when the operation should finish.
For injection-context-only tests, synchronize the test application as shown above. When using
HTTP mocks or fake timers, flush the request or advance time before awaiting stability.
Avoid asserting an exact subscription order or a stale intermediate value during initialization. Those are implementation details. To test pending mutation or fetching state, hold the operation open with a controlled promise and assert after rendering; do not await stability until you resolve that promise. To test completed state, resolve the operation and await stability before asserting the result.
Infinite queries & pagination#
Use the same pattern for infinite queries: call fetchNextPage(), advance timers if you are faking time, then await stability and assert on data().pages.
const infinite = TestBed.runInInjectionContext(() =>
injectInfiniteQuery(() => ({
queryKey: ['pages'],
initialPageParam: 1,
queryFn: ({ pageParam }) => fetchPage(pageParam),
getNextPageParam: (last, all) => all.length + 1,
})),
)
TestBed.tick()
await appRef.whenStable()
expect(infinite.data()?.pages).toHaveLength(1)
await infinite.fetchNextPage()
await appRef.whenStable()
expect(infinite.data()?.pages).toHaveLength(2)
Mutations and optimistic updates#
const mutation = TestBed.runInInjectionContext(() =>
injectMutation(() => ({
mutationFn: async (input: string) => input.toUpperCase(),
})),
)
mutation.mutate('test')
// Synchronize the test application
TestBed.tick()
await appRef.whenStable()
expect(mutation.isSuccess()).toBe(true)
expect(mutation.data()).toBe('TEST')
whenStable() waits for every mutation invocation, including awaited lifecycle callbacks.
Resolve or reject all outstanding mocked mutations before awaiting stability; calling reset()
does not finish a request. Queries paused offline also keep stability open until resumed or cancelled.
Quick checklist#
- Fresh
QueryClientper test (and clear it afterwards) - Disable or control retries to avoid timeouts
- Advance timers + microtasks before
whenStable()when using fake timers - Use
provideHttpClientTestingor your preferred mock to assert network calls - Resolve controlled requests, then await
whenStable()for settled-state assertions - Prefer
TestBed.runInInjectionContextfor service tests andfixture.whenStable()for component tests