8.5 KiB
| id | title |
|---|---|
| testing | Testing |
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 lets the framework, for example during SSR, wait until mutations and queries resolve. In unit tests, ApplicationRef.whenStable() and fixture.whenStable() work for both Zone.js and Zoneless setups when the work settles right away, such as a synchronous query function or a response flushed through HttpTestingController. They can resolve before a query or mutation that takes time settles, so advance fake timers instead, as shown in the sections below.
This integration requires Angular 19 or later. Earlier versions of Angular do not support
PendingTasks.
TestBed setup
Create a fresh QueryClient for every spec and provide it with provideTanStackQuery or provideQueryClient. This keeps caches isolated and lets you change default options per test:
const queryClient = new QueryClient({
defaultOptions: {
queries: {
retry: false, // ✅ faster failure tests
},
},
})
TestBed.configureTestingModule({
providers: [provideTanStackQuery(queryClient)],
})
If your applications actual 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() // Trigger effect
// Application is stable when queries are idle
await appRef.whenStable()
expect(query.status()).toBe('success')
expect(query.data()).toBe('Hello')
Here whenStable() resolves after the query settles because the query function returns right away. 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, create them through TestBed.createComponent. fixture.whenStable() can resolve before the query data arrives, so with fake timers, advance the clock past the query function's delay, then run fixture.detectChanges() and assert on what the component renders:
beforeEach(() => {
vi.useFakeTimers()
})
afterEach(() => {
vi.useRealTimers()
})
it('should render the query data', async () => {
@Component({
template: `<p>{{ query.data()?.value ?? 'Loading...' }}</p>`,
})
class ExampleComponent {
readonly query = injectQuery(() => ({
queryKey: ['example'],
queryFn: () =>
new Promise<{ value: number }>((resolve) =>
setTimeout(() => resolve({ value: 42 }), 10),
),
}))
}
const fixture = TestBed.createComponent(ExampleComponent)
fixture.detectChanges()
expect(fixture.nativeElement.textContent).toContain('Loading...')
await vi.advanceTimersByTimeAsync(11)
fixture.detectChanges()
expect(fixture.nativeElement.textContent).toContain('42')
})
If you use Angular Testing Library, render the component with render and follow the same flow, running change detection through rendered.fixture:
it('should render the query data', async () => {
@Component({
template: `<p>{{ query.data()?.value ?? 'Loading...' }}</p>`,
})
class ExampleComponent {
readonly query = injectQuery(() => ({
queryKey: ['example'],
queryFn: () =>
new Promise<{ value: number }>((resolve) =>
setTimeout(() => resolve({ value: 42 }), 10),
),
}))
}
const rendered = await render(ExampleComponent)
expect(rendered.getByText('Loading...')).toBeInTheDocument()
await vi.advanceTimersByTimeAsync(11)
rendered.fixture.detectChanges()
expect(rendered.getByText('42')).toBeInTheDocument()
})
To test the same query without a component, create it with TestBed.runInInjectionContext, advance the clock the same way, and assert on its signals:
it('should resolve the query data', async () => {
const query = TestBed.runInInjectionContext(() =>
injectQuery(() => ({
queryKey: ['example'],
queryFn: () =>
new Promise<{ value: number }>((resolve) =>
setTimeout(() => resolve({ value: 42 }), 10),
),
})),
)
expect(query.isPending()).toBe(true)
await vi.advanceTimersByTimeAsync(11)
expect(query.data()).toEqual({ value: 42 })
})
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 HttpClient testing utilities play nicely with PendingTasks. Register provideHttpClient() and provideHttpClientTesting() 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')),
})),
)
const fixturePromise = TestBed.inject(ApplicationRef).whenStable()
httpCtrl.expectOne('/api/todos').flush([{ id: 1 }])
await fixturePromise
expect(query.data()).toEqual([{ id: 1 }])
httpCtrl.verify()
Infinite queries & pagination
whenStable() can resolve before the pages of an infinite query reach the data() signal. With fake timers, advance the clock past the query function's delay instead, call fetchNextPage(), and advance it again before asserting on data().pages. Restore real timers in afterEach, so they are restored even when an assertion fails:
beforeEach(() => {
vi.useFakeTimers()
})
afterEach(() => {
vi.useRealTimers()
})
it('should load the next page', async () => {
const infinite = TestBed.runInInjectionContext(() =>
injectInfiniteQuery(() => ({
queryKey: ['pages'],
queryFn: ({ pageParam }) =>
new Promise<string>((resolve) =>
setTimeout(() => resolve(`page ${pageParam}`), 10),
),
initialPageParam: 1,
getNextPageParam: (_lastPage, allPages) => allPages.length + 1,
})),
)
await vi.advanceTimersByTimeAsync(11)
expect(infinite.data()?.pages).toEqual(['page 1'])
void infinite.fetchNextPage()
await vi.advanceTimersByTimeAsync(11)
expect(infinite.data()?.pages).toEqual(['page 1', 'page 2'])
})
Mutations and optimistic updates
whenStable() can resolve before a mutation started with mutate() settles. With fake timers enabled as in the examples above, advance the clock past the mutation function's delay before asserting on the result:
it('should uppercase the input', async () => {
const mutation = TestBed.runInInjectionContext(() =>
injectMutation(() => ({
mutationFn: (input: string) =>
new Promise<string>((resolve) =>
setTimeout(() => resolve(input.toUpperCase()), 10),
),
})),
)
mutation.mutate('test')
await vi.advanceTimersByTimeAsync(11)
expect(mutation.isSuccess()).toBe(true)
expect(mutation.data()).toBe('TEST')
})
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
provideHttpClientTesting()or your preferred mock to assert network calls - Advance timers past the query or mutation function after every
refetch,fetchNextPage(), or mutation instead of awaitingwhenStable() - Prefer
TestBed.runInInjectionContextfor service tests, andTestBed.createComponentor Angular Testing Library'srenderwithfixture.detectChanges()for component tests