firxworx

React Testing Library is a newer library that simplifies the testing of React components.

It provides utility functions built on top of react-dom and react-dom/test-utils that enable developers to write intuitive tests that relate to how actual users interact with your app.

This post covers the installation and configuration of React Testing Library in a React project that was “created from scratch”, i.e. not based on Create React App (CRA).

This post covers common considerations for a modern react project seen in industry:

• Support for ES6+ language features via babel
• Support for testing custom hooks
• CSS Modules / SCSS Modules for component styling
• Support for components that import multimedia files such as images, fonts, and audio
• Support for the react-spring animation library.
• Working with eslint

Installing React Testing Library

Change your working directory to the root of your project.

Use your favorite package manager to install react-testing-library and jest-dom as dev dependencies. The following examples use yarn:

yarn add --dev @testing-library/react 
yarn add --dev @testing-library/jest-dom

I like to install jest on its own:

yarn add --dev jest

I recommend including the jest plugin for eslint:

yarn add --dev eslint-plugin-jest

Add the babel-jest package to support the latest ES6+ language features:

yarn add --dev babel-jest

If you’d like to be able to test custom hooks, install @testing-library/react-hooks and react-test-renderer. The version of react-test-renderer should match the version of React, so edit the version number in the example below to reflect what you see in package.json:

yarn add --dev @testing-library/react-hooks
yarn add --dev react-test-renderer@^16.12.0

Note the minimum supported version of React for @testing-library/react-hooks and react-test-renderer is 16.9.0.

Check out the hooks testing documentation at: https://react-hooks-testing-library.com/usage/basic-hooks.

Finally, install the identity-obj-proxy package to support CSS/SCSS Modules. When configured, all classNames defined in component will be returned as-is when run in tests vs. replaced with a hashed version as they would in a production build. This helps facilitate snapshot testing because you can rely on classNames being static. If you are not using CSS/SCSS Modules, you can skip this step:

yarn add --dev identity-obj-proxy

Configuring ESLint

Eslint will complain about your tests in its default configuration. This is because, among other things, your test files will use functions such as test() and expect() without explicitly including them.

Open your eslint configuration file to make some changes to support jest. Your eslint configuration could be housed in a .eslintrc.json file or a functional equivalent such as any .eslintrc.* file or via an eslintConfig key in package.json.

To configure eslint to work with jest, ensure that there is a "jest": true entry in the env section of your configuration:

"env": {
    "commonjs": true,
    "jest": true,
    "es6": true
  },

Add the "jest" plugin to the plugins array:

  "plugins": [
    "babel",
    "react",
    "jest"
  ],

If you’d like to use the recommended linter rules for jest, add plugin:jest/recommended to the extends array. In the example below, I also add the recommended style rules provided by plugin:jest/style:

  "extends": [
    "eslint:recommended",
    "plugin:jest/recommended",
    "plugin:jest/style"
  ],

Supporting Static File Imports

Jest tests will cough if your React components import images, fonts, audio, and other static files. This is because the components are not being run through webpack (or whatever asset bundler you may be using). Imported files such as JPG images will be interpreted as JavaScript code, and that simply won’t work. We can solve this issue with a mock.

Create a test/ folder in the root of your project, and add a __mocks__ subfolder.

Note that this particular file/folder structure is entirely optional; you may wish to use something different in your project.

Create a file fileMock.js and paste the following JavaScript code inside:

module.exports = 'test-file-stub'

In the next section of this post, we will configure jest to use fileMock.js.

Configuring Jest

Jest can be configured by adding a jest.config.js file to the root of your project folder, or via a top-level jest key in package.json.

An example of a basic jest.config.js follows. This particular configuration supports babel via babel-jest, tells jest to look for tests under app/ and test/ folders, and tells it to ignore the node_modules/ and public/ paths.

Consider the patterns defined in the testMatch array. You should revise these to suit your needs. For example, many projects place code in a src/ folder vs. an app/ folder. The following example will match any files ending in .test.js or .test.jsx in the app/ folder, and any files ending in .test.js in the test/ folder.

