# @happyvertical/smrt-vitest 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-vitest/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:55:40.199Z
中文译文更新时间：2026-11-17T09:58:58.732Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/smrt-vitest
原文对照：https://npmcn.com/package/%40happyvertical/smrt-vitest/?lang=original
项目主页：https://github.com/happyvertical/smrt#readme
源码仓库：https://github.com/happyvertical/smrt

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：828 kB，68 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- peer 依赖：svelte \>=5\.57\.0，vitest \>=2\.1\.9
- 首次发布：2026-06-23T01:18:56.181Z
- 最新版本发布：2026-11-17T07:55:40.016Z
- 近 30 天下载量：15759（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：365（近 12 个月 365 个）

## 中文简介

在 SMRT 测试中自动装入跨包装表的虚拟插件

## 安装

```sh
npm install @happyvertical/smrt-vitest
```

也可以使用：`pnpm add @happyvertical/smrt-vitest`、`yarn add @happyvertical/smrt-vitest`、`bun add @happyvertical/smrt-vitest`

## README

# @happy垂直/ smrt-vitest

S-m-r-t 项目的虚拟插件 - **所需经费** 所有s -m -r 自动生成物列表,加载跨包类元数据,并提供交易同位化测试数据库的公用功能.

## 安装

```bash
pnpm add -D @happyvertical/smrt-vitest
```

## 使用量

### 需要的插件设置

每个 s -m `smrtVitestPlugin()` 在vitest.config.ts中:

```typescript
import { defineConfig } from 'vitest/config';
import { smrtVitestPlugin } from '@happyvertical/smrt-vitest';

export default defineConfig({
  plugins: [smrtVitestPlugin()],
});
```

没有此插件, 测试失败 `"No field metadata found"` 或者说 `"unregistered class"` 错误.

### 插件选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `generateManifest` | `boolean` | `true` | 启动时自动生成显示 |
| `include` | `string[]` | `['src/**/*.ts']` | 要扫描的源模式 |
| `exclude` | `string[]` | `['**/*.d.ts', ...]` | 排除的模式 |
| `packages` | `string[]` | `[]` | 超出自动发现范围的其他软件包 |
| `verbose` | `boolean` | `false` | 按包装发放的登记清单。 继续 `SMRT_VERBOSE=true` 或者说 `DEBUG` 包含 `smrt`,无论这个选项。 每个过程的一行摘要`Loaded manifests from N/M packages`总是记录一次 即使这是 `false`。 。 。 . |
| `root` | `string` | `process.cwd()` | 根目录 |
| `setupFile` | `string` | 软件包设置条目 | 覆盖注入 Vitest 项目的设置文件 |
| `aliasFilter` | `(entry) => boolean` | 保留全部 | 丢弃自动生成的工作空间别名条目( 接收原始字符串) `find` 财务报告和审定财务报表 `replacement`(中文(简体) ) |

### 活性8(滚动/氧化)

Vite 8用倒数/oxc取代了ebuild,它改变了三种行为 中断 s -m -r 插件将所有三个如此消耗的应用程序都正常化 需要每回转工作( 证据: 任意town.ai# 707, willgriffin.dev# 220) :

1.  **`esbuild.tsconfigRaw` 被忽略** 遗产 `@smrt()` 到达装饰器 未转换的捆绑。 插件注入 `oxc.decorator = { legacy: true, emitDecoratorMetadata: true }` (加上 匹配 `oxc.tsconfig.compilerOptions` 镜子).
    
2.  **默认导入oxc elides 类型定位副作用** ——测试文件 通常坐在tsconfig外边 `include`,所以一个回波范围 `verbatimModuleSyntax` 永远无法到达它们 以及副作用模型导入 (s-m-r-t 对象注册)默不作声. 插件注入 `oxc.typescript = { onlyRemoveTypeImports: true }`。 。 。 .
    
3.  **滚动前缀匹配字符串的别名 `find`编号** 赤裸的工作空间别名 喜欢 `@org/pkg` → `src/index.ts` mangles 无异名子路径导入 (单位:千美元)`@org/pkg/sub` → `src/index.ts/sub`) (中文(简体) ). 工作空间别名作为 锁定精确匹配的 RegExps, 因此未变形的子路径会掉入 软件包导出地图; 使用 `aliasFilter` 完全删除条目.
    
    > **直接突破变化 `getWorkspaceViteAliases()` 消费者:** 每个条目 `find` 现在是一个固定 `RegExp`,而不是一个 `string` (单位:千美元) 返回的数组仍为命令最具体的第一个, 新的第二个 `options` 参数是可选的). 使用的代码 `find` 作为一个字符串—— 例如,a `Map` 键或平等过滤器——应该与 `entry.find.test('<specifier>')` 换句话说 过滤器通过 `aliasFilter` (或帮助者) `options.filter`不受影响: 收到原始字符串 `find` 在锁定之前。 仅限插件消费者 无需更改.
    

