DOCSEARCHbyAlgolia
Submit Docs

Rstest Documentation

repository·main·Indexed 19 days ago

https://github.com/web-infra-dev/rstest

A high-performance JavaScript testing framework powered by Rspack, providing a Jest-compatible API with native support for TypeScript and ESM. It includes specialized adapters for Rsbuild, Rslib, and Rspack, as well as browser-based React testing utilities via @rstest/browser-react for rendering components and hooks.

Tokens
125.3K
Snippets
417
Records
515
Agent score
64%

What's inside Rstest

  1. Introduction to Rstest

    main

    Rstest is a JavaScript testing framework powered by Rspack. It provides Jest-compatible APIs while offering native support for modern web technologies like TypeScript, ESM, CJS, and CSS Modules.

    Unlike traditional testing frameworks that use a per-file transform-and-execute model, Rstest uses a dependency graph–based bundle model. This allows it to leverage build-time optimizations (like tree-shaking) and ensures that test behavior closely matches production output. It is designed to integrate seamlessly into existing Rspack-based projects or be adopted into non-Rspack projects without requiring a full build system migration.

  2. Overview of Rstest built-in reporters

    main

    Rstest provides several built-in reporters tailored for different environments and use cases:

    ReporterPurposeUse case
    defaultConsole output with colorsLocal development
    dotCompact per-test markersFast local feedback
    verboseDetailed test case outputDebugging test failures
    github-actionsCI error annotationsGitHub Actions workflows
    junitJUnit XML formatCI/CD integration
    jsonStructured JSON reportCI tooling and scripting
    mdMarkdown agent reportAgent / LLM integrations
    blobSerialized JSON outputMerging sharded reports

  3. Overview of Rstest

    main

    Rstest is a JavaScript testing framework powered by Rspack. It is designed to provide first-class support for the Rspack ecosystem, making it ideal for integration into Rspack-based projects.

    Key features include:

    • Jest Compatibility: Offers full Jest-compatible APIs.
    • Modern Defaults: Native, out-of-the-box support for TypeScript, ESM, and other modern web standards.
    • Comprehensive Scenarios: Supports Node.js testing, DOM testing, mocking, multi-project testing, and coverage collection.

  4. Use @rstest/browser-ui for browser mode testing

    main

    @rstest/browser-ui is a prebuilt browser container UI designed for Rstest's experimental browser mode testing. It provides the visual interface used to display test files, execution status, and results during test runs.

    Tech Stack:

    • React 19
    • Tailwind CSS v4
    • Ant Design v5
    • Lucide React
    • birpc (for RPC communication with the host)

  5. Explore the Rstest Runtime API

    main

    The Rstest Runtime API provides the core testing interfaces for your projects. The API is divided into two main categories:

    1. General Testing APIs: Used for standard assertions and test lifecycle management. For detailed documentation on these, refer to the Test API section.
    2. Browser Mode APIs: Specialized APIs designed for testing in a browser environment. For details on browser-specific testing, refer to the Browser Mode section.

  6. What is Browser Mode in Rstest?

    main

    Browser Mode allows you to execute tests in real browsers (Chromium, Firefox, or WebKit) using Playwright instead of simulated environments like jsdom or happy-dom. This ensures your tests run with the exact same browser APIs and behaviors as your production environment.

    Important Note on Error Handling: Like Node mode, Browser Mode will fail a test file if an unhandled error or promise rejection escapes it, even if all individual tests in that file pass. To prevent this, ensure you await promises or attach handlers to expected rejections within your tests so they do not leak to the page.

  7. Integrate existing configurations with Rstest

    main

    For large projects, you can use the extends option or adapters to integrate existing build/toolchain configurations (like aliases, global variables, or plugins) into your Rstest setup.

    Using extends, you can load a function (adapter) or an object. The returned configuration is then deeply merged with the current Rstest configuration, ensuring consistency between your main build and your test environment.

  8. Configure Rsbuild in Rstest

    main

    Rstest's build configuration inherits from Rsbuild. You can use most Rsbuild configurations directly within Rstest, including:

    • Plugins: Using Rsbuild plugins.
    • Module Resolution: Configuring resolve behavior.
    • Rspack Configuration: Using tools.rspack.
    • SWC Configuration: Configuring tools.swc (the builtin:swc-loader).

    Additionally, Rstest provides APIs for Rsbuild plugins to read or modify the resolved Rstest configuration.

  9. How Locators work in Browser Mode

    main

    A Locator is the core API for querying and interacting with elements. The typical workflow involves using the page object (a BrowserPage) to create a Locator via query methods, and then calling interaction methods (like click or fill) on that Locator.

    Key Concepts:

    • page (BrowserPage): A query-only starting point. It only creates Locator instances and does not execute actions directly.
    • Locator: The object that holds the query logic and provides interaction methods (e.g., .click()).
    • Auto-waiting: When using the Playwright provider, interaction methods automatically wait for elements to become actionable (visible, enabled, stable) before executing.
    • Strictness: Locators are strict. If an interaction resolves to more than one element, the operation will throw an error. To handle multiple matches, use .first(), .last(), or .nth(index) to select a specific element.
    import { page } from '@rstest/browser';
import { expect, test } from '@rstest/core';

test('interacts with a form using locator', async () => {
  await page.getByLabel('Username').fill('alice');
  await page.getByLabel('Password').fill('secret123');
  await page.getByRole('button', { name: 'Login' }).click();

  await expect.element(page.getByLabel('Username')).toHaveValue('alice');
});

  10. Compare @rstest/playwright vs native Playwright

    main

    Choose @rstest/playwright if you want Playwright-driven E2E tests to run within your existing Rstest workflow. Choose native Playwright if you require the full Playwright Test runner workflow and its specific configuration model.

    Feature@rstest/playwrightNative Playwright
    RunnerRstest runnerPlaywright Test runner
    Configurationrstest.config.ts + fixture overridesplaywright.config.ts
    Test APIimport { test, expect } from '@rstest/playwright'import { test, expect } from '@playwright/test'

  11. Understand Global vs Project configuration

    main

    Rstest distinguishes between Global configuration (set in the root rstest.config.ts) and Project configuration (set within individual projects).

    Global Configuration

    These settings apply to the entire Rstest process and cannot be configured inside a project. If you need to change these for a specific project, you must use CLI options.

    • reporters
    • pool
    • isolate
    • coverage
    • bail
    • output.distPath.root

    Project Configuration

    Project configurations are a subset of the Rstest configuration object. They do not inherit from the root configuration; only the root's projects field and global settings are effective. To share configuration between projects, use mergeRstestConfig from @rstest/core.

    import { defineConfig, mergeRstestConfig } from '@rstest/core';
import sharedConfig from '../shared/rstest.config';

export default mergeRstestConfig(sharedConfig, {
  name: 'pkg-a',
});

  12. Run multi-project test suites

    main
    Rstest supports running multiple test projects within a single process. Each project maintains its own independent configuration and environment. This is ideal for monorepos or workspaces where different applications require different test targets (e.g., one project targeting Node.js and another targeting the DOM or Browser Mode).