Testing recommendations
Our general set of do's and don'ts for testing components and views.
Choose the right 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.
screen.getByRole('dialog'); // react-testing-library
cy.get('[role="dialog"]'); // cypress
driver.findElement(By.cssSelector('[role="dialog"]')); // selenium
Do: Use accessible and semantic queries.
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.
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
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:
- It significantly increases total test run time, especially when used often
- 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.
screen.getByRole('button', { name: 'Save document' });
expect(await screen.findByText('Document saved successfully')).toBeInTheDocument();
Do: Programmatically await changes to occur
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.
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
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.
it('returns an empty object when the `value` string is empty');
Do: Wrap property names in backticks
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.
// 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