references/async-waitfor-polling.md

GitHub
titleUse vi.waitFor for Async Conditions
impactCRITICAL
impactDescriptionReplaces arbitrary timeouts with condition-based waiting, eliminating flaky tests
tagsasync, waitFor, polling, flaky-tests, conditions

Use vi.waitFor for Async Conditions

Arbitrary timeouts (setTimeout with fixed delays) are the #1 cause of flaky tests. They either wait too long (slow tests) or not long enough (flaky tests). Use vi.waitFor to poll for conditions instead.

Incorrect (arbitrary timeout):

import { describe, it, expect } from 'vitest'

describe('DataLoader', () => {
  it('should load data', async () => {
    const loader = new DataLoader()
    loader.start()

    // Arbitrary 500ms - might be too short on slow CI, too long for fast machines
    await new Promise(r => setTimeout(r, 500))

    expect(loader.data).toEqual({ items: [1, 2, 3] })
  })
})

Correct (condition-based waiting):

import { describe, it, expect, vi } from 'vitest'

describe('DataLoader', () => {
  it('should load data', async () => {
    const loader = new DataLoader()
    loader.start()

    // Polls condition until true or timeout
    await vi.waitFor(() => {
      expect(loader.data).toEqual({ items: [1, 2, 3] })
    })
  })
})

With custom options:

await vi.waitFor(
  () => {
    expect(element.textContent).toBe('Loaded')
  },
  {
    timeout: 5000,  // Max wait time
    interval: 100,  // Poll interval
  }
)

When NOT to use this pattern:

  • When you have full control over timing (use fake timers instead)
  • For synchronous operations

Benefits:

  • Tests complete as fast as possible
  • No arbitrary delays that cause flakiness
  • Clear timeout errors when conditions aren't met

Reference: Vitest vi.waitFor