#Testing

Because Rspack uses a mix of Rust and Node.js code, different testing strategies are used for each.

#Rust testing

#Running Rust tests

You can run the Rust code's test cases using ./x test rust or cargo test.

#Writing Rust tests

Test cases are written within the Rust code. For example:

fn add(a: u8, b: u8) -> u8 {
  a + b
}

#[test]
fn test_add() {
  assert_eq!(add(1, 2), 3);
}

For more information, please refer to: Rust: How to Write Tests

#Node.js testing

Rspack's test cases include the following:

• Rspack core test cases are stored in the tests/rspack-test folder and will run the test cases by simulating the build process. In general, test cases should be added in this folder.
• Test cases for other Rspack packages are stored in the packages/{name}/tests folder and should only be added or modified when modifying that package.

You can run Rspack tests by running ./x test unit or pnpm run test:unit at the root folder.

You can also go to the tests/rspack-test folder and run npm run test to run test cases and add some arguments:

• When refreshing test snapshots is needed: Add -u, like npm run test -- -u
• When filtering test cases is needed: Add -t, like npm run test -- -t configCases/asset to only run test cases from the tests/rspack-test/configCases/asset folder. Pattern matching supports regex, see rstest for details.

#Running tests

You can run these test cases in the following ways:

• Run ./x test unit or pnpm run test:unit from the root directory.
• Or run npm run test from the tests/rspack-test directory.
• To update snapshots, run npm run test -- -u from the tests/rspack-test directory.
• To pass specific rstest cli arguments, run npm run test -- {args} from the tests/rspack-test directory.
• To filter specific test cases, run npm run test -- -t path-of-spec from the tests/rspack-test directory.
  • Like npm run test -- -t configCases/asset to only run test cases from the tests/rspack-test/configCases/asset folder (config will be automatically mapped to configCases, and other folders will work in a similar way).
• To use Rspack Wasm for running test cases, you need to additionally configure the following environment variables:
  1. NAPI_RS_FORCE_WASI=1: Forces the use of Rspack Wasm instead of native binding
  2. WASM=1: Enables Wasm-specific test configurations
  3. NODE_NO_WARNINGS=1: Disables Node.js Wasm warnings.

  NAPI_RS_FORCE_WASI=1 WASM=1 NODE_NO_WARNINGS=1 pnpm run test:unit

#Directory structure

The structure of the tests/rspack-test folder is as follows:

.
├── js # Used to store build artifacts and temporary files
├── __snapshots__ # Used to store test snapshots
├── {Name}.test.js # Entry for normal testing
├── {Name}.hottest.js # Entry for hot snapshot testing
├── {Name}.difftest.js # Entry for diff testing
├── {name}Cases # Directory to store test cases
└── fixtures # General test files

The {Name}.test.js is the entry file for tests, which will walk the {name}Cases folder and run cases in it. Therefore, when you need to add or modify test cases, add them to the relevant {name}Cases folder based on the type of testing.

#Test types

The existing test types are:

• Normal: Used to test core build processes without configuration changes. This type is used when testing does not require adding rspack.config.js.
• Config: Used to test build configuration options. If your test needs specific configuration added through rspack.config.js to run and does not fit other scenarios, use this test type.
• Hot: Used to test whether HMR runs correctly. This type includes HotNode with a fixed target=async-node, HotWeb with a fixed target=web, and HotWorker with a fixed target=webworker.
• HotSnapshot: Used to test whether HMR can generate correct intermediate artifacts. This test type shares test cases with the Hot type and generates snapshots for incremental artifacts for each HMR.
• Watch: Used to test incremental compilation after modifying files in Watch mode.
• StatsOutput: Used to test the console output log after the build ends.
• StatsAPI: Used to test the Stats object generated after the build ends.
• Diagnostic: Used to test the formatted output information for warnings/errors generated during the build process.
• Hash: Used to test whether hash generation works correctly.
• Compiler: Used to test Compiler/Compilation object APIs.
• Defaults: Used to test the interaction between configuration options.
• Error: Used to test the interaction between compilation.errors and compilation.warnings.
• Hook: Used to test various hook functionalities.
• TreeShaking: Used to test Tree Shaking-related features.
• Builtin: Used to test plugins with built-in native implementations.

