This document is a starting/reference guide for writing unit tests for the UI modules within ERM.
RTL (React testing library) is a testing utility for React that has been adopted by the FOLIO community as the framework for writing Unit tests within the UI modules.
This doc is a good place to start with understanding RTL, as to what problem it essentialy solves within the UI testing world.
Jest is the test runner that react recommends that lets you access the dom and make assertions against it within your tests.
RTL/JEST setup within ERM:
- The entire setup for the RTL/jest infrastructure lies within the stripes-erm-components under the test/jest folder. (PR that set it up for more reference)
- We have chosen stripes-erm-components to place this infrastructure because all the ERM UI modules have a dependency on stripes-erm-components which lets us allow to pull in the test configuration directly into the individual ui-* modules with a very simple setup, for example in ui-agreements, which pulls in the config from the jest.config.js in erm-components
- The __mock__ folder mocks the entire underlying stripes libraries, for eg: stripes-core, stripes-smart-components, stripesConfig, stripes-connect etc. These mocks are what let us not worry about any stripes dependencies we may have while testing, and just be concerned with testing the component in isolation.
Note: Its very important all the developers understand what each of the mock is actually mocking and also understand the jest configuration within the jest.config.js file. Understanding these details will help us debug the tests quickly specially when we hit errors/issues within the tests that are due to stripes level dependencies.
Writing RTL tests:
Before writing the RTL tests, its important to arrange where you would want to place the test file. RTL picks up test files with extension __filename__.test.js (config). Structurally its easier to group the actual component thats being tested along with the test file. Refer to the AddToBasketButton folder that has the component and its corresponding test placed in the same folder.
Once the test file has been created, we are good to write the tests.
This is a very nice blog that helps in setting up and writing tests in RTL/Jest.
A typical RTL test has 5 steps (reference)
- Imports
- Mock
- Arrange
- Act
- Assert
Imports:
This section includes all the necessary imports that are needed within the test file. Typically this includes:
- Importing React
- Importing the mocks from erm-components
- Importing the TestForm (if your component is rendered within a Form), renderWithIntl (function that renders the component to the dom with necessary translations)
- userEvent thats used to trigger events such as clicks, hover etc
- The actual component you need to test
Mock:
Apart from the stripes/intl mocks that were imported in the previous step from erm-components, this section includes mocks such as mocking an API request, or mocking a callback (spy). We use jests mocking API for this purpose.
Mocking an onSubmit or an onAdd callback can be as simple as:
or you can go one step further and mock the function implementation:
This mock overrides the default onSubmit functionality and logs submit to the console when its triggered.
Going through the mocks in erm-components should give you a better understanding of how mocking works.
Note: You can always clear the mocks using the mockClear() helper.
Arrange:
The next step is to render the component using either the render helper or renderWithIntl (which is just a wrapper around the render helper but also includes translations).
You can render the component simply by calling the render method.
Likewise we can use the renderWithIntl helper instead to include translations.
Act:
This step is where we can trigger user actions such as clicks, hover etc.
Checkout the userEvent api here which we use to trigger these actions.
To trigger a button with label Submit on it, you could do that using the userEvent.click api.
Assert:
Final step is to assert if your test is behaving as expected.
The following assertion expects the handleSubmit callback to be called once when the submit button is clicked.
