@umijs/test

@umijs/test provides Jest testing utilities and configurations specifically designed for Umi applications. It offers pre-configured Jest setups with support for multiple JavaScript transformers (esbuild, swc, ts-jest), TypeScript/JSX transformation, CSS module mocking, and both Node.js and browser testing environments.

Package Information

• Package Name: @umijs/test
• Package Type: npm
• Language: TypeScript
• Installation: npm install @umijs/test

Core Imports

import { createConfig, JSTransformer } from "@umijs/test";
import type { Config } from "@umijs/test";

For CommonJS:

const { createConfig } = require("@umijs/test");

Basic Usage

import { createConfig } from "@umijs/test";

// Basic Jest configuration with default esbuild transformer
const jestConfig = createConfig();

// Configuration with specific transformer
const jestConfigWithSwc = createConfig({
  jsTransformer: 'swc',
  target: 'node'
});

// Browser environment configuration
const browserConfig = createConfig({
  jsTransformer: 'esbuild',
  target: 'browser',
  jsTransformerOpts: {
    target: 'es2020'
  }
});

export default jestConfig;

Architecture

@umijs/test is built around several key components:

• Configuration Factory: The createConfig function generates complete Jest configurations with Umi-specific defaults
• Transformer System: Pluggable JavaScript/TypeScript transformation supporting esbuild, swc, and ts-jest
• Module Resolution: Custom resolver that prioritizes main field over module field in package.json
• Environment Setup: Automatic polyfill injection for test environments (fetch via isomorphic-unfetch)
• CSS Module Handling: Built-in CSS/LESS/SASS/SCSS/Stylus module mocking via identity-obj-proxy

Capabilities

Jest Configuration Creation

Creates a pre-configured Jest configuration optimized for Umi applications with sensible defaults and transformer support.

/**
 * Creates a Jest configuration with Umi-specific defaults
 * @param opts - Configuration options
 * @returns Complete Jest configuration object
 */
function createConfig(opts?: {
  /** JavaScript transformer to use - defaults to 'esbuild' */
  jsTransformer?: JSTransformer;
  /** Runtime environment - defaults to 'node' */
  target?: 'node' | 'browser';
  /** Additional options passed to the JS transformer */
  jsTransformerOpts?: any;
}): Config.InitialOptions;

Configuration Defaults:

The createConfig function provides these pre-configured settings:

• Test Match Patterns: **/*.test.(t|j)s(x)? - Matches test files with .test extension
• Transform Patterns: Handles TypeScript, JavaScript, JSX, and .mjs files
• Module Name Mapping: CSS/LESS/SASS/SCSS/Stylus files mapped to identity-obj-proxy
• Test Timeout: 30 seconds (30000ms)
• Transform Ignore Patterns: Transforms all node_modules (empty ignore pattern)
• Path Ignore Patterns: Ignores compiled and fixtures directories
• Setup Files: Automatically includes isomorphic-unfetch polyfill
• Custom Resolver: Uses package.json main field prioritization
• Test Environment: Node.js by default, jsdom when target: 'browser'

Usage Examples:

// Default configuration with esbuild
const defaultConfig = createConfig();

// Swc transformer for faster builds
const swcConfig = createConfig({
  jsTransformer: 'swc'
});

// Browser environment with jsdom
const browserConfig = createConfig({
  target: 'browser',
  jsTransformer: 'esbuild',
  jsTransformerOpts: {
    target: 'es2020',
    sourcemap: true
  }
});

// ts-jest for maximum TypeScript compatibility
const tsJestConfig = createConfig({
  jsTransformer: 'ts-jest'
});

Types

/** Supported JavaScript/TypeScript transformers */
type JSTransformer = 'esbuild' | 'swc' | 'ts-jest';

/** Jest configuration interface (re-exported from @jest/types) */
interface Config {
  // Complete Jest configuration type from @jest/types
  InitialOptions: {
    testMatch?: string[];
    transform?: Record<string, any>;
    moduleNameMapper?: Record<string, string>;
    testTimeout?: number;
    transformIgnorePatterns?: string[];
    setupFiles?: string[];
    resolver?: string;
    testEnvironment?: string;
    // ... and all other Jest configuration options
  };
}

Internal Components

The package includes several internal utilities that power the main API:

EsBuild Transformer

Custom Jest transformer using esbuild for fast TypeScript/JavaScript compilation:

• File Support: .ts, .tsx, .js, .jsx, .mjs files
• Jest Mock Support: Special handling for jest.mock() calls via Babel transformation
• Source Maps: Full source map support for debugging
• Caching: MD5-based caching for improved performance
• ESBuild Options: Configurable via jsTransformerOpts parameter

Custom Resolver

Jest resolver that modifies package.json resolution:

• Main Field Priority: Prioritizes main field over module field
• Compatibility: Ensures better compatibility with CommonJS-first packages
• Fallback: Uses Jest's default resolver as fallback

Setup Files

Automatic environment setup:

• Fetch Polyfill: Includes isomorphic-unfetch for fetch API support in Node.js test environments
• Auto-injection: Automatically included in all Jest configurations

Error Handling

The package handles several common testing scenarios:

• Unknown Transformer: Throws descriptive error for unsupported jsTransformer values
• Transform Warnings: Logs esbuild warnings to console during transformation
• Module Resolution: Falls back to default Jest resolver if custom resolution fails

Advanced Configuration

For advanced use cases, you can extend the returned configuration:

import { createConfig } from "@umijs/test";

const baseConfig = createConfig({
  jsTransformer: 'esbuild',
  target: 'node'
});

// Extend with custom settings
const customConfig = {
  ...baseConfig,
  collectCoverage: true,
  coverageDirectory: 'coverage',
  coverageReporters: ['text', 'lcov'],
  setupFilesAfterEnv: ['<rootDir>/test-setup.ts']
};

export default customConfig;