Please prioritize adding test cases within the above test types.

#Normal

The writing of the case is the same as a regular rspack project, but it does not include the rspack.config.js file and will use the provided configuration for building.

#Config

This test case is similar to a regular rspack project. You can specify the build configuration by adding a rspack.config.js and control various behaviors during testing by adding a test.config.js. The structure of the test.config.js file is as follows:

type TConfigCaseConfig = {
  noTests?: boolean; // Do not run the test output and end the test
  beforeExecute?: () => void; // Callback before running the output
  afterExecute?: () => void; // Callback after running the output
  moduleScope?: (ms: IModuleScope) => IModuleScope; // Module context variables when running the output
  findBundle?: (
    // Function for obtaining output when running the output, can control the output at a finer granularity
    index: number, // Compiler index in multi-compiler scenario
    options: TCompilerOptions<T>, // Build configuration object
  ) => string | string[];
  bundlePath?: string[]; // Output file name when running the output (prior to findBundle)
  nonEsmThis?: (p: string | string[]) => Object; // this object during CJS output runtime, defaults to current module's module.exports if not specified
  modules?: Record<string, Object>; // Pre-added modules when running the output, will be prioritized when required
  timeout?: number; // Timeout for the test case
};

/** @type {import("../../../..").TConfigCaseConfig} */
module.exports = {
  // ...
};

#Hot

This test case is similar to a regular rspack project. You can specify the build configuration by adding a rspack.config.js.

And also, within the file that has changed, use --- to separate the code before and after the change:

module.exports = 1; // Initial build
---
module.exports = 2; // First hot update
---
module.exports = 3; // Second hot update

In the test case code, use the NEXT_HMR method to control the timing of file changes and add test code within it:

import value from './file';

it('should hot update', done => {
  expect(value).toBe(1);
  // Use tests/rspack-test/hotCases/update.js to trigger update
  await NEXT_HMR();
  expect(value).toBe(2);
  await NEXT_HMR();
  expect(value).toBe(3);
});

module.hot.accept('./file');

#HotSnapshot

Uses the same test cases as Hot{Target}, and generates a __snapshots__/{target}/{step}.snap.txt file in the case folder to perform snapshot testing on the incremental artifacts of each HMR.

The snapshot structure is as follows:

• Changed Files: Source code files that trigger this HMR build
• Asset Files: Artifact files of this HMR build
• Manifest: Contents of the hot-update.json metadata file for this HMR build, where:
  • "c": Id of the chunks to be updated in this HMR
  • "r": Id of the chunks to be removed in this HMR
  • "m": Id of the modules to be removed in this HMR
• Update: Information about the hot-update.js patch file for this HMR build, including:
  • Changed Modules: List of modules included in the patch
  • Changed Runtime Modules: List of runtime modules included in the patch
  • Changed Content: Snapshot of the patch code

#Watch

As the Watch build needs to be performed in multiple steps, you can specify the build configuration by adding a rspack.config.js. The directory structure of its cases is special and will use incrementing numbers to represent change batches:

.
├── 0 # WATCH_STEP=0, initial code for the case
├── 1 # WATCH_STEP=1, diff files for the first change
├── 2 # WATCH_STEP=2, diff files for the second change
└── rspack.config.js

In the test code, you can use the WATCH_STEP variable to get the current batch number of changes.

#StatsOutput

The writing of the cases is the same as in a regular rspack project. After running, the console output information will be captured in snapshots and stored in tests/rspack-test/__snapshots__/StatsOutput.test.js.snap.

#Stats API

This test uses tests/rspack-test/fixtures as the source code for the build, so the test case is written as a single file. Its structure is as follows:

type TStatsAPICaseConfig = {
  description: string, // Case description
  options?: (context: ITestContext) => TCompilerOptions<T>, // Case build configuration
  build?: (context: ITestContext, compiler: TCompiler<T>) => Promise<void>, // Case build method
  check?: (stats: TCompilerStats<T>, compiler: TCompiler<T>) => Promise<void>, // Function to check the stats for the case
};

/** @type {import('../..').TStatsAPICaseConfig} */
module.exports = {
  // ...
};

#Diagnostic