module.exports = {
  roots: ['<rootDir>'],
  transform: {
    '\\.(js|jsx)?$': 'babel-jest',
  },
  testMatch: [
    '<rootDir>/app/**/*.test.{js, jsx}',
    '<rootDir>/test/**/*.test.js'
  ],
  moduleFileExtensions: ['js', 'jsx', 'json', 'node'],
  testPathIgnorePatterns: ['/node_modules/', '/public/'],
  setupFilesAfterEnv: [
    '@testing-library/jest-dom/extend-expect',
  ],
  moduleNameMapper: { },
}

An example of an expanded configuration that supports CSS Modules / SCSS Modules, imports of images/svg’s/fonts/audio files, and the react-spring library follows.

Note the moduleNameMapper object and how we’ve added a mapping for stylesheet files, multimedia imports, and react-spring. Note how we reference the fileMock.js file we created earlier.

If you do not use react-spring in your project, you can omit the 2x entries for it.

module.exports = {
  roots: ['<rootDir>'],
  transform: {
    '\\.(js|jsx)?$': 'babel-jest',
  },
  testMatch: [
    '<rootDir>/app/**/*.test.{js, jsx}',
    '<rootDir>/test/**/*.test.js'
  ],
  moduleFileExtensions: ['js', 'jsx', 'json', 'node'],
  testPathIgnorePatterns: ['/node_modules/', '/public/'],
  setupFilesAfterEnv: [
    '@testing-library/jest-dom/extend-expect',
  ],
  moduleNameMapper: {
    '\\.(css|less|scss|sass)$': 'identity-obj-proxy',
    '\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$': '<rootDir>/test/__mocks__/fileMock.js',
    'react-spring/renderprops': '<rootDir>/node_modules/react-spring/renderprops.cjs', // define this entry before 'react-spring'
    'react-spring': '<rootDir>/node_modules/react-spring/web.cjs',
  },
}

Full documentation for the configuration file can be found on the Jest website: https://jestjs.io/docs/en/configuration.

Running Tests

In the scripts section of your package.json file, define scripts for test, test:watch, and test:coverage that invoke jest:

"scripts": {
    ...
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage --colors",
    ...
}

You can now run these scripts via your package manager, e.g. yarn test or yarn test:watch.

The watch feature will monitor your project files for changes and automatically run your tests when they do. The coverage tool attempts to calculate your test coverage.

Write Some Tests

There are plenty of resources on how to write tests with react-testing-library and with jest.

Get started with the react-testing-library docs at:

https://testing-library.com/docs/react-testing-library/example-intro

Kent C. Dodds, one of the authors of react-testing-library, has a great blog where he covers topics related to testing and using the library, and he provides plenty of examples:

https://kentcdodds.com/blog/?q=testing

An example of a very basic test for a hypothetical button component called ActionButton follows:

import React from 'react'

import { render } from '@testing-library/react'
import ActionButton from './ActionButton.jsx'

const testLabel = 'TEST_LABEL'

test('confirm ActionButton renders with label', () => {
  const { getByText } = render(<ActionButton buttonStyle="back" label={testLabel} />)
  expect(getByText(testLabel)).toBeInTheDocument()
})

I think one of the coolest features of react-testing-library is fireEvent() function, enabling you to test how your components behave in response to clicks, keypresses, and other events. This provides powerful capabilities for integration testing.

import { render, fireEvent } from '@testing-library/react'
...
fireEvent.touchStart(getByText(/Accept/i))

Check out the ‘cheatsheet’ included in the react-testing-library docs:

https://testing-library.com/docs/react-testing-library/cheatsheet

Good luck with your tests!

This post walks through the steps to creating an Invoice component in React that supports adding + removing line items and features automatic calculation of totals as a user inputs values.

The source code to follow along with is available on github at: https://github.com/firxworx/react-simple-invoice

A live demo can be viewed at: https://demo.firxworx.com/react-simple-invoice

