Testing

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

Vitest

Vitest is a delightful testing framework that's simple to use. To run tests in your app, you will run vitest run or vitest 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 Vitest, read the Vitest documentation

Vitest Config

If you need to customize the vitest config, you can do so in vitest.config.ts.

// vitest.config.ts
import { loadEnvConfig } from "@next/env"
import { defineConfig } from "vitest/config"

import react from "@vitejs/plugin-react"
import tsconfigPaths from "vite-tsconfig-paths"

const projectDir = process.cwd()
loadEnvConfig(projectDir)

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), tsconfigPaths()],
  test: {
    dir: "./",
    globals: true,
    setupFiles: "./test/setup.ts",
    coverage: {
      reporter: ["text", "json", "html"],
    },
  },
})

Client vs Server Environments

The following test files will run in the server environment:

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

All other files will run in the 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 Vitest 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