所有默认值都是可被推翻的:任何 `oxc` 在您自己的配置中设置的字段 从未注入(显性消费者价值总是取胜,兄弟字段仍然 - 深入,和 `oxc: false` 完全抑制了注射。 这个 `oxc` 密钥 以建筑为主的7.

注意: 插件仅达到包含它的配置( vitest configs and any) 包含它的 vite 配置 `plugins`) (中文(简体) ). 应用程序的单独构建 `vite.config.ts` 没有插件仍然需要自己的 `oxc.decorator` 在 vite 8 上设置.

### 监视模式注释

清单在vitest启动时生成一次。 添加新内容后重新启动vitest `@smrt()` 类别或字段.

### 测试性能快照

测试启动扫描包含测试的源( 内置) `*.test.ts` 固定类 需要显示元数据),并将结果写入每个运行的快照, `.smrt/test-runs/<run>/manifest.json`从不 `.smrt/manifest.json`, (中文(简体) ), `dist/manifest.json`,或他们的配对 `smrt-knowledge.json` (# 4128) (中文(简体) ). 这些 属于生产建筑,所以在测试的同时进行建筑或打字检查 套房既不能取代套房的明细表,也不能被取而代之. 每个 运行中显示的——工人登记,运行时间显示 装填器, `createIsolatedTestDbFromManifest()` ——先解决快照; 检查生成的元数据的测试已读 `getTestManifestPath()`编辑 当运行退出时, 快取目录被删除, 而目录由 结束的运行在下次启动时被刷新 .

### 池与隔离

在333个文件、3 259个测试单元套房、16个核心(# 2897,# 2893的后续):

| 模式 | 墙 | CPU 软件 | 结果 |
| --- | --- | --- | --- |
| `pool: 'forks'`,孤立(默认) | 第22.9条 | 274 s (中文(简体) ) | 全部通过 |
| `pool: 'threads'`,隔离 | 第19.4节 | 234 s (中文(简体) ) | 全部通过 |
| `pool: 'forks'`, (中文(简体) ), `isolate: false` | 12.1 会 议 | 93会 | 1 个文件中的 7 个失败( 从另一个文件中取出模块模拟) |

-   **`pool: 'threads'` 获得支持** 并且在这个套房里价格低了15% 试试看 工程 - 本地驱动程序可以在线条下对分叉行为不同.
-   **`isolate: false` 获得支持** 由此插件自己的设置: 注册守护 内 `src/setup.ts` 由设计自愈(在 `ObjectRegistry.clear()`,这就是那个警卫存在的原因 -- -- #2750. 转向隔离 关闭是一个消费者的决定,虽然: 它去除泄漏的守卫 _介于_ 测试文件,所以 它下面的失败文件表示真正的跨文件泄漏来修正,而不是插件错误. 仅推荐单位项目,绝不推荐整合项目.
-   这个插件支付的每个文件固定成本是进程 + 模块图拖曳 (每个文件大约为CPU的半秒),未显示注册本身 (50-90 ms) (英语). 预先进行登记不会从固定费用中节省多少;见 2893号的测量数据 懒惰装入 `@happyvertical/ai` 在核心(一个单独的, 对消费者而言,使用ai 软件包的杠杆更大 他们的依赖图.

## API 密码

### 最小行合同

每一个声明模型的软件包都保持这个生成的测试 `src/__tests__/minimal-row.generated.test.ts`数字 :

```typescript
import { registerMinimalRowTests } from '@happyvertical/smrt-vitest/minimal-row';

await registerMinimalRowTests();
```

共享测试从活性测试表中加载出真实的模型和集合. ObjectRegistry提供模型列表. 每个模型都有自己的SQLite数据库 和创建/保存/获得/列出往返。 首先要创建必要的父母. 可选输入保持空或默认值 。 无法识别模式 和可选的字段,当错误或单场探测器能够识别它时. 框架基础、抽象模型、测试固定装置和收集类报告 他们的跳伞原因。 已知的发现仍停留在按模式分列的共用收缩分类账中, 字段,稳定的出错摘录和类型:可选字段,只服务字段或 需要域值。 仅服务测试表明,自有服务完全直接 写入拒绝; 域- 值项描述值/ 文本元数据不能 供应。 更改错误失败 。 列表模式通过失败 指示删除其条目.

同样的子路径输出 `buildMinimalRow(modelName, { db })` 服务种子 数据。 它只返回需要的输入, 并保存所需的家长 `db`。 。 。 . 需要的租户地被填满;模式上的可选租户地被填满 测试被省略。 法定父母继承同一房客,包括可选择的 被监视的父母。 重复的命名关系重复使用相同的祖先身份; 不同的角色保留了不同的行. 这个 `TESTING_STANDARD.md` 释放门 要求每个被触摸的包的服务 一次运行在这些最小行, 包括每个服务模式的指定所有人.

此子路径导入 Vitest 并属于测试代码 。 主软件包条目 不导入 Vitest 全球 .

### 插件

| 导出 | 说明 |
| --- | --- |
| `smrtVitestPlugin(options?)` | Vite 插件 - 生成表和装入跨包类 |
| `setupSmrtManifests(options?)` | 非 Vite 设置( 如 GlobalSetup 文件) 的强制选项 |

### 测试数据库工具

| 导出 | 说明 |
| --- | --- |
| `createIsolatedTestDbFromManifest(options?)` | 从本地 + 明确请求的注册依赖性列表对象创建 DB, FK 命令和STI 解调( 建议) |
| `createIsolatedTestDb(options?)` | 创建带有原始 DDL 计划和交易隔离的 DB |
| `createTestDb(prefix?)` | 创建带有清理功能的 DB( 无交易隔离) |
| `getTestDbConfig(prefix?)` | 为当前环境获取 DB 配置 |
| `getInMemoryDbConfig()` | 获取模拟 SQLite 配置 |
| `getTestAdapter()` | 检测适配器 : `'postgres'` 或者说 `'sqlite'` |
| `getAdapterDisplayName()` | 测试标签的可读适配器名称 |
| `isPostgresAvailable()` | 检查是否 `DATABASE_URL` 设定 |

DB 适配器自动检测 : `DATABASE_URL` 设置 - > PostgreSQL; 否则 - > SQLite 临时文件.

### 交易隔离示例

```typescript
import { createIsolatedTestDb } from '@happyvertical/smrt-vitest';

let db, cleanup;

beforeEach(async () => {
  ({ db, cleanup } = await createIsolatedTestDb({
    schema: `CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT NOT NULL)`
  }));
});

afterEach(async () => {
  await cleanup(); // Rolls back transaction
});

it('should insert and query', async () => {
  await db.insert('users', { id: '1', name: 'Alice' });
  const user = await db.get('users', { id: '1' });
  expect(user?.name).toBe('Alice');
});
```

### 类型

`IsolatedTestDbOptions`, (中文(简体) ), `IsolatedTestDbResult`, (中文(简体) ), `ManifestTestDbOptions`, (中文(简体) ), `TestDbAdapter`, (中文(简体) ), `TestDbConfig`, (中文(简体) ), `TransactionHandle`

## 依赖关系

-   `@happyvertical/smrt-core` - 显示器、对象登记册
-   `@happyvertical/sql` -- 数据库连接和交易
-   `vitest` (同行) -- 虚拟测试框架

## 许可证

麻省理工学院

## 常见问题

### @happyvertical/smrt-vitest 是什么？

在 SMRT 测试中自动装入跨包装表的虚拟插件

### 如何安装 @happyvertical/smrt-vitest？

在项目目录运行 npm install @happyvertical/smrt-vitest，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vitest（\>=2\.1\.9）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @happyvertical/smrt-vitest 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @happyvertical/smrt-vitest 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @happyvertical/smrt-vitest 可以商用吗？

@happyvertical/smrt-vitest 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @happyvertical/smrt-vitest 的下载量有多少？

根据 npm 官方下载统计，@happyvertical/smrt-vitest 在 2026/10/17 – 2026/11/15 这 30 天内被下载 15,759 次，日均约 525 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @happyvertical/smrt-vitest 还在维护吗？

最新版本 0\.62\.1 发布于 2026/11/17（今天）；至今共发布 365 个版本，其中过去 12 个月发布了 365 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

