Unit Testing with Jest

Unit testing refers to the concept of testing and evaluating the quality of each unit of functionality made available by an implementation—in this case, a Gatsby site. Though Gatsby doesn’t offer a unit testing framework out of the box for efficiency reasons, Gatsby developers can use Jest to power unit testing with a minimal amount of overhead. However, because Gatsby’s build process is slightly unusual when it comes to the sort of JavaScript that Jest deals with, standard Jest implementations need some adjustment to work properly with Gatsby sites.

$ gatsby new gtdg-ch11-unit-testing gatsbyjs/gatsby-starter-blog
$ cd gtdg-ch11-unit-testing

$ npm install --save-dev jest babel-jest react-test-renderer 
  babel-preset-gatsby identity-obj-proxy

module.exports = {
  transform: { 
    "^.+\.jsx?$": `<rootDir>/jest-preprocess.js`,
  },
  moduleNameMapper: { 
    ".+\.(css|styl|less|sass|scss)$": `identity-obj-proxy`,
    ".+\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm >>>
|wav|mp3|m4a|aac|oga)$": `<rootDir>/__mocks__/file-mock.js`,
  },
  testPathIgnorePatterns: [ 
    `node_modules`,
    `\.cache`,
    `<rootDir>.*/public`
  ],
  transformIgnorePatterns: [`node_modules/(?!(gatsby)/)`], 
  globals: { 
    __PATH_PREFIX__: ``,
  },
  testURL: `http://localhost`, 
  setupFiles: [`<rootDir>/loadershim.js`], 
}

const React = require("react")
const gatsby = jest.requireActual("gatsby")

module.exports = {
  ...gatsby,
  graphql: jest.fn(),
  Link: jest.fn().mockImplementation(
    // These props cannot be used on `a` elements
    ({
      activeClassName,
      activeStyle,
      getProps,
      innerRef,
      partiallyActive,
      ref,
      replace,
      to,
      ...rest
    }) =>
      React.createElement("a", {
        ...rest,
        href: to,
      })
  ),
  StaticQuery: jest.fn(),
  useStaticQuery: jest.fn(),
}

import React from "react"
import renderer from "react-test-renderer"

import Bio from "../bio"

describe("Bio", () => {
  it("renders correctly", () => {
    const tree = renderer
      .create(<Bio />)
      .toJSON()
    expect(tree).toMatchSnapshot()
  })
})

import React from "react"
import renderer from "react-test-renderer"

import Header from "../header"

describe("Header", () => {
  it("renders correctly", () => {
    const tree = renderer
      .create(<Header siteTitle="Default Starter" />)
      .toJSON()
    expect(tree).toMatchSnapshot()
  })
})

  "scripts": {
    "build": "gatsby build",
    "develop": "gatsby develop",
    "format": "prettier --write "**/*.{js,jsx,ts,tsx,json,md}"",
    "start": "npm run develop",
    "serve": "gatsby serve",
    "clean": "gatsby clean",
    "test": "echo "Write tests! -> https://gatsby.dev/unit-testing" >>>
&& exit 1"
  }

  "scripts": {
    "build": "gatsby build",
    "develop": "gatsby develop",
    "format": "prettier --write "**/*.{js,jsx,ts,tsx,json,md}"",
    "start": "npm run develop",
    "serve": "gatsby serve",
    "clean": "gatsby clean",
    "test": "jest"
  }

$ npm test

$ npm test -- --watch

$ npm test -- -u

Testing React Components

The @testing-library/react library includes several helpers on top of react-dom and react-dom/test-utils to aid in ensuring that whenever the implementation (though not the functionality) of your component evolves, your tests won’t break. If you followed the steps in the previous section to install and configure Jest, you can pick up right here. Otherwise, check to ensure that you have Jest installed and configured correctly for your Gatsby site.

First, you’ll need to install several additional development dependencies (devDependencies):

$ npm install --save-dev @testing-library/react @testing-library/jest-dom

