Improve Code Maintainability Through React Integration Testing

Integration tests provide a good balance between test cost and value. Using react-testing-library to write integration tests for React applications, either in place of or alongside component unit tests, can enhance code maintainability without sacrificing development speed.

If you’d like a sneak peek before moving forward, you can check out an example demonstrating how to use react-testing-library for React app integration tests here.

Why Invest in Integration Testing?

“Integration tests find a good balance between confidence and speed/cost trade-offs. Therefore, it’s recommended to focus most (but not all) of your testing efforts in this area.” – Kent C. Dodds in Write tests. Not too many. Mostly integration.

Unit testing React components is a standard practice, often employing popular libraries like “enzymes” for React testing, specifically its “shallow” method. This allows testing components separately from the rest of the application. However, since React applications rely heavily on component composition, unit tests alone cannot guarantee a bug-free application.

For instance, modifying a component’s accepted props and updating its corresponding unit tests might show all tests passing, but the application could still break if another component wasn’t updated accordingly.

Integration tests can offer peace of mind when making changes to a React application by verifying that the component composition results in the desired user experience.

What We Want and What We Don’t Want in React App Integration Tests

Here’s what React developers aim to achieve when writing integration tests:

  • Test application use-cases from the end-user’s point of view, simulating how users interact with controls and access information on a web page.
  • Mock API calls to avoid dependency on API availability and state for test results.
  • Mock browser APIs (like local storage) as they don’t exist in the testing environment.
  • Make assertions about the React DOM state (whether it’s a browser DOM or a native mobile environment).

Conversely, here’s what we should try to avoid:

  • Testing implementation specifics. Implementation changes should only break a test if they introduce a genuine bug.
  • Excessive mocking. The goal is to test how different app parts work together.
  • Shallow rendering. We want to test the entire component composition, down to the smallest unit.

Why Choose React-testing-library?

These requirements make react-testing-library an excellent choice, as its core principle is to enable testing React components in a way that mirrors how actual users interact with them.

This library, along with its optional companion tool, companion libraries, allows writing tests that interact with and assert on the state of the DOM.

Setting Up a Sample App

Our sample app for integration tests will implement a basic scenario:

  • The user provides a GitHub username.
  • The app displays a list of public repositories associated with that username.

The implementation details shouldn’t matter for integration testing. However, to stay realistic, the app will follow common React patterns:

  • Single-page app (SPA) structure
  • API requests
  • Global state management
  • Internationalization support
  • Use of a React component library

The app’s source code is available here.

Writing Integration Tests

Installing Dependencies

Using yarn:

1

yarn add --dev jest @testing-library/react @testing-library/user-event jest-dom nock

Or with npm:

1

npm i -D jest @testing-library/react @testing-library/user-event jest-dom nock

Creating a Test Suite File

We’ll create viewGitHubRepositoriesByUsername.spec.js within our application’s ./test folder. Jest will automatically detect it.

Importing Dependencies

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

import React from 'react'; // so that we can use JSX syntax
import {
 render,
 cleanup,
 waitForElement
} from '@testing-library/react'; // testing helpers
import userEvent from '@testing-library/user-event' // testing helpers for imitating user events
import 'jest-dom/extend-expect'; // to extend Jest's expect with DOM assertions
import nock from 'nock'; // to mock github API
import {
 FAKE_USERNAME_WITH_REPOS,
 FAKE_USERNAME_WITHOUT_REPOS,
 FAKE_BAD_USERNAME,
 REPOS_LIST
} from './fixtures/github'; // test data to use in a mock API
import './helpers/initTestLocalization'; // to configure i18n for tests
import App from '../App'; // the app that we are going to test

Setting up the Test Suite

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

describe('view GitHub repositories by username', () => {
 beforeAll(() => {
   nock('https://api.github.com')
     .persist()
     .get(`/users/${FAKE_USERNAME_WITH_REPOS}/repos`)
     .query(true)
     .reply(200, REPOS_LIST);
 });

 afterEach(cleanup);

 describe('when GitHub user has public repositories', () => {
   it('user can view the list of public repositories for entered GitHub username', async () => {
     // arrange
     // act
     // assert
   });
 });


 describe('when GitHub user has no public repositories', () => {
   it('user is presented with a message that there are no public repositories for entered GitHub username', async () => {
     // arrange
     // act
     // assert
   });
 });

 describe('when GitHub user does not exist', () => {
   it('user is presented with an error message', async () => {
     // arrange
     // act
     // assert
   });
 });
});

Notes:

  • Before each test, mock the GitHub API to return a list of repositories for a specific username.
  • Clean the test React DOM after each test to ensure a fresh start for subsequent tests.
  • describe blocks outline the integration test use case and its flow variations.
  • Tested flow variations include:
    • Valid username with associated public repositories.
    • Valid username with no associated public repositories.
    • Non-existent GitHub username.
  • it blocks use async callbacks to handle asynchronous operations within the tested use cases.

Writing the First Flow Test

The first step is to render the app:

1

 const { getByText, getByPlaceholderText, queryByText } = render(<App />);

The render method, imported from @testing-library/react, renders the app within the test React DOM and returns DOM queries bound to the app container. These queries help locate and interact with DOM elements and assert their state.

Next, we simulate the user entering a username into the provided field:

1

 userEvent.type(getByPlaceholderText('userSelection.usernamePlaceholder'), FAKE_USERNAME_WITH_REPOS);