I use SCSS Modules for styling but you could easily refactor the code to use your favourite method for styling components.

SCSS Modules are an easy choice because the latest v2 of create-react-app (released Oct 1 2018) introduces out-of-the-box support for CSS Modules that can be written in CSS (default) or SASS/SCSS with the addition of the node-sass package. Version 1 required users to manually customize their webpack configuration if they wanted to use CSS Modules.

The code is relevant to React v16.6.3.

Project Setup

This project is based on the create-react-app starter. To get started with the yarn package manager:

yarn create react-app react-simple-invoice

The following dependencies are installed:

yarn add node-sass
yarn add react-icons

The create-react-app boilerplate can then be customized to use sass modules: all .css files are renamed to .scss and the .module.scss suffix filename convention is applied where applicable.

I added a bare-bones global stylesheet in styles/index.scss where I import Normalize.css (as _normalize.scss).

All of the component styles assume box-sizing border-box and that normalize.css is in place.

Implementing an Invoice Component

The most significant part of an Invoice component are arguably the line items that can be added and removed. The following provides an overview for how this functionality is implemented:

Initial scaffolding

Start by creating components/Invoice.js and components/Invoice.modules.scss.

Tear up the initial Invoice component as a class-based component. Import a couple helpful icons from react-icons and the Invoice scss module:

import React, { Component } from 'react'
import { MdAddCircle as AddIcon, MdCancel as DeleteIcon } from 'react-icons/md'
import styles from './Invoice.module.scss'

class Invoice extends Component {

  locale = 'en-US'
  currency = 'USD'

  render = () => {
    return (
      <div><h1>I am an Invoice</h1></div>
    )
  }

}

export default Invoice

The locale and currency are stored in the class for the sake of example. In a broader app, these might be injected as props and/or come in from a context or global state.

React will move towards functional components across the board in upcoming versions. However, for now, class-based components still reign for interactive/dynamic components that maintain their own state.

Define state

The Invoice’s state maintains a tax rate and an array of line item objects that have the following properties: name, description, quantity, and price.

Define the initial state with a 0% tax rate and a single blank line item:

  state = {
    taxRate: 0.00,
    lineItems: [
      {
        name: '',
        description: '',
        quantity: 0,
        price: 0.00,
      },
    ]
  }

Displaying line items

Inside the component’s render() method, JSX is used to display each line item reflected in the component’s state.

The Array map() function is used to iterate over each line item.

The key for each line item is simply set to its index in the state array. For more information on the necessity of keys in React, refer to the docs regarding Lists and Keys.

Each form input element is created as a Controlled Component. This means that React completely controls the element’s state (including whatever value is currently being stored by the form element Component) rather than leaving this to the element itself. To accomplish this, each input specifies an onChange event handler whose job it is to update the component’s state every time a user changes the value of an input.

Each input’s value is set to its corresponding value in the Invoice’s state.

The various styles and functions referenced will be implemented next:

{this.state.lineItems.map((item, i) => (
    <div className={`${styles.row} ${styles.editable}`} key={i}>
    <div>{i+1}</div>
    <div><input name="name" type="text" value={item.name} onChange={this.handleLineItemChange(i)} /></div>
    <div><input name="description" type="text" value={item.description} onChange={this.handleLineItemChange(i)} /></div>
    <div><input name="quantity" type="number" step="1" value={item.quantity} onChange={this.handleLineItemChange(i)} onFocus={this.handleFocusSelect} /></div>
    <div className={styles.currency}><input name="price" type="number" step="0.01" min="0.00" max="9999999.99" value={item.price} onChange={this.handleLineItemChange(i)} onFocus={this.handleFocusSelect} /></div>
    <div className={styles.currency}>{this.formatCurrency( item.quantity * item.price )}</div>
    <div>
        <button type="button"
        className={styles.deleteItem}
        onClick={this.handleRemoveLineItem(i)}
        ><DeleteIcon size="1.25em" /></button>
    </div>
    </div>
))}

Implement onChange handler

