> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# browser（实验性）

- **类型：**

```ts
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>;
};
```

- **默认值：**

```ts
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`

启用浏览器模式。

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';

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

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

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

:::

### provider

- **类型：** `'playwright'`
- **默认值：** `'playwright'`

浏览器驱动提供者。目前仅支持 [Playwright](https://playwright.dev/)。

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

```ts title="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

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';

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

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

```bash
# 安装 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**

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

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


**CI (GitHub Actions)**

```yaml
# .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` 可以看到浏览器窗口，便于调试。

:::tip 根据环境动态配置
如果你希望本地调试时使用 headed 模式，CI 中使用 headless，可以通过环境变量控制：

```ts title="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](https://github.com/web-infra-dev/rstest/releases/tag/v0.8.4)

- **类型：** `BrowserViewport`
- **默认值：** `undefined`

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

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

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

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';

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

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

```ts title="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`](#provider-选项) 配置。
:::

### port

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

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

```ts title="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`：如果端口被占用则自动回退到其他可用端口

```ts title="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](https://github.com/web-infra-dev/rstest/releases/tag/v0.9.3)

- **类型：** `Record<string, unknown>`
- **默认值：** `{}`
- **CLI：** `--browser.providerOptions.*`

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

`providerOptions` 的结构由各 provider 自行定义。详见下方 [Provider 选项](#provider-选项)。

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';

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

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

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

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

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

- `provider`
- `browser`
- `headless`
- `providerOptions`

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

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

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

## 多项目配置隔离

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

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

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';

export default defineConfig({
  projects: ['./project-b/rstest.config.ts', './project-a/rstest.config.ts'],
});
```

```ts title="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 测试：

```ts title="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()`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch)，控制浏览器进程的启动方式。
2. **`context`** — 传递给 Playwright [`browser.newContext()`](https://playwright.dev/docs/api/class-browser#browser-new-context)，控制每个测试文件创建的 browser context。

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

```ts title="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,
  },
});
```

## 相关链接

- [浏览器模式指南](/zh/guide/browser-testing/index.md) - 浏览器模式介绍和使用指南
- [快速开始](/zh/guide/browser-testing/getting-started.md) - 配置浏览器模式测试
- [浏览器交互](/zh/guide/browser-testing/user-interactions.md#locator-api) - 使用 `page` + `expect.element` 编写语义化测试