close
Rstest
  • 简体中文

      • browser（实验性）

      • 类型：
      type BrowserModeConfig = {
  enabled?: boolean;
  provider: 'playwright';
  browser?: 'chromium' | 'firefox' | 'webkit';
  headless?: boolean;
  port?: number;
  strictPort?: boolean;
  providerOptions?: Record<string, unknown>;
};
      • 默认值：
      const defaultBrowser = {
  enabled: false,
  provider: 'playwright',
  browser: 'chromium',
  headless: true, // CI 环境；本地开发为 false
  port: undefined, // 随机可用端口
  strictPort: false,
  providerOptions: {},
};

      浏览器模式配置。启用后，测试将在真实浏览器中运行，而非 Node.js 环境。

      选项

      enabled

      • 类型： boolean
      • 默认值： false
      • CLI： --browser、--browser.enabled

      启用浏览器模式。

      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
  },
});
      Tip

      启用浏览器模式需要安装 @rstest/browser 包和 Playwright 浏览器。

      npm add @rstest/browser -D
npx playwright install chromium

      provider

      • 类型： 'playwright'
      • 默认值： 'playwright'

      浏览器驱动提供者。目前仅支持 Playwright。

      同一次测试运行（single run）暂不支持混用多个 provider。

      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
  },
});

      browser

      • 类型： 'chromium' | 'firefox' | 'webkit'
      • 默认值： 'chromium'
      • CLI： --browser.name <name>

      用于测试的浏览器类型。

      • chromium - Google Chrome、Microsoft Edge
      • firefox - Mozilla Firefox
      • webkit - Safari
      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
    browser: 'firefox',
  },
});

      使用前需要安装对应的浏览器：

      # 安装 Chromium
npx playwright install chromium

# 安装 Firefox
npx playwright install firefox

# 安装 WebKit
npx playwright install webkit

# 安装所有浏览器
npx playwright install

      headless

      • 类型： boolean
      • 默认值： CI 环境为 true，本地开发为 false
      • CLI： --browser.headless

      是否以无界面模式运行浏览器。

      rstest.config.ts
      CI (GitHub Actions)
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
    headless: true,
  },
});

      在本地开发时，设置 headless: false 可以看到浏览器窗口，便于调试。

      根据环境动态配置

      如果你希望本地调试时使用 headed 模式，CI 中使用 headless，可以通过环境变量控制：

      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
    headless: process.env.CI === 'true',
  },
});

      port

      • 类型： number
      • 默认值： undefined（自动选择可用端口）
      • CLI： --browser.port <port>

      浏览器模式 Dev Server 的端口号。

      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
    port: 5173,
  },
});

      如果指定了 port 且端口已被占用，是否报错由 strictPort 控制：当 strictPort: true 时会报错退出；当 strictPort: false 时会尝试使用其他可用端口。如果未指定 port，则始终会自动选择一个可用端口。

      strictPort

      • 类型： boolean
      • 默认值： false
      • CLI： --browser.strictPort

      当指定 port 时，是否要求端口必须可用：

      • true：如果端口被占用则直接报错退出
      • false：如果端口被占用则自动回退到其他可用端口
      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
    port: 5173,
    strictPort: true,
  },
});

      providerOptions

      Added in v0.9.3
      • 类型： Record<string, unknown>
      • 默认值： {}

      传递给选定 browser provider 的特定选项。Rstest 不会验证或解析该对象的内容——它会在浏览器启动和 context 创建时原样转发给 provider。

      providerOptions 的结构由各 provider 自行定义。详见下方 Provider 选项。

      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
    providerOptions: {
      launch: {
        timeout: 60_000,
      },
    },
  },
});

      当前限制：同一次 run 的 browser 启动配置必须一致

      在一个 rstest 进程内，所有启用 Browser Mode 的项目需要共享同一组 browser 启动配置：

      • provider
      • browser
      • headless
      • port
      • strictPort
      • providerOptions

      这意味着目前还不支持在同一次 run 里通过 projects 混用多个 provider，或同时配置 Chromium/Firefox/WebKit。

      如果你需要跨浏览器覆盖，建议拆成多次执行（例如在 CI matrix 中分别跑）：

      npx rstest --browser.name chromium
npx rstest --browser.name firefox
npx rstest --browser.name webkit

      多项目配置隔离

      在 Browser Mode 下使用 projects 时，每个项目会按自己的构建配置独立编译和执行（如 plugins、include、框架设置），不会复用其他项目的构建配置。

      但 browser 启动配置仍需保持一致：provider、browser、headless、port、strictPort、providerOptions 必须在所有 browser 项目中对齐。

      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  projects: ['./project-b/rstest.config.ts', './project-a/rstest.config.ts'],
});
      project-a/rstest.config.ts
      import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rstest/core';

export default defineConfig({
  name: 'project-a',
  plugins: [pluginReact()],
  include: ['tests/**/*.test.tsx'],
  browser: {
    enabled: true,
    provider: 'playwright',
  },
});

      与 Node 测试混合

      可以同时配置浏览器测试和 Node.js 测试：

      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  projects: [
    {
      name: 'browser',
      include: ['src/**/*.browser.test.ts'],
      browser: {
        enabled: true,
        provider: 'playwright',
      },
    },
    {
      name: 'node',
      include: ['src/**/*.node.test.ts'],
      testEnvironment: 'node',
    },
    {
      name: 'jsdom',
      include: ['src/**/*.test.ts'],
      exclude: ['src/**/*.browser.test.ts', 'src/**/*.node.test.ts'],
      testEnvironment: 'jsdom',
    },
  ],
});

      Provider 选项

      Playwright

      使用 provider: 'playwright' 时，Playwright provider 识别 providerOptions 中的以下字段：

      1. launch — 传递给 Playwright browserType.launch()，控制浏览器进程的启动方式。
      2. context — 传递给 Playwright browser.newContext()，控制每个测试文件创建的 browser context。

      由于 providerOptions 的类型是 Record<string, unknown>，默认不会提供 IntelliSense。如需类型检查和自动补全，可以直接从 playwright 包导入类型，并配合 TypeScript 的 satisfies 运算符使用：

      rstest.config.ts
      import type { LaunchOptions, BrowserContextOptions } from 'playwright';
import { defineConfig } from '@rstest/core';

type PlaywrightProviderOptions = {
  launch?: LaunchOptions;
  context?: BrowserContextOptions;
};

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
    providerOptions: {
      launch: {
        timeout: 60_000,
      },
      context: {
        locale: 'en-US',
        colorScheme: 'dark',
      },
    } satisfies PlaywrightProviderOptions,
  },
});

      相关链接