Basic testing setup

[arcticicestudio]

Related epics: #38

To start writing tests the basic testing environment must be set up. As also mentioned in #38, Nord Docs requires some special changes when it comes to the testing setup because of Gatsby. Apart from that the setup is the same like in most projects and is also documented in the official Jest docs.

The scope of this issue is to get started to write unit tests. Of course, Gatsby provides a extensive documentation and great guides for this setup which will be implemented for Nord Docs.

Jest

The first step is to get Jest up and running which is quite easy since it works out-of-the-box™ after installing the main package jest.
This step is documented in the sections “Setting up your environment” of the Gatsby guide and the Jest docs about how to get started.

The main configuration file jest.config.js will be placed in the project root and initially contains the following options:

• coverageDirectory - The path to the directory where all coverage reports will be placed. It'll be set to the main build directory within the reports sub-directory.
• collectCoverageFrom - To ensure only relevant files are included in the coverage stats this array will set paths to find sources to measure the coverage from.
• globals - This will include the __PATH_PREFIX__ variable which is usually set by Gatsby, and which some components need.
• moduleNameMapper - A map from regular expressions to module names that allow to stub out resources, like images or styles with a single module while also allows to set up resolve aliases which will reflect the same setup like the ones configured for Webpack in Webpack configuration #31.
• modulePaths - This will include paths to additional locations to search when resolving modules which is useful to define test specific utils which can then be imported like a aliased module.
• setupFiles - This also includes setup scripts that'll be run to configure and set up tests (executed before setupTestFrameworkScriptFile) and will initial include a shim mock for the ___loader function used by Gatsby.
• setupTestFrameworkScriptFile - The setup file that'll be run to configure or set up the testing framework before each test. It'll import and run the cleanup function of react-testing-library and jest-dom's custom matchers to extend the expect global.
• testPathIgnorePatterns - Paths for files that'll be ignored when matching test files have been found.
• transform - Contains regex matcher for files that will be transpiled with Babel first before run them with Jest. See the “Use Jest with Babel” section below for details.
• transformIgnorePatterns - This is required since Gastby includes un-transpiled ES6 code and by default Jest doesn’t try to transform code inside node_modules, therefore the gatsby-browser-entry.js isn't transpiled before running Jest so the gatsby module must be excluded.

Use Jest with Babel

To write tests using the latest ECMAScript syntax and proposals, Babel must be in place and set up to transpile the sources before passing them to Jest to run them.
This step is documented in the sections “Creating a configuration file for Jest” of the Gatsby guide about the preprocess file and the Jest docs about using babel.

The main Babel configuration file babel-config.js will be placed in the base test folder within the project root. It'll initially use the babel-preset-gatsby preset package which includes all necessary Babel plugins to write tests for Gatsby based projects. This includes all plugins mentioned in the Jest Babel setup guide and additionally adds useful syntax proposal plugins that are also used in the project sources like e.g. babel-plugin-proposal-class-properties and babel-plugin-proposal-optional-chaining.
The the custom transformer will be exported using babel-jest's createTransformer function which takes the created Babel config object as parameter.

react-testing-library provides a function to get elements by an test ID using the data-testid property (attribute) that can be added to any React component's JSX so it can be easily queried in tests. Note that this should only be done when there is no other way which is documented in the guiding principles!
Since this property is only relevant for test purposes it should and will be removed for production builds using the babel-plugin-react-remove-properties package that'll be included in Gatsby's Babel configuration and loaded when in production mode.

react-testing-library and jest-dom

Like documented in #38, Nord Docs will use the awesome react-testing-library by Kent C. Dodds to render React components and test them with a bunch of useful DOM utils. Nord Docs testing principle is based on the concept of the author to not test implementation details for UIs but see your app/website only from the sight of the user.

The setup documentation provides instruction for best practices on how to configure the library for a optimal and easy developer workflow. This includes a global configuration that'll be added and loaded via Jest's setupTestFrameworkScriptFile option and will be placed within the test base directory named setup.js.
Initially it'll import the react-testing-library/cleanup-after-each script which will automatially execute afterEach(cleanup) for each test which prevents unnecessary boilerplate per test file and possible problems when the function is not called accidentally. It'll also import jest-dom/extend-expect to automatically extend the expect global with jest-dom's custom matchers.

Shims

Like documented in Gatsby's official testing setup guide there are some configurations that are specific to Gatsby projects. One is the global ___loader function used by Gatsby which must be mocked using Jest's fn() mocking function. The ___loader.js file will be created in a folder called __shims__ within the base test directory.

Mocks

With Webpack, there are many loaders available to load any kind of file type, e.g. CSS or Sass/Less for styles and images/videos of many types. Jest doesn't know how to handle these when these are imported within source files that are normally processed by Webpack so it'll throw errors during the import.
A Jest mock is a dummy module that is used instead of the real module inside tests. It is good when there are something that you can’t or don’t want to test. Almost everything can be mocked and the examples are assets rather than code. For stylesheets, there is a package called identity-obj-proxy which is also already configured for this project. For all other assets a manual mock will be created called file.js that'll be created in a new __mocks__ folder within the base test directory.
To configure Jest to use these mocks the matching regex for the files will be added to the moduleNameMapper option.

ESLint

Since Jest makes use of the globally provided functions, ESLint's environment must be configured to know that Jest is used in the project. This can easily be done by adding the jest: true property to the env option in the .eslintrc.js config file.

NPM scripts

To allow to run all tests with various options there will be some new NPM scripts:

• test - Run all tests with Jest.
• test:cov - Run all tests with coverage reports.
• test:watch - Run all tests in Jest's watch mode.

Tasks

• Install required dependencies:
  • (dev) @babel/core
  • (dev) babel-jest
  • (dev) babel-plugin-react-remove-properties
  • (dev) babel-preset-gatsby
  • (dev) identity-obj-proxy
  • (dev) jest
  • (dev) jest-dom
  • (dev) react-testing-library
• Implement the Jest main configuration file (jest.config.js)
• Implement Jest's Babel configuration file (test/babel-config.js)
• Configure the Babel plugin to remove properties from production builds in Gatsby's Webpack configuration
• Implement Jest's test framework setup configuration file (test/setup.js) for react_testing-library and jest-dom
• Implement Gatsby specific mocks and shims
• Configure ESLint for Jest's global functions with the jest environment
• Implement NPM scripts for multiple test tasks
• Implement initial snapshot tests for existing components (they actually only render a React <Fragment>)