or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-umijs--test-utils

Testing utilities for Umi applications providing temporary test environments, HTML generation, React component rendering, and HTML content retrieval

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@umijs/test-utils@3.5.x

To install, run

npx @tessl/cli install tessl/npm-umijs--test-utils@3.5.0

index.mddocs/

@umijs/test-utils

@umijs/test-utils provides testing utilities for Umi applications, enabling developers to create controlled testing environments with temporary file generation, HTML output, React component rendering, and content retrieval. It integrates seamlessly with Umi's service architecture and React Testing Library.

Package Information

  • Package Name: @umijs/test-utils
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @umijs/test-utils
  • Peer Dependencies: @testing-library/react ^9.4.0, umi ^3.0.0

Core Imports

import { generateTmp, generateHTML, render, getHTML } from "@umijs/test-utils";

For CommonJS:

const { generateTmp, generateHTML, render, getHTML } = require("@umijs/test-utils");

Basic Usage

import { generateTmp, render, getHTML } from "@umijs/test-utils";
import { Service } from "@umijs/core";

// Generate temporary test environment
await generateTmp({
  cwd: "/path/to/project",
  Service,
});

// Render the generated app with React Testing Library
const { getByText } = render({ cwd: "/path/to/project" });

// Get HTML output for assertions
const htmlContent = getHTML({ cwd: "/path/to/project" });

Architecture

@umijs/test-utils is built around the following key components:

  • Service Integration: Leverages Umi's Service class to create isolated test environments
  • Memory History: Uses memory-based routing through an internal plugin for predictable testing
  • Temporary Generation: Creates .umi-test directories with all necessary Umi configuration and files
  • React Testing Library Integration: Provides seamless component rendering for unit tests
  • HTML Output: Generates and retrieves HTML files for integration testing

Capabilities

Temporary Environment Generation

Creates temporary Umi test environments with all necessary configuration files and dependencies.

/**
 * Generates temporary Umi test environment in .umi-test directory
 * @param opts - Configuration options for test environment generation
 * @returns Promise that resolves when generation is complete
 */
function generateTmp(opts: {
  cwd: string;
  Service?: typeof UmiService;
}): Promise<void>;

HTML Generation

Generates HTML output files for testing and integration scenarios.

/**
 * Generates HTML output for testing in dist directory
 * @param opts - Configuration options for HTML generation
 * @returns Promise that resolves when HTML generation is complete
 */
function generateHTML(opts: {
  cwd: string;
  Service?: typeof UmiService;
}): Promise<void>;

Component Rendering

Renders Umi applications using React Testing Library for component testing.

/**
 * Renders the generated Umi app using React Testing Library
 * @param opts - Configuration options for rendering
 * @returns RenderResult from React Testing Library for querying and interaction
 */
function render(opts: { cwd: string }): RenderResult;

HTML Content Retrieval

Retrieves generated HTML content as a string for assertions and validation.

/**
 * Retrieves generated HTML content from dist/index.html
 * @param opts - Configuration options for HTML retrieval
 * @returns HTML content as a string
 */
function getHTML(opts: { cwd: string }): string;

Types

import { Service as UmiService } from 'umi';
import { RenderResult } from '@testing-library/react';

interface GenerationOptions {
  /** Current working directory path for the test project */
  cwd: string;
  /** Optional Umi Service class override for custom service instances */
  Service?: typeof UmiService;
}

interface RenderOptions {
  /** Current working directory path containing the generated .umi-test files */
  cwd: string;
}

interface HTMLOptions {
  /** Current working directory path containing the generated dist files */
  cwd: string;
}

Usage Examples

Complete Testing Workflow

import { generateTmp, generateHTML, render, getHTML } from "@umijs/test-utils";
import { Service } from "@umijs/core";

// Setup test environment
const testCwd = "/tmp/test-project";

// Generate temporary test files
await generateTmp({
  cwd: testCwd,
  Service,
});

// Render app for component testing
const { getByText, container } = render({ cwd: testCwd });

// Assert component rendering
expect(getByText("Welcome")).toBeInTheDocument();

// Generate HTML for integration testing
await generateHTML({
  cwd: testCwd,
  Service,
});

// Get HTML content for validation
const htmlContent = getHTML({ cwd: testCwd });
expect(htmlContent).toContain("<title>My App</title>");

Custom Service Configuration

import { generateTmp } from "@umijs/test-utils";
import { Service } from "umi";

// Create custom service configuration
class CustomTestService extends Service {
  constructor(opts) {
    super({
      ...opts,
      // Custom test-specific configuration
    });
  }
}

// Use custom service for test generation
await generateTmp({
  cwd: "/path/to/project",
  Service: CustomTestService,
});

Error Handling

Functions may throw errors in the following scenarios:

  • File System Errors: When cwd path doesn't exist or lacks proper permissions
  • Service Errors: When Umi Service fails to initialize or execute commands
  • Generation Errors: When temporary file generation fails due to configuration issues
  • Render Errors: When React component rendering fails due to missing files or configuration
  • HTML Errors: When dist/index.html file doesn't exist or can't be read

File Structure

The package generates the following directory structure during testing:

project-root/
├── .umi-test/           # Temporary test environment
│   ├── umi.ts          # Main Umi app entry point
│   ├── core/           # Core Umi files
│   └── ...             # Other generated test files
└── dist/               # HTML output directory
    └── index.html      # Generated HTML file