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 the 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.

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

Do: Use accessible and semantic queries.

✄𐘗
tsx code block:
✄𐘗container.querySelector('.euiFlyout'); // react-testing-library
cy.get('.euiFlyout'); // cypress
driver.findElement(By.cssSelector('.euiFlyout')); // selenium

Don't: Query by internal EUI selectors, especially when better selectors are available.

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.

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

Do: Query and assert on elements you actually want to test

✄𐘗
tsx code block:
✄𐘗const { container } = render(<MyComponent />); // react-testing-library
expect(container).toMatchSnapshot();

Don't: Snapshot whole components

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.

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

Do: Programmatically await changes to occur

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

Don't: Add timeouts and other static waits

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.

✄𐘗
tsx code block:
✄𐘗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', () => { /*[...]*/ });
});

Do: Use clear and consistent names and test grouping

✄𐘗
tsx code block:
✄𐘗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
});

Don't: Use inconsistent or unclear naming

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.

✄𐘗
tsx code block:
✄𐘗it('returns an empty object when the `value` string is empty');

Do: Wrap property names in backticks

✄𐘗
tsx code block:
✄𐘗it('returns an empty object when the value string is empty');

Don't: Have no separation between property names and the rest of the text

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.

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

Do: Explain the source of the asserted value in code