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

# globalSetup

- **类型：** `string | string[]`
- **默认值：** `undefined`

Rstest 中的 `globalSetup` 选项允许你运行 setup 和 teardown 代码，这些代码会在所有测试之前和完成后执行。这对于以下场景很有用：

- 启动和停止数据库
- 初始化测试服务
- 测试运行后清理资源

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

export default defineConfig({
  globalSetup: ['./global-setup.ts'],
  // 或多个文件
  globalSetup: ['./setup-db.ts', './setup-server.ts'],
  // 其他配置...
});
```

## 全局设置文件格式

你可以用两种格式编写全局设置文件：

### 命名函数（推荐）

```ts
// global-setup.ts

export async function setup() {
  console.log('正在设置测试环境...');

  // 初始化数据库、启动服务等
  // await startDatabase();
}

export async function teardown() {
  console.log('正在清理测试环境...');

  // 清理资源
  // await stopDatabase();
}
```

### 返回 teardown 函数的默认函数

```ts
// global-setup.ts
export default async function globalSetup() {
  console.log('正在设置测试环境...');

  // 初始化资源
  const database = await connectDatabase();
  const server = await startTestServer();

  // 返回 teardown 函数
  return async () => {
    console.log('正在清理资源...');
    await server.stop();
    await database.disconnect();
  };
}
```

:::note
globalSetup 文件在隔离的 setup worker 中运行：setup 文件里模块作用域的变量在测试中无法访问。其中产生的环境变量变更会存储在 Rstest context 上，并被组合到每个 node 测试 worker 的环境中，而不会修改宿主的 `process.env`——所以通过在此处修改环境变量把值传给 node 测试是被支持的用法。对于 browser 模式测试，**browser 项目自身**的 `globalSetup` 中所做的环境变量变更也会被传递：它们会被注入到 browser 运行时的 env 存储中（可通过 `process.env` / `import.meta.env` 读取），叠加在内置的 `NODE_ENV` / `RSTEST` 之上，且显式的 `test.env` 配置仍然优先。其他宿主环境变量不会被转发到 browser 测试；在混合项目中，Node 侧 `globalSetup` 的环境变量变更不会合并进 browser 测试。由 browser provider hook（`modifyRstestConfig`）新增或修改的 `globalSetup` 条目同样会被识别：这些 hook 会在测试发现阶段被应用，早于 setup 阶段读取项目配置。在 watch 模式下，每个 browser 项目的 `globalSetup` 会在初始测试周期前执行一次；后续 rerun 不会再次执行，watch session 关闭时会执行对应的 teardown。
:::

## 多个全局设置文件

当使用多个全局设置文件时：

- 设置函数按提供的顺序顺序执行
- teardown 函数按相反顺序执行（LIFO - 后进先出）
- 如果任何设置失败，整个测试运行都会失败

## 与 setupFiles 的区别

| 特性          | globalSetup     | setupFiles      |
| ----------- | --------------- | --------------- |
| 执行时机        | 在**所有测试**之前执行一次 | 在**每个测试文件**之前执行 |
| teardown 支持 | 支持              | 不支持             |
| 使用场景        | 全局资源、数据库、服务     | 每个测试的工具方法、mock  |

## 示例：数据库设置

```ts
// db-setup.ts
let dbConnection: any;

export async function setup() {
  const { MongoClient } = await import('mongodb');
  const client = new MongoClient(process.env.TEST_MONGODB_URI!);
  await client.connect();

  dbConnection = client.db('test');

  // 播种测试数据
  await dbConnection.collection('users').insertMany([
    { name: 'John', email: 'john@example.com' },
    { name: 'Jane', email: 'jane@example.com' },
  ]);

  console.log('✓ 数据库已连接并播种数据');
}

export async function teardown() {
  if (dbConnection) {
    await dbConnection.dropDatabase();
    await dbConnection.client.close();
    console.log('✓ 数据库已清理');
  }
}
```

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

export default defineConfig({
  globalSetup: ['./db-setup.ts'],
  include: ['**/*.test.ts'],
});
```