The userEvent helper, imported from @testing-library/user-event, provides the type method to mimic a user typing into a text field. It takes the target DOM element and the input string as arguments.

Users usually find elements through associated text, like labels or placeholders. We’ll use the getByPlaceholderText query returned by render to locate the username field.

It’s good practice to configure the localization module to return localization keys instead of actual values during tests. For instance, instead of “Enter GitHub username” for userSelection.usernamePlaceholder, return “userSelection.usernamePlaceholder”. This avoids relying on text that might change.

The text field should update as the user types:

1

expect(getByPlaceholderText('userSelection.usernamePlaceholder')).toHaveAttribute('value', FAKE_USERNAME_WITH_REPOS);

Next, we simulate the user clicking the submit button and expect to see the repository list:

1
2

 userEvent.click(getByText('userSelection.submitButtonText').closest('button'));
 getByText('repositories.header');

userEvent.click simulates a click event, and getByText finds the button by its text. The closest modifier helps select the correct element type.

Note: In integration tests, steps often have both action and assertion roles. Here, clicking the button asserts its clickability.

We’ve asserted that the repository list section is visible. Now, let’s ensure the user sees a loading indicator while fetching repositories from GitHub and that the app doesn’t prematurely indicate no repositories found:

1
2

 getByText('repositories.loadingText');
 expect(queryByText('repositories.empty')).toBeNull();

Note the use of getBy to assert an element’s presence and queryBy for the opposite. queryBy doesn’t throw an error if the element is missing.

We then ensure the app eventually fetches and displays the repositories:

1
2
3
4
5

 await waitForElement(() => REPOS_LIST.reduce((elementsToWaitFor, repository) => {
   elementsToWaitFor.push(getByText(repository.name));
   elementsToWaitFor.push(getByText(repository.description));
   return elementsToWaitFor;
 }, []));

The waitForElement method waits for a DOM update that fulfills the provided assertion. Here, we wait for the app to display the name and description of each repository returned by the mocked GitHub API.

Finally, the loading indicator and any error messages should disappear:

1
2

 expect(queryByText('repositories.loadingText')).toBeNull();
 expect(queryByText('repositories.error')).toBeNull();

Our complete React integration test now looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

it('user can view the list of public repositories for entered GitHub username', async () => {
     const { getByText, getByPlaceholderText, queryByText } = render(<App />);
     userEvent.type(getByPlaceholderText('userSelection.usernamePlaceholder'), FAKE_USERNAME_WITH_REPOS);  expect(getByPlaceholderText('userSelection.usernamePlaceholder')).toHaveAttribute('value', FAKE_USERNAME_WITH_REPOS);
     userEvent.click(getByText('userSelection.submitButtonText').closest('button'));
     getByText('repositories.header');
     getByText('repositories.loadingText');
     expect(queryByText('repositories.empty')).toBeNull();
     await waitForElement(() => REPOS_LIST.reduce((elementsToWaitFor, repository) => {
       elementsToWaitFor.push(getByText(repository.name));
       elementsToWaitFor.push(getByText(repository.description));
       return elementsToWaitFor;
     }, []));
     expect(queryByText('repositories.loadingText')).toBeNull();
     expect(queryByText('repositories.error')).toBeNull();
});

Testing Alternate Flows

Test the scenario where the entered username has no associated public repositories:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

 describe('when GitHub user has no public repositories', () => {
   it('user is presented with a message that there are no public repositories for entered GitHub username', async () => {
     const { getByText, getByPlaceholderText, queryByText } = render(<App />);
     userEvent.type(getByPlaceholderText('userSelection.usernamePlaceholder'), FAKE_USERNAME_WITHOUT_REPOS);     expect(getByPlaceholderText('userSelection.usernamePlaceholder')).toHaveAttribute('value', FAKE_USERNAME_WITHOUT_REPOS);
     userEvent.click(getByText('userSelection.submitButtonText').closest('button'));
     getByText('repositories.header');
     getByText('repositories.loadingText');
     expect(queryByText('repositories.empty')).toBeNull();
     await waitForElement(() => getByText('repositories.empty'));
     expect(queryByText('repositories.error')).toBeNull();
   });
 });

Test the scenario where the entered GitHub username doesn’t exist:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

 describe('when GitHub user does not exist', () => {
   it('user is presented with an error message', async () => {
     const { getByText, getByPlaceholderText, queryByText } = render(<App />);
     userEvent.type(getByPlaceholderText('userSelection.usernamePlaceholder'), FAKE_BAD_USERNAME);     expect(getByPlaceholderText('userSelection.usernamePlaceholder')).toHaveAttribute('value', FAKE_BAD_USERNAME);
     userEvent.click(getByText('userSelection.submitButtonText').closest('button'));
     getByText('repositories.header');
     getByText('repositories.loadingText');
     expect(queryByText('repositories.empty')).toBeNull();
     await waitForElement(() => getByText('repositories.error'));
     expect(queryByText('repositories.empty')).toBeNull();
   });
 });

Why React Integration Tests are Great

Integration testing hits a sweet spot for React apps. They effectively catch bugs and facilitate test-driven development (TDD) while remaining resilient to implementation changes.

React-testing-library, demonstrated here, is an excellent tool for writing React integration tests, allowing you to interact with the app from the user’s perspective and validate its state and behavior accordingly.

These examples can be a starting point for incorporating integration tests into new or existing React projects. The complete code, including the app implementation, is available at GitHub.

Licensed under CC BY-NC-SA 4.0