At the root of your project, in the same directory as package.json and gatsby-config.js, create a new file named setup-test-env.js containing the following import:

import "@testing-library/jest-dom/extend-expect"

Because this JavaScript file is executed every time Jest runs a test, you don’t need to add this import statement to every single test file. Now, you need to make Jest aware of this file and indicate its location. If your jest.config.js file is in the same state it was in at the end of the previous section, all you need to do is add a new key, setupFilesAfterEnv, to the module.exports object and identify the file you just created:

module.exports = {
  // Other Jest configuration.
  setupFiles: [`<rootDir>/loadershim.js`],
  setupFilesAfterEnv: ["<rootDir>/setup-test-env.js"],
}

Now, you can write tests that use @testing-library/react instead of react-test-renderer, and you have access to a much richer range of methods to use to introspect the rendered DOM elements and ensure they match your snapshots. Here is one example of a rudimentary test that ensures our <Bio /> component contains a particular string as opposed to the child elements it comes with by default in the unmodified Gatsby blog starter:

import React from "react"
import { render } from "@testing-library/react"

const Bio = () => (
  <div className="bio" data-testid="main-bio">
    Hello! This is my bio!
  </div>
)

test("Displays the correct title", () => {
  const { getByTestId } = render(<Bio />)
  // The next line describes our assertion.
  expect(getByTestId("main-bio"))
    .toHaveTextContent("Hello! This is my bio!")
})

We’ve covered unit tests at a high level in this section, but that doesn’t mean unit testing is the only type of testing you should be concerned with. For small-scale testing, unit tests do the trick, but sometimes it’s important to have a more holistic view of the visual design of your components as well as a sense of how your site performs end-to-end across multiple pages. We’ll turn our attention to these two types of tests next.

Visual Testing with Storybook

Though unit testing is powerful for situations where you need to maintain functional parity over time, sometimes a visual testing approach can be even more fruitful for maintaining a high-quality Gatsby implementation. One tool that has become popular for visual inspection and testing of JavaScript components is Storybook, a development environment for user interface components that allows developers to see their components across various states and understand what components they can leverage and what props they accept.

To install and configure Storybook, the quickest way to get started is to use the npx command, which comes packaged with NPM. NPX, used to execute packages (as opposed to the NPM installer), is useful because it will scaffold a directory structure with default configuration already in place to maximize productivity. Execute the following command in the root of your project:

$ npx -p @storybook/cli sb init

$ npm install -g @storybook/cli
$ sb init

Though Storybook will scaffold a fully constructed set of directories and files within them in the .storybook directory, Gatsby requires some adjustments to Storybook’s default configuration. If you open .storybook/main.js, you’ll find the following configuration:

module.exports = {
  stories: [
    "../src/**/*.stories.mdx",
    "../src/**/*.stories.@(js|jsx|ts|tsx)"
  ],
  addons: ["@storybook/addon-actions", "@storybook/addon-links"],
}

You’ll need to extend this Storybook configuration to embrace Gatsby’s own ES6 code that remains untranspiled, similarly to how we configured Jest to do so earlier in this chapter. Change your Storybook configuration to the following, adding webpackFinal after the lines in the previous example, as follows:

module.exports = {
  stories: [
    "../src/**/*.stories.mdx",
    "../src/**/*.stories.@(js|jsx|ts|tsx)"
  ],
  addons: ["@storybook/addon-actions", "@storybook/addon-links"], >>>
webpackFinal: async config => {
    config.module.rules[0].exclude = [/node_modules/(?!(gatsby)/)/]
    config.module.rules[0].use[0].loader = require.resolve("babel-loader")
    config.module.rules[0].use[0].options.presets = [
      require.resolve("@babel/preset-react"),
      require.resolve("@babel/preset-env"),
    ]
    config.module.rules[0].use[0].options.plugins = [
      require.resolve("@babel/plugin-proposal-class-properties"),
      require.resolve("babel-plugin-remove-graphql-queries"),
    ]
    config.resolve.mainFields = ["browser", "module", "main"]
    return config
  },
}

