Modify docs suggesting fireEvent as fallback

[jeremy-daley-kr]

Problem description

The current documentation seems to suggest that userEvent should be used almost always instead of fireEvent, but as others have called out, things like userEvent.type() are pretty expensive at scale. Heavy usage of that method may require overriding defaults (Jest timeout, userEvent's own delay, etc.).

A lot of developers are likely to take documentation as gospel... so can recommendations like this be reconsidered?

Most projects have a few use cases for fireEvent, but the majority of the time you should probably use @testing-library/user-event.

Suggested solution

Language suggesting fireEvent should be considered only a fallback solution seems to be dismissing test performance, and scale. Something more along these lines would make more sense in my opinion:

Projects writing mostly integration tests should prefer using userEvent over fireEvent, but that may require overriding test framework timeout defaults. However, projects that don't intend on changing any defaults, and don't require key-by-key emulation may need to consider if fireEvent is the more appropriate tool for the job when performance is a concern.

Or even something that mentions setting delay: null, as suggested by the aforementioned issue reviewer.

Additional context

Consider this Typescript example:

import React from 'react';
import { render, fireEvent } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

jest.setTimeout(60000);

const FIELDS = 20;
const CHARS = 200;

const fields = Array.from({ length: FIELDS }).map((_, i) => (
  <input type="text" key={i} aria-label={`fake${i}`} />
));
const chars = 'a'.repeat(CHARS);
const MyTest = () => <div>{fields}</div>;

describe('MyTest', () => {
  test('userEvent', async () => {
    const session = userEvent.setup();
    const { getByRole } = render(<MyTest />);
    for (let i = 0; i < fields.length; i++) {
      await session.type(getByRole('textbox', { name: `fake${i}` }), chars);
    }
  });

  test('fireEvent', async () => {
    const { getByRole } = render(<MyTest />);
    for (let i = 0; i < fields.length; i++) {
      fireEvent.input(getByRole('textbox', { name: `fake${i}` }), {
        target: { value: chars },
      });
    }
  });
});

The outcome: