browser（实验性）

类型：

type BrowserViewport =
  | {
      width: number;
      height: number;
    }
  | DevicePreset;

type DevicePreset =
  | 'iPhoneSE'
  | 'iPhoneXR'
  | 'iPhone12Pro'
  | 'iPhone14ProMax'
  | 'Pixel7'
  | 'SamsungGalaxyS8Plus'
  | 'SamsungGalaxyS20Ultra'
  | 'iPadMini'
  | 'iPadAir'
  | 'iPadPro'
  | 'SurfacePro7'
  | 'SurfaceDuo'
  | 'GalaxyZFold5'
  | 'AsusZenbookFold'
  | 'SamsungGalaxyA51A71'
  | 'NestHub'
  | 'NestHubMax';

type BrowserModeConfig = {
  enabled?: boolean;
  provider: 'playwright';
  browser?: 'chromium' | 'firefox' | 'webkit';
  headless?: boolean;
  port?: number;
  viewport?: BrowserViewport;
  strictPort?: boolean;
  providerOptions?: Record<string, unknown>;
};

默认值：

const defaultBrowser = {
  enabled: false,
  provider: 'playwright',
  browser: 'chromium',
  headless: true, // CI 环境；本地开发为 false
  port: undefined, // 随机可用端口
  viewport: undefined, // Browser UI 填满预览面板
  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,
  },
});

# .github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install
      - run: npx playwright install chromium
      - run: npm test

在本地开发时，设置 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',
  },
});

viewport

Added in v0.8.4

类型： BrowserViewport
默认值： undefined

设置 Browser Mode 测试的默认 runner iframe viewport。如果未指定，Browser UI 会填满预览面板。

type BrowserViewport =
  | {
      width: number;
      height: number;
    }
  | DevicePreset;

如果你希望一个 browser 项目中的所有文件都使用同一个 viewport，可以显式指定尺寸：

rstest.config.ts

import { defineConfig } from '@rstest/core';

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
    viewport: { width: 390, height: 844 },
  },
});

你也可以使用内置设备 preset：

rstest.config.ts

import { defineConfig } from '@rstest/core';

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

支持的 preset：

Preset	尺寸
`iPhoneSE`	375 x 667
`iPhoneXR`	414 x 896
`iPhone12Pro`	390 x 844
`iPhone14ProMax`	430 x 932
`Pixel7`	412 x 915
`SamsungGalaxyS8Plus`	360 x 740
`SamsungGalaxyS20Ultra`	412 x 915
`iPadMini`	768 x 1024
`iPadAir`	820 x 1180
`iPadPro`	1024 x 1366
`SurfacePro7`	912 x 1368
`SurfaceDuo`	540 x 720
`GalaxyZFold5`	344 x 882
`AsusZenbookFold`	853 x 1280
`SamsungGalaxyA51A71`	412 x 914
`NestHub`	1024 x 600
`NestHubMax`	1280 x 800

Tip

browser.viewport 控制测试 runner iframe 的 viewport。如果你需要 Playwright context 选项，例如 locale、color scheme 或 permissions，请通过 providerOptions.context 配置。

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>
默认值： {}
CLI： --browser.providerOptions.*

传递给选定 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,
      },
    },
  },
});

也可以通过 CLI 传入嵌套的 provider 选项：

npx rstest --browser.providerOptions.launch.channel=chrome

当前限制：同一次 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 中的以下字段：

launch — 传递给 Playwright browserType.launch()，控制浏览器进程的启动方式。
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,
  },
});

#browser（实验性）

#选项

#enabled

#provider

#browser

#headless

#viewport

#port

#strictPort

#providerOptions

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

#多项目配置隔离

#与 Node 测试混合

#Provider 选项

#Playwright

#相关链接

browser（实验性）

选项

enabled

provider

browser

headless

viewport

port

strictPort

providerOptions

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

多项目配置隔离

与 Node 测试混合

Provider 选项

Playwright

相关链接