These lines configure Webpack to handle the Gatsby module correctly and to ensure that Storybook uses Gatsby’s ES6 entry point (which prepopulates dependencies) rather than the default CommonJS entry point (which executes dependencies on demand). Now, you need to provide a configuration file that will add certain global parameters and Storybook decorators to ensure Storybook works with Gatsby. Replace the contents of the file named preview.js in the .storybook directory with the following code:

import { action } from "@storybook/addon-actions"

// This prevents Gatsby Link from triggering errors in Storybook.
global.___loader = {
  enqueue: () => {},
  hovering: () => {},
}

// This global variable prevents the "__BASE_PATH__ is not defined" error 
// inside Storybook.
global.__BASE_PATH__ = "/"

// Navigating through a Gatsby app using gatsby-link or any other
// gatsby component will use the `___navigate` method. In Storybook
// it makes more sense to log an action than doing an actual navigate.
// Check out the actions addon docs for more info:
// https://github.com/storybookjs/storybook/tree/master/addons/actions.

window.___navigate = pathname => {
  action("NavigateTo:")(pathname)
}

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
}

With both of these configuration files in place, you can now write Storybook stories. Storybook will seek any files with a .stories.js extension and load them automatically in your Storybook interface for you. For Gatsby components, these stories can live alongside the components in the same directory. But for Gatsby pages, since Gatsby restricts what JavaScript files are permitted in the src/pages directory, you’ll need to create a __stories__ directory in the src directory.

A full walkthrough of Storybook is outside the scope of this book, but as an example adapted from the Gatsby documentation, here’s a Storybook story, which in Storybook parlance describes a rendered component that is displayed in the Storybook interface:

import React from "react"

export default {
  title: "Bio",
}

export const bioStory = () => (
  <div style={{ padding: "1rem", backgroundColor: "#ccc" }}>
    <h1 style={{ color: "blue" }}>Hello world and Storybook!</h1>
  </div>
)

End-to-End Testing with Cypress

Visual testing and unit testing both permit small-scale observation of how quality changes over time across individual Gatsby components and pages. However, there are often situations where, as a Gatsby developer, it will be desirable to perform end-to-end (e2e) testing that involves not only single pages and components but navigating through an entire Gatsby site with multiple pages and components involved in one test.

This is particularly important for accessibility testing when it comes to accessible client-side routing, as an e2e test can reveal when navigating between pages isn’t working properly due to a missing Reach route change or other issue. Though there are multiple systems commonly used for e2e testing, Cypress is a common choice.

Because e2e testing typically requires a second parallel server to be running alongside Gatsby’s local development server, you’ll want to use the start-server-and-test library to manage both in parallel. Add the following to your development dependencies (devDependencies):

$ npm install --save-dev cypress start-server-and-test  
  @testing-library/cypress

Cypress comes with the ability to configure certain global settings. Do that now by creating a new cypress.json file in your project root:

{
  "baseUrl": "http://localhost:8000/"
}

This baseUrl configuration will ensure that every URL that Cypress visits or issues a request to will be prefixed with the correct domain for our Gatsby development server. Next, you need to add Cypress scripts to our package.json to ensure you can run Cypress tests from the terminal:

{
  "scripts": {
    "develop": "gatsby develop",
    "test:jest": "jest",
    "cy:open": "cypress open",
    "test:e2e": "start-server-and-test develop http://localhost:8000 cy:open"
  }
}

If you’re using Cypress in the context of a CI provider like CircleCI or Travis, you will need to use the cypress run command instead of cypress open:

"cy:run": "cypress run",

To kick off a Cypress test, execute the following after installing other dependencies required for Cypress:

$ npm run test:e2e

You’ll see a new directory named cypress created within the root of your project.

"test:e2e": "START_SERVER_AND_TEST_INSECURE=1 >>>
start-server-and-test develop >>>
http://localhost:8000 cy:open"

