UmiJS Jest Testing Utility

Common errors

• SyntaxError: Unexpected token import at ScriptTransformer._transformAndBuildScript

  cause Jest's transformer (often Babel) encounters ES module syntax (e.g., `import`) in files it's not configured to transform, typically when TypeScript's `module` option is `es6` or `esnext` for the test compilation.
  fix In your `jest.config.js`, ensure the `transform` and `transformIgnorePatterns` options are correctly set, or create a `tsconfig.test.json` with `"module": "commonjs"` and point Jest to it. UmiJS presets usually handle this by default.

• process.env.YOUR_VARIABLE is undefined

  cause Environment variables configured for the UmiJS development server are not automatically available in the Jest test environment.
  fix Add a `globals` section to your `jest.config.js` to define the required `process.env` variables for your test runs. For example: `module.exports = { globals: { 'process.env.PRODUCT_MODEL': 'test-model' } };`.

Warnings

• breaking The `umi-test` package (v1.9.7) is considered abandoned. For UmiJS v4 and newer, use `@umijs/preset-jest` or `@umijs/max` for Jest integration, as the framework's testing strategy has evolved significantly. Direct usage of `umi-test` with UmiJS v4 is not recommended and will likely lead to compatibility issues.
  Fix: Migrate testing setup to use `@umijs/preset-jest` in your `jest.config.js` or leverage the built-in testing features of `@umijs/max`. Example: `npm install --save-dev jest @umijs/preset-jest @testing-library/react @testing-library/jest-dom`.
• gotcha If `tsconfig.json` has `module` set to `es6` or `esnext`, Jest might fail with a `SyntaxError: Unexpected token import` because Jest's default transformer (Babel) may not correctly process ES modules in `node_modules` or `src` without proper configuration.
  Fix: Ensure your `jest.config.js` or `tsconfig.json` (specifically for test environment) correctly configures module resolution for Jest. A common fix is to set `module` to `commonjs` in a dedicated `tsconfig.test.json` that Jest uses, or to configure `transformIgnorePatterns` in `jest.config.js` to include relevant modules for transformation. For UmiJS, `@umijs/preset-jest` usually handles this.
• gotcha Environment variables (`process.env.VAR_NAME`) might appear `undefined` when running tests, especially if they are usually defined by the UmiJS build process (e.g., in `umi dev`). Test environments often require explicit variable definitions.
  Fix: Define necessary environment variables in your `jest.config.js` using the `globals` option, or ensure they are set in the shell environment before running tests. For example: `globals: { 'process.env.VAR_NAME': 'test_value' }`.

Install

• npm install umi-test npm
• yarn add umi-test yarn
• pnpm add umi-test pnpm

Imports

• render
  wrong:

  const { render } = require('@testing-library/react');

  correct:

  import { render } from '@testing-library/react';

  Commonly imported for rendering React components in UmiJS tests. While `umi-test` sets up the environment, the actual testing utilities come from `@testing-library/react`. ESM syntax is standard for test files.
• jest-dom
  wrong:

  require('@testing-library/jest-dom');

  correct:

  import '@testing-library/jest-dom';

  Imports extend Jest's `expect` with DOM-specific matchers. This is a side-effect import and is crucial for ergonomic DOM assertions. ESM syntax is preferred in modern test setups.
• configUmiAlias
  wrong:

  import { configUmiAlias } from '@umijs/preset-jest';

  correct:

  import { createConfig, configUmiAlias } from 'umi/test';

  For Umi v4, the `umi/test` module provides utilities for Jest configuration, including alias resolution. This is not directly from `umi-test` but reflects the modern UmiJS testing approach which superseded `umi-test`.

Quickstart

Demonstrates a basic unit test for a React component within an UmiJS project, utilizing Jest and React Testing Library, which `umi-test` (or `@umijs/preset-jest` for Umi v4) would configure.

import { render, screen } from '@testing-library/react';
import '@testing-library/jest-dom';
import React from 'react';

// Assuming you have a component like this in src/components/Greeting.tsx
const Greeting = ({ name = 'World' }) => <h1>Hello, {name}!</h1>;

describe('Greeting Component', () => {
  test('renders default greeting', () => {
    render(<Greeting />);
    expect(screen.getByText('Hello, World!')).toBeInTheDocument();
  });

  test('renders greeting with a specific name', () => {
    render(<Greeting name="Umi" />);
    expect(screen.getByText('Hello, Umi!')).toBeInTheDocument();
  });

  test('renders a snapshot correctly', () => {
    const { asFragment } = render(<Greeting name="Snapshot" />);
    expect(asFragment()).toMatchSnapshot();
  });
});

// To run this test, your package.json would typically have:
// {
//   "scripts": {
//     "test": "jest"
//   },
//   "jest": {
//     "preset": "@umijs/preset-jest" // Or earlier, configured by umi-test
//   }
// }