Retryable assertions
I will start from removing the
vi.waitFor() block I have in the test:import { Client } from './client'
test('receives a basket of fruits', async () => {
const client = new Client()
const responseListener = vi.fn()
client.request('fruits', responseListener)
await vi.waitFor(() => {
expect(responseListener).toHaveBeenCalledWith(['apple', 'banana', 'cherry'])
})
})
Instead, I will replace it with a retryable assertion via the
expect.poll() API in Vitest:import { Client } from './client'
test('receives a basket of fruits', async () => {
const client = new Client()
const responseListener = vi.fn()
client.request('fruits', responseListener)
await expect
.poll(() => responseListener)
.toHaveBeenCalledWith(['apple', 'banana', 'cherry'])
})
This retryable (or polling) assertion accepts a function that should return the received value. This way, Vitest prevents the value from getting out-of-date while it keeps retrying the assertion over a period of time.
Similar to
vi.waitFor(), the expect.poll() call returns a Promise that you must await. This Promise will resolve once the assertion passes. It will reject if the assertion hasn't pass once the timeout has been reached (which you can customize using the second options argument to expect.poll()).🦉 Notice that despiteexpect.poll()being asynchronous, it doesn't have any.resolves.or.rejects.chaining. That is because it makes the entire assertion asynchronous, regardless if the value passed to it was a Promise or not.
vi.waitFor() vs expect.poll()
You might be wondering: How is this different from
vi.waitFor()?On the surface, two approaches simply differ syntactically, but there's more to it.
vi.waitFor() isn't really meant to be used with assertions. The way assertion errors are nested in the callback make it somewhat harder for Vitest to process them. expect.poll(), on the other hand, is tailored exclusively for eventual assertions.This makes the distinction between the two APIs a bit more clear.
vi.waitFor() | expect.poll() |
|---|---|
| Use to wait for a side effect or a state transition not directly related to the expectation you're testing. | Use to describe an eventual expectation. |
expect.element() is built around expect.poll() so you don't need to poll for values manually. When testing your components, prefer expect.element() instead.Here's how you would apply each API:
// Let's say this `action` is your starting interaction with the system.
// (i.e. it begins the state transition)
await action()
// Wait for certain side effects to complete.
// These are not related to what you're testing but are rather
// required before you proceed with your test.
await vi.waitFor(async () => {
// You can still use `expect()` here as a shorthand for resolving
// when a condition is met and rejecting when it's not. You can also
// use things like `invariant` or throwing errors manually.
await sideEffect()
})
// Now that the system is in the correct next state,
// continue interacting with it as the user would.
await anotherAction()
// Finally, write assertions that reflect your expectations.
// In this case, an eventual expectation for the `state` to
// become `expected`.
await expect.poll(state).toBe(expected)
Limitations of expect.poll()
That being said,
expect.poll() comes with a few limitations that you have to keep in mind when using it.- It doesn't work with all matchers (e.g. doesn't support snapshot matchers);
- The Promise it returns can only resolve, which means there's no
.rejects.or.resolves.chaining afterexpect.poll(). For example, you cannot use it with.toThrow(error)for negative assertions.