One of the most common use cases for end-to-end testing with Cypress is accessibility testing, which requires a library such as Axe. Though building in automated accessibility testing is a best practice for Gatsby sites, it’s also a best practice to perform at least some manual accessibility testing lest something fall through the cracks.

You can install those additional Axe dependencies now:

$ npm install --save-dev cypress-axe axe-core

Because you already ran Cypress once, you can open the already created cypress/support/index.js file and import the additional dependencies you now need, including @testing-library/cypress:

import "./commands"
import "cypress-axe"
import "@testing-library/cypress/add-commands"

Though Cypress will look for tests within the cypress/integration directory by default, accessibility tests that visit multiple pages are considered end-to-end tests and should be placed in a new cypress/e2e directory as a best practice. In this case, you’ll need to configure an integrationFolder in your Cypress configuration as follows:

{
  "baseUrl": "http://localhost:8000/",
  "integrationFolder": "cypress/e2e"
}

To finish our exploration of Cypress end-to-end testing, let’s create a rudimentary test that checks for the absence of accessibility violations on the initial load of the home page of our example Gatsby site, which in this chapter is our Gatsby blog starter. Create a new file in the cypress/e2e directory named accessibility.test.js with the following contents:

/// <reference types="Cypress" /> 

describe("Accessibility tests", () => {
  beforeEach(() => {
    cy.visit("/").get("main").injectAxe() 
  })
  it("Has no detectable accessibility violations on load", () => {
    cy.checkA11y() 
  })
  it("Navigates to blog post and checks for accessibility violations", () => {
    cy.findByText(/new beginnings/i) 
     .click()
     .checkA11y()
  })
})

This comment facilitates autocompletion if you’re using certain IDEs (such as those with IntelliSense).

As the cy.visit() method suggests, Cypress visits the home page of your Gatsby site and waits until the page load is complete. The subsequent chained methods find the <main> HTML element (using cy.get(), as Gatsby may “finish” loading too quickly), where the Axe accessibility testing API is injected and made available.

The cy.checkA11y() method performs a check for any accessibility errors on the home page.

The cy.findByText() method finds the first blog post displayed in the Gatsby blog starter and navigates to it, performing another check for accessibility errors on that page.

You can extend this end-to-end accessibility test by working through some additional assertions using the should method to check whether a given link has text legible to screen readers and has an href attribute, as is expected of all links:

describe("Accessibility tests", () => {
  // Previous assertions.
  it("Focuses on the header link and asserts its attributes", () => {
    cy.findAllByText("Gatsby Starter Blog").focus()
    cy.focused()
      .should("have.text", "Gatsby Starter Blog")
      .should("have.attr", "href", "/")
  })
})

Debugging Static Builds

Because Gatsby’s static build process ultimately generates a series of HTML files that maximize the speed at which Gatsby sites load in the browser, some issues can be difficult to diagnose. In many cases, issues surrounding static builds involve inaccessible globals or Webpack bundling issues. The Gatsby documentation outlines four specific cases that are common in Gatsby sites:

1. Undefined browser globals. Because JavaScript can be executed on the server side or the client side, if your code references the window or document object, those objects may be unavailable except when the Gatsby site is loaded in a browser. During the build process, you may run into errors such as window is not defined, as it is undefined before the site reaches the browser. There are two ways to handle this:

   1. If your code requires the use of the window or document object in the browser, perform a check to ensure window or document is defined so that the code within the check is only executed in the browser, as follows:

      if (typeof window !== `undefined`) {
        // Your window-reliant code here.
      }

   2. If the offending code with references to the window or document object is within the render function of a React component, you’ll need to relocate that code into a componentDidMount lifecycle method in React or, if you’re using React hooks, into a useEffect hook implementation to prevent its execution outside the browser.

2. Improperly exported pages. Because Gatsby automatically generates pages based on the contents of the pages directory, you must ensure that all files within that directory are exporting either a React component or a string. Otherwise, Gatsby’s automatic page generation will fail.