This test case is similar to a typical rspack project and can specify build configurations by adding a rspack.config.js. Additionally, it will add a stats.err file in the case directory to store snapshots of warnings/errors. To refresh, use the -u parameter.

#Hash

This test case is similar to a typical rspack project, but it will add a test.config.js file in the case directory and specify a validate() method to check the hash information in the stats object after the build is complete:

type THashCaseConfig = {
  validate?: (stats: TCompilerStats<T>) => void,
};

/** @type {import('../..').THashCaseConfig} */
module.exports = {
  // ...
};

#Compiler

This test uses tests/rspack-test/fixtures as the source code for the build, so the test case is written as a single file. Its structure is as follows:

interface TCompilerCaseConfig {
  description: string; // Description of the test case
  options?: (context: ITestContext) => TCompilerOptions<T>; // Test case build configuration
  compiler?: (context: ITestContext, compiler: TCompiler<T>) => Promise<void>; // How the compiler is created for the test case
  build?: (context: ITestContext, compiler: TCompiler<T>) => Promise<void>; // Build method for the test case
  check?: (
    context: ITestContext,
    compiler: TCompiler<T>,
    stats: TCompilerStats<T>,
  ) => Promise<void>; // Check function for the test case
}

/** @type {import('@rspack/core').TCompilerCaseConfig} */
module.exports = {
  // ...
};

#Defaults

This test does not execute real builds; it only generates build configurations and observes the differences from the default configuration. The basic default configuration will be snapshot and stored in tests/rspack-test/__snapshots__/Defaults.test.js.snap.

This test uses tests/rspack-test/fixtures as the source code for the build, so the test case is written as a single file. Its structure is as follows:

interface TDefaultsCaseConfig {
  description: string; // Description of the test case
  cwd?: string; // process.cwd for generating the build configuration of the test case, default is the `tests/rspack-test` directory
  options?: (context: ITestContext) => TCompilerOptions<ECompilerType.Rspack>; // Test case build configuration
  diff: (
    diff: Assertion<Diff>,
    defaults: Assertion<TCompilerOptions<ECompilerType.Rspack>>,
  ) => Promise<void>; // Differences from the default configuration
}

/** @type {import('../..').TDefaultsCaseConfig} */
module.exports = {
  // ...
};

The details for the Error test are as follows:

#Error

This test uses tests/rspack-test/fixtures as the source code for the build, so the test case is written as a single file. Its structure is as follows:

interface TErrorCaseConfig {
  description: string; // Description of the test case
  options?: (
    options: TCompilerOptions<T>,
    context: ITestContext,
  ) => TCompilerOptions<T>; // Test case configuration
  build?: (context: ITestContext, compiler: TCompiler<T>) => Promise<void>; // Test case build method
  check?: (stats: TStatsDiagnostics) => Promise<void>; // Function to check the test case
}

/** @type {import('../..').TErrorCaseConfig} */
module.exports = {
  // ...
};

#Hook

This test records the input and output of the hook and stores it in the snapshot hooks.snap.txt. The snapshot of the final product code is stored in output.snap.txt.

This test uses tests/rspack-test/fixtures as the source code for the build, so the test case is written as a single file. Its structure is as follows:

interface THookCaseConfig {
  description: string; // Description of the test case
  options?: (
    options: TCompilerOptions<T>,
    context: ITestContext,
  ) => TCompilerOptions<T>; // Test case configuration
  compiler?: (context: ITestContext, compiler: TCompiler<T>) => Promise<void>; // Callback after creating the compiler instance
  check?: (context: ITestContext) => Promise<void>; // Callback after the build is completed
}

/** @type {import("@rspack/test-tools").THookCaseConfig} */
module.exports = {
  // ...
};

#TreeShaking

In this test case, the configuration is similar to a regular rspack project. You can specify the build configuration by adding a rspack.config.js, but the final product is snapshot and stored in __snapshots__/treeshaking.snap.txt.

#Builtin

This test case is similar to a regular rspack project, and you can specify the build configuration by adding a rspack.config.js. However, depending on the directory, different snapshots of the products will be generated and stored in __snapshots__/output.snap.txt:

• plugin-css: Snapshots of files with a .css extension
• plugin-css-modules: Snapshots of files with .css and .js extensions
• plugin-html: Snapshots of files with .html extension
• Other: Snapshots of files with .js extension