When a user types a value into an input, the onChange event fires and the handleLineItemChange(elementIndex) function is called.

The Invoice’s state is updated to reflect the input’s latest value:

  handleLineItemChange = (elementIndex) => (event) => {

    let lineItems = this.state.lineItems.map((item, i) => {
      if (elementIndex !== i) return item
      return {...item, [event.target.name]: event.target.value}
    })

    this.setState({lineItems})

  }

The handleLineItemChange() handler accepts an elementIndex param that corresponds to the line item’s position in the lineItems array. As an event handler, the function is also passed an event object.

The Invoice’s state is updated by creating a new version of the lineItems array. The new version features a line item object and property (name, description, quantity, price) modified to correspond to the changed input’s new value. The this.setState() function is then called to update the Invoice component with the updated state.

The new array is created by calling map() on the this.state.lineItems‘s Array and passing a function that updates the appropriate value.

As map() loops through each element, our function checks if that element’s index matches that of the input that triggered handleLineItemChange(). When it matches, an updated version of the line item is returned. When it doesn’t match, the line item is returned as-is.

The implementation works because the name of each form input input (available as event.target.name) corresponds to a the property name of the line item.

Implement onFocus Handler

It is sometimes convenient for users to have an input automatically select its entire value whenever it receives focus.

I think this applies to the quantity and price inputs so I added an onFocus handler called onFocusSelect(). It is implemented as follows:

  handleFocusSelect = (event) => {
    event.target.select()
  }

Implement Handler for Adding a Line Item

When the “Add Line Item” button is clicked, the onClick() event calls the handleAddLineItem() function.

A new line item is added to the Invoice by adding a new line item object to the component state’s lineItems array.

The Array concat() method is used to create a new array based on the current lineItems array. It concatenates a second array containing a new blank line item object. setState() is then called to update the state.

  handleAddLineItem = (event) => {

    this.setState({
      lineItems: this.state.lineItems.concat(
        [{ name: '', description: '', quantity: 0, price: 0.00 }]
      )
    })

  }

Implement Handler for Removing a Line Item

Each line item features a Delete button to remove it from the invoice.

Each Delete button’s onClick() event calls this.handleRemoveLineItem(i) where i is the index of line item.

The Array filter() method is used to return a new array that omits the object at the i‘th position of the original array. this.setState() updates the component state.

  handleRemoveLineItem = (elementIndex) => (event) => {
    this.setState({
      lineItems: this.state.lineItems.filter((item, i) => {
        return elementIndex !== i
      })
    })
  }

Implement Calculation and Formatting Functions

The component implements a number of helper functions to calculate and format tax and total amounts:

  formatCurrency = (amount) => {
    return (new Intl.NumberFormat(this.locale, {
      style: 'currency',
      currency: this.currency,
      minimumFractionDigits: 2,
      maximumFractionDigits: 2
    }).format(amount))
  }

  calcTaxAmount = (c) => {
    return c * (this.state.taxRate / 100)
  }

  calcLineItemsTotal = () => {
    return this.state.lineItems.reduce((prev, cur) => (prev + (cur.quantity * cur.price)), 0)
  }

  calcTaxTotal = () => {
    return this.calcLineItemsTotal() * (this.state.taxRate / 100)
  }

  calcGrandTotal = () => {
    return this.calcLineItemsTotal() + this.calcTaxTotal()
  }

Implement Styles

CSS Modules (or SCSS Modules in this case) are great for ensuring there are no naming conflicts in projects with multiple Components that might use the same class names.

The ComponentName.modules.scss file looks and works just like any normal SCSS file except the classes are invoked in JSX slightly differently.

Notice the import line: import styles from './Invoice.module.scss'

To apply a give .example style to a given component, you would refer to styles.example in the className prop:

<ExampleComponent className={styles.example}>

For multiple and/or conditional styles, ES6 strings + interpolation can be used to add additional expressions:

<ExampleComponent className={`${styles.example} ${styles.anotherExample}`} />

Refer to the repo on github to see how it all comes together.