3. Collision of import and require in a single file. In Webpack 4, the bundler no longer permits the use of both import and require statements within the same file. Instead, Gatsby recommends using only import statements within Gatsby files, including gatsby-ssr.js and gatsby-browser.js.

4. Improper hydration. Gatsby allows for client-side functionality to proceed by hydrating rendered HTML with React. If this hydration doesn’t happen correctly, you will run into inconsistencies between the results of the gatsby develop and gatsby build commands. If you discover inconsistencies between the build results, it’s likely that some logic in gatsby-ssr.js or gatsby-browser.js is causing a mismatch between the HTML generated by the server and that understood by the client.

exports.onCreateWebpackConfig = ({ stage, loaders, actions }) => {
  if (stage === "build-html") {
    actions.setWebpackConfig({
      module: {
        rules: [
          {
            test: /module-without-window-defined-check/,
            use: loaders.null(),
          },
        ],
      },
    })
  }
}

Debugging the Build Process

Because both the gatsby build and gatsby develop scripts are technically Node.js applications at their core, you can debug issues that occur within the execution of those scripts using commonly available standard approaches and tools for Node.js application development. Using Node.js debugging tools can be useful for situations where you need to identify a problem area in a gatsby-node.js file or another file that influences the build process or instantiation of the local development server.

For Gatsby developers familiar with debugging JavaScript in the browser, the console object is available with a console.log() method to print any values that need verification or introspection to the browser console during execution:

console.log(anObject)

Because the console object is also built into Node.js, you can add an invocation of console.log() to any executed code in your gatsby-node.js file or any other file—including Gatsby pages and components—to print the variable’s value into the terminal output, just like in the browser console. Consider the following example from gatsby-source-filesystem, in which we print the args variable to the Node.js console in the terminal:

const { createFilePath } = require("gatsby-source-filesystem")

exports.onCreateNode = args => {
  console.log(args)
  const { actions, node } = args
  if (node.internal.type === "MarkdownRemark") {
    const { createNodeField } = actions

    const value = createFilePath({ node, getNode })
    createNodeField({
      name: `slug`,
      node,
      value,
    })
  }
}

Observe the difference between console.log() statements that are executed at build time and can be seen in the terminal, like in the gatsby-node.js file, and those statements that are executed on the client side, whose results will display in the browser console instead of the terminal.

Debugging Server-Side Rendering Issues

Gatsby performs server-side rendering as part of its build process to facilitate faster page loads on the browser. Hooking into this rendering process involves creating or modifying the gatsby-ssr.js file. One of the server-side rendering APIs commonly leveraged during the build process is the replaceRenderer API, which can be used to customize or otherwise adjust the ways in which Gatsby renders out the contents of your site in static form. The most common use cases for this API generally involve the use of Redux, Styled Components, or other CSS-in-JavaScript libraries that need to influence the markup rendered on the server side.

The replaceRenderer API is employed by various Gatsby plugins in the ecosystem to extend Gatsby so it supports these libraries, or any custom code that needs to modify how Gatsby generates its initial HTML output for the browser. This logic is executed solely during the build process (i.e., when gatsby build is executed), not during local development (gatsby develop). Sometimes, when multiple plugins require usage of the replaceRenderer API through their respective gatsby-ssr.js files, conflicts can occur between them.

If multiple plugins are simultaneously using the API at the same time, during the build process you’ll encounter an error that looks like the following, where default-site-plugin represents the local Gatsby site’s gatsby-ssr.js file, not the plugin’s:

warning replaceRenderer API found in these plugins:
warning gatsby-plugin-one, default-site-plugin
warning This might be an error, see: https://www.gatsbyjs.com/docs/debugging-
replace-renderer-api/
warning Duplicate replaceRenderer found, skipping gatsby-ssr.js for plugin: 
gatsby-plugin-one

