Testing

The blitz dependency also automatically installs and configures jest, @testing-library/react, @testing-library/react-hooks, and @testing-library/jest-dom for you.

Jest

Jest is a delightful testing framework that's simple to use. To run tests in your app, you will run jest or jest --watch from the terminal.

To make a new test, make a file named something.test.ts (or .js, .tsx, etc). Here's an example:

import something from "./somewhere"

it("does something", () => {
  const result = something()
  expect(result).toBe(true)
})

For more details on using Jest, read the Jest documentation

Jest Config

If you need to customize the jest config, you can do so in jest.config.js.

// jest.config.js
const nextJest = require("@blitzjs/next/jest")

const createJestConfig = nextJest({
  dir: "./",
})

const customJestConfig = {
  testEnvironment: "jest-environment-jsdom",
}

module.exports = createJestConfig(customJestConfig)

Client vs Server Environments

The following test files will run in the Jest server environment:

*.test.* files inside an api, queries, or mutations folder
*.server.test.* files

All other files will run in the Jest client environment (with jsdom).

@testing-library

@testing-library is a family of packages that help you test UI components in a user-centric way. It's a better alternative to Enzyme, if you've used that in the past.

The following packages are installed for you. Refer to their documentation as needed.

Testing Utilities

Blitz provides some basic testing utilities in the generated test/utils.tsx file. These are intended for use with Jest and React Testing Library to allow advanced configuration for your testing environment. Customizing this file can be useful for testing things like global providers as well as certain parts of your app which Blitz handles internally such as routing and data querying.

`BlitzProvider`

This component works as the global provider for data queries and mutations in your tests. Internally, it wraps the QueryClient component from react-query and adds some additional configuration options.

BlitzProvider accepts the following props:

client - The global query client used by React Query. By default the queryClient from @blitzjs/rpc (that you can access through getQueryClient function) is used unless you override it.
contextSharing - Controls whether or not the provider context can be shared across multiple applications. This can be useful when working in certain environments such as micro-frontends. Defaults to false.
dehydratedState - The server state passed along to the application containing the results of server-side queries. Useful for testing queries that need to be prerendered in markup and hydrated on the client.

End-to-end testing with Cypress

Cypress is a front-end testing framework that enables testing options for both unit tests and integration tests.

If you plan to integrate it into your Blitz application, you can look at our example with a Cypress setup. It includes a simple factory pattern, a command for creating and logging in a user, and a few example tests.

Topics