Testing

This page describes how to test an application built with with React Spectrum, including how to query the DOM tree for elements and simulate user interactions.

Introduction#

Running automated tests on your application helps ensure that it continues to work as expected over time. You can use testing tools like Enzyme or React Testing Library along with test runners like Jest or Mocha to test React Spectrum applications. These generally work quite well out of the box but there are a few things to consider to ensure your tests are the best they can be.

Testing semantics#

Many testing libraries expect you to query for elements in the DOM tree. For example, you might have a test that renders a login page, finds the username and password fields, and simulates filling them out and submitting the form.

Querying for these elements can be done in many ways. It's common to use CSS selectors for this, but this can be problematic if you rely on implementation details of the component in these queries. For example, if you query by a CSS class name that may change in a future update of React Spectrum, your test will be brittle.

This also applies if you query for internal elements within a React Spectrum component. The DOM structure that React Spectrum renders should be considered a black box, and it may change at any time, so you should avoid relying on it.

The recommended way to query for React Spectrum components and their internals is by semantics. React Spectrum components implement ARIA patterns. ARIA is a W3C standard that specifies the semantics for many UI components. This is used to expose them to assistive technology such as screen readers, but can also be used in tests to operate the application programmatically. These semantics are much less likely to change over time, and while other DOM nodes may be added or removed, and CSS classes changed, the semantics are more likely to stay stable.

The main attribute to look for when querying is the role. This attribute represents the type of element a DOM node represents, e.g. a button, list option, or tab. This is similar to the HTML element type (e.g. <button> or <option>), but since many React Spectrum components are implemented with <div> for styling purposes, the role attribute is used instead to communicate the element's semantics.

React Testing Library#

React Testing Library is useful because it enforces that you write tests using semantics instead of implementation details. We use React Testing Library to test React Spectrum itself, and it's quite easy to query elements by role, text, label, etc.

import {render} from '@testing-library/react';

let tree = render(<MyComponent />);
let option = tree.getByRole('button');

import {render} from '@testing-library/react';

let tree = render(<MyComponent />);
let option = tree.getByRole('button');

import {render} from '@testing-library/react';

let tree = render(
  <MyComponent />
);
let option = tree.getByRole(
  'button'
);

Enzyme#

In Enzyme, you can use CSS selectors to find elements. You can query by role using an attribute selector:

import {mount} from 'enzyme';

let wrapper = mount(<MyComponent />);
let option = wrapper.find('[role="option"]');

import {mount} from 'enzyme';

let wrapper = mount(<MyComponent />);
let option = wrapper.find('[role="option"]');

import {mount} from 'enzyme';

let wrapper = mount(
  <MyComponent />
);
let option = wrapper.find(
  '[role="option"]'
);

Test ids#

Querying by semantics covers many scenarios, but what if you have many buttons on a page? How do you find the specific button you're looking for in a test? In many cases this could be done by querying by the text in the button or an accessibility label associated with it, but sometimes this might change over time or may be affected by things like translations in different languages. In these cases, you may need a way to identify specific elements in tests, and that's where test ids come in.

React Spectrum components pass all data attributes through to their underlying DOM nodes, which allows you to use an attribute like data-testid to identify a particular instance of a component. For example, you could add test ids to the two input elements in a login form and use them to find the username and password fields.

This example uses React Testing Library, but the idea could be applied in a similar way with Enzyme or other testing libraries.

import {render} from '@testing-library/react';
import {TextField} from '@react-spectrum/textfield';

function LoginForm() {
  return (
    <>
      <TextField label="Username" data-testid="username" />
      <TextField label="Password" data-testid="password" />
    </>
  );
}

let tree = render(<LoginForm />);
let username = tree.getByTestId('username');
let password = tree.getByTestId('password');

import {render} from '@testing-library/react';
import {TextField} from '@react-spectrum/textfield';

function LoginForm() {
  return (
    <>
      <TextField label="Username" data-testid="username" />
      <TextField label="Password" data-testid="password" />
    </>
  );
}

let tree = render(<LoginForm />);
let username = tree.getByTestId('username');
let password = tree.getByTestId('password');

import {render} from '@testing-library/react';
import {TextField} from '@react-spectrum/textfield';

function LoginForm() {
  return (
    <>
      <TextField
        label="Username"
        data-testid="username"
      />
      <TextField
        label="Password"
        data-testid="password"
      />
    </>
  );
}

let tree = render(
  <LoginForm />
);
let username = tree.getByTestId(
  'username'
);
let password = tree.getByTestId(
  'password'
);

Triggering events#

Most testing libraries include a way to simulate events on an element. React Spectrum components rely on many different browser events to support different devices and platforms, so it's important to simulate these correctly in your tests. For example, rather than only simulating a click event, the tests should simulate all of the events that would occur if a real user were interacting with the component.

For example, a click is really a mousemove and mouseover the target, followed by mousedown, focus, and mouseup events, and finally a click event. If you only simulated the click event, you would be missing all of these other preceding events that occur in real-world situations and this may make your test not work correctly. The implementation of the component may also change in the future to expect these events, making your test brittle. In addition, browsers have default behavior that occurs on certain events which would be missing, like focusing elements on mouse down, and toggling checkboxes on click.

The best way to handle this is with the user-event library. This lets you trigger high level interactions like a user would, and the library handles firing all of the individual events that make up that interaction. If you use this library rather than firing events manually, your tests will simulate real-world behavior much better and work as expected.

user-event can handle many types of interactions, e.g. clicks, tabbing, typing, etc. This example shows how you could use it to render a login form and enter text in each field and click the submit button, just as a real user would.

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

let tree = render(<LoginForm />);

// Click on the username field to focus it, and enter the value.
userEvent.click(tree.getByLabelText('Username'));
userEvent.type(document.activeElement, 'devon');

// Tab to the password field, and enter the value.
userEvent.tab();
userEvent.type(document.activeElement, 'Pas$w0rd');

// Tab to the submit button and click it.
userEvent.tab();
userEvent.click(document.activeElement);

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

let tree = render(<LoginForm />);

// Click on the username field to focus it, and enter the value.
userEvent.click(tree.getByLabelText('Username'));
userEvent.type(document.activeElement, 'devon');

// Tab to the password field, and enter the value.
userEvent.tab();
userEvent.type(document.activeElement, 'Pas$w0rd');

// Tab to the submit button and click it.
userEvent.tab();
userEvent.click(document.activeElement);

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

let tree = render(
  <LoginForm />
);

// Click on the username field to focus it, and enter the value.
userEvent.click(
  tree.getByLabelText(
    'Username'
  )
);
userEvent.type(
  document.activeElement,
  'devon'
);

// Tab to the password field, and enter the value.
userEvent.tab();
userEvent.type(
  document.activeElement,
  'Pas$w0rd'
);

// Tab to the submit button and click it.
userEvent.tab();
userEvent.click(
  document.activeElement
);