The easiest way to correct an issue with conflicting gatsby-ssr.js files is to identify the offending replaceRenderer API code in the plugin’s gatsby-ssr.js file and copy it into your Gatsby site’s own gatsby-ssr.js file. This needs to happen because only the gatsby-ssr.js file for the site being built will be executed during the build process, which only accepts a single gatsby-ssr.js file.

Debugging Cache Issues

Gatsby contains its own internal cache that is used to accelerate plugin handling, and especially the data sourcing process. Sometimes the Gatsby cache can fail, manifesting in strange and perhaps silent errors involving stale content, where the most up-to-date content doesn’t display despite an upstream content update, and recent modifications to plugin code that don’t appear to execute.

Gatsby uses a .cache directory to cache certain elements of the Gatsby site. Starting with Gatsby version 2.1.1, the gatsby clean command is available to clear out the Gatsby cache and ensure the most recent versions of your plugin code and content are represented in your site:

$ gatsby clean

Prior to v2.1.1, an NPM script was required in the site’s package.json file, as follows:

{
  "scripts": {
    "clean": "rm -rf .cache"
  }
}

To run this NPM script for versions 2.1.0 and earlier, execute:

$ npm run clean

Debugging Asynchronous Lifecycle Methods

For Gatsby developers who are used to previous paradigms of JavaScript programming, the introduction of specific syntax for asynchronicity into JavaScript may be a rude awakening. As of Node.js version 8, Node.js can natively handle the async and await keywords, which are used to identify functions that should be treated asynchronously but are written as if they were synchronous. The async and await keywords are particularly useful for situations where consecutive Promises were chained together in older JavaScript, which often led to confusing and hard-to-read code.

Within Gatsby, certain lifecycle methods, like createPages in Gatsby’s Node APIs, are presumed by the framework to be asynchronous. This means it is generally assumed that a value may not immediately be available upon the execution of the createPages logic. Methods like createPages will eventually resolve to a value (or not resolve, throwing an error) represented by a Promise. In asynchronous JavaScript with Promises, we wait for the Promise to resolve to a usable value, and in Gatsby’s case, the lifecycle method in question (such as createPages) is considered complete once the Promise resolves.

Gatsby’s Node APIs handle a great deal of asynchronous logic, such as requests for data from external sources, invocations of graphql, and more. For this reason, Gatsby developers may encounter difficult-to-debug errors when writing logic in gatsby-node.js that does not correctly return Promises. The resolutions of these promises may occur after the lifecycle method is considered by Gatsby to be complete, thus returning a value that was expected but now is never used.

When writing logic in gatsby-node.js, pay close attention to whether a method is expected to be asynchronous or not. For instance, in the following example, not including the await keyword shown ahead of the invocation of graphql would result in absent data, since createPages will not wait for the value representing the result of graphql to be returned:

exports.createPages = async function ({ actions, graphql }) {
  await graphql(`
    {
      allMarkdownRemark {
        edges {
          node {
            fields {
              slug
            }
          }
        }
      }
    }
  `).then(res => {
    res.data.allMarkdownRemark.edges.forEach(edge => {
      const slug = edge.node.fields.slug
      actions.createPage({
        path: slug,
        component: require.resolve(`./src/templates/article.js`),
        context: {
          slug
        },
      })
    })
  })
}

There are also scenarios where it is necessary to wait for a series of unconnected Promises to resolve before proceeding. In JavaScript, the Promise.all() method encapsulates multiple asynchronous actions, such as a data fetch (e.g., fetch().then()) that represents a Promise but needs to query multiple APIs or data sources. Consider the following example, in which we retrieve data from multiple APIs:

const fetch = require("node-fetch")

exports.createPages = async function ({ actions, graphql }) {
  const [siteAData, siteBData] = await Promise.all([
    fetch("https://site-a.com/api/articles").then(res => res.json()),
    fetch("https://site-b.com/api/products").then(res => res.json()),
  ])

  // Further logic with actions.createPage.
}

Because one of the fetch operations may conclude before the other, we need to ensure that Gatsby awaits the resolution of all Promises contained therein before proceeding and marking the createPages lifecycle method as complete.