Testing recommendations

---

Our general set of do's and don'ts for testing components and views.

Choose the right selectors

Follow RTL's Guiding Principles and query priorities when choosing right element selectors.

Prioritize accessible and semantic queries (e.g., [role="dialog"]) followed by data-test-subj attributes over other, more complicated and prone to breaking queries (e.g. div > span.title) whenever possible.

Check out our component-specific testing docs to find the selectors we officially support.

Do:

screen.getByRole('dialog'); // react-testing-library
cy.get('[role="dialog"]'); // cypress
driver.findElement(By.cssSelector('[role="dialog"]')); // selenium

Don't:

container.querySelector('.euiFlyout'); // react-testing-library
cy.get('.euiFlyout'); // cypress
driver.findElement(By.cssSelector('.euiFlyout')); // selenium

Don't use snapshots

The EUI team strongly discourages snapshot testing, despite its simplicity. Snapshot tests are prone to frequent failures due to the smallest things, like whitespace changes. Developers often update stored snapshots when they see them fail without thinking too much about why they fail.

Tests should tell a story and be considered an instant red flag whenever they fail. They should focus on the important details like the data a component is displaying or if the data is coming from a prop or being dynamically calculated.

Instead, consider writing simple but precise assertion tests.

Do:

const { getByText, getByRole } = render(<MyComponent />);
expect(getByText('Hello, World!')).toBeInTheDocument();
expect(getByRole('button')).toHaveTextContent('Save');

Don't:

const { container } = render(<MyComponent />); // react-testing-library
expect(container).toMatchSnapshot();

Avoid time-based waits

Sometimes the easiest solution to fixing a test is adding a wait/sleep call. In most cases, though, this can't be considered a reliable fix, because:

1. It significantly increases total test run time, especially when used often
2. Every machine will take a different amount of time to execute the code, and some — especially CI runners — are prone to lag during the test run.

Instead, use the utilities available for every testing framework to wait for elements to appear or for asynchronous operations to finish execution.

Do:

screen.getByRole('button', { name: 'Save document' });
expect(await screen.findByText('Document saved successfully')).toBeInTheDocument();

Don't:

screen.getByRole('button', { name: 'Save document' });
await new Promise((resolve) => setTimeout(resolve, 1000));
expect(screen.getByText('Document saved successfully')).toBeInTheDocument();

Write clear test names

Test cases and suites should have unambiguous names and match the naming convention throughout the project. Use short but descriptive names written in plain English.

We recommend using the third-person singular simple present tense for its short form and ease of reading.

Do:

describe('arraySearch()', () => { // use tested function name as the root group name
  it('accepts object arrays', () => { /* [...] */ });
  it('accepts string arrays', () => { /* [...] */ });
  it('throw on non-array inputs', () => { /* [...] */});
  it('supports the `options.caseSensitive` option', () => { /*[...]*/ });
});

Don't:

describe('array search', () => { // bad: not pointing to what exactly this group is testing
  it('object arrays', () => { /* [...] */ }); // bad: not enough context
  it('arraySearch(["a", "b"])', () => { /* [...] */ }); // bad: function call example may not be easily understandable
  it('should throw on non-array inputs', () => { /* [...] */ });
  it('supports options.caseSensitive', () => { /* [...] */ }); // bad: using two different naming conventions; see line above
});

Wrap property names and data in `

When including property and argument names in the test name string, wrap them in backticks (`) to clearly separate them from the rest of the text.

Do:

it('returns an empty object when the `value` string is empty');

Don't:

it('returns an empty object when the value string is empty');

Add debug-friendly comments or error messages

Consider adding custom error messages or code comments for assertions that are not obvious. For jest, we recommend adding a comment on top or to the right of the assertion, so in case of an error, it will be printed out together as the failing code fragment.

Do:

// Total should equal the result of 1234^2 / 3.14 rounded to two decimal places
expect(screen.getByText('Total: 484954.14')).toBeInTheDocument();