Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
render
✓ import { render } from '@testing-library/react';
✗ const { render } = require('@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
✓ import '@testing-library/jest-dom';
✗ require('@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
✓ import { createConfig, configUmiAlias } from 'umi/test';
✗ import { configUmiAlias } from '@umijs/preset-jest';
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`.
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
// }
// }
Debug
Known issues
breakingThe `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.fixMigrate 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`.
affects: >=1.9.7 (for UmiJS v4+ projects)
gotchaIf `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.fixEnsure 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.
affects: >=1.0.0 (all versions using Jest with TypeScript)
gotchaEnvironment 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.fixDefine 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' }`. affects: >=1.0.0 (all versions)
Errors
Common errors & fixes
SyntaxError: Unexpected token import at ScriptTransformer._transformAndBuildScript
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.
fixIn 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
Environment variables configured for the UmiJS development server are not automatically available in the Jest test environment.
fixAdd 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' } };`. Audit
Dependencies
jestrequiredCore testing framework that umi-test is built upon.
@testing-library/reactrequiredCommonly used for React component testing within UmiJS projects, facilitated by umi-test's configuration.
@testing-library/jest-domrequiredProvides custom Jest matchers for testing the DOM state, frequently used with React Testing Library in UmiJS projects.