vitest-runner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vitest Test Runner Skill

Vitest测试运行器Skill

Operator Context

操作器上下文

This skill operates as an operator for Vitest test execution, configuring Claude's behavior for running tests and parsing results into actionable reports.

本Skill作为Vitest测试执行的操作器，配置Claude的行为以运行测试并将结果解析为可执行的报告。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终适用）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before running tests
Over-Engineering Prevention: Only run tests; do not auto-fix failures unless explicitly requested
Complete Output: Show full test output including all failures, never summarize away details
Non-Interactive Execution: Always use
```
npx vitest run
```
(not bare
```
npx vitest
```
which starts watch mode)
Exit Code Respect: Accurately report pass/fail status based on process exit code

CLAUDE.md合规性：运行测试前阅读并遵循仓库中的CLAUDE.md
避免过度设计：仅运行测试；除非明确要求，否则不要自动修复失败
完整输出：显示包括所有失败在内的完整测试输出，绝不省略细节
非交互式执行：始终使用
```
npx vitest run
```
（而非不带
```
run
```
的
```
npx vitest
```
，后者会启动监听模式）
尊重退出码：根据进程退出码准确报告测试通过/失败状态

Default Behaviors (ON unless disabled)

默认行为（启用状态，除非禁用）

Parse Failures: Extract and format failing test names, errors, and stack traces
File Grouping: Organize results by test file
Duration Reporting: Show test execution times
Verbose Reporter: Use
```
--reporter=verbose
```
for detailed output

解析失败信息：提取并格式化失败测试的名称、错误和堆栈跟踪
按文件分组：按测试文件组织结果
执行时长报告：显示测试执行时间
详细报告器：使用
```
--reporter=verbose
```
获取详细输出

Optional Behaviors (OFF unless enabled)

可选行为（禁用状态，除非启用）

Coverage Mode: Run with
```
--coverage
```
flag when user requests coverage
Filter Tests: Run specific test files or name patterns via
```
--grep
```
Snapshot Update: Run with
```
--update
```
when user requests snapshot updates

覆盖率模式：当用户请求覆盖率时，使用
```
--coverage
```
标志运行
过滤测试：通过
```
--grep
```
运行特定测试文件或名称模式的测试
更新快照：当用户请求更新快照时，使用
```
--update
```
运行

What This Skill CAN Do

本Skill可实现的功能

Run Vitest tests on any Vitest-configured project
Parse test results into structured, actionable failure reports
Filter tests by file path, describe block, or test name pattern
Run tests with coverage reporting
Report flaky tests when results are inconsistent

在任何已配置Vitest的项目中运行Vitest测试
将测试结果解析为结构化、可执行的失败报告
按文件路径、describe块或测试名称模式过滤测试
运行带覆盖率报告的测试
当结果不一致时报告不稳定测试

What This Skill CANNOT Do

本Skill无法实现的功能

Auto-fix tests or modify test code to make tests pass
Install dependencies (will not run npm install)
Create or modify vitest.config.ts
Run non-Vitest test frameworks (Jest, Mocha, Playwright)

自动修复测试或修改测试代码以使其通过
安装依赖（不会运行npm install）
创建或修改vitest.config.ts
运行非Vitest的测试框架（Jest、Mocha、Playwright）

Instructions

使用说明

Step 1: Verify Vitest Project

步骤1：验证Vitest项目

Confirm vitest is available before running:

bash

undefined

运行前确认Vitest可用：

bash

undefined

Check for vitest configuration

检查Vitest配置

ls vitest.config.* vite.config.* 2>/dev/null grep -q "vitest" package.json && echo "vitest found in package.json"


If no vitest configuration found, stop and inform the user.

ls vitest.config.* vite.config.* 2>/dev/null grep -q "vitest" package.json && echo "vitest found in package.json"


如果未找到Vitest配置，请停止操作并告知用户。

Step 2: Run Tests

步骤2：运行测试

Execute Vitest in run mode (non-watch):

bash

npx vitest run --reporter=verbose 2>&1

For specific files or patterns:

bash

npx vitest run path/to/test.ts 2>&1
npx vitest run --grep "pattern" 2>&1

For coverage:

bash

npx vitest run --coverage 2>&1

以非监听模式执行Vitest：

bash

npx vitest run --reporter=verbose 2>&1

针对特定文件或模式：

bash

npx vitest run path/to/test.ts 2>&1
npx vitest run --grep "pattern" 2>&1

生成覆盖率报告：

bash

npx vitest run --coverage 2>&1

Step 3: Parse Output

步骤3：解析输出

For each test result, extract:

Test file: Path to the test file
Test name: Full test path (describe > it)
Status: PASS / FAIL / SKIP
Duration: Time taken
Error: Assertion error and stack trace for failures

针对每个测试结果，提取以下信息：

测试文件：测试文件的路径
测试名称：完整测试路径（describe > it）
状态：PASS / FAIL / SKIP
时长：执行时间
错误：失败断言的错误信息和堆栈跟踪

Step 4: Present Results

步骤4：展示结果

Format output as structured report:

=== Vitest Test Results ===

Status: PASS / FAIL (X passed, Y failed, Z skipped)

Failures:
---------
FAIL src/utils/__tests__/helpers.test.ts > parseData > handles null input
  AssertionError: expected null to equal { data: [] }
  - Expected: { data: [] }
  + Received: null
  at src/utils/__tests__/helpers.test.ts:25:10

Summary:
--------
Test Files: 12 passed, 2 failed (14 total)
Tests:      45 passed, 3 failed, 2 skipped (50 total)
Duration:   4.23s

将输出格式化为结构化报告：

=== Vitest测试结果 ===

状态：PASS / FAIL（X个通过，Y个失败，Z个跳过）

失败详情：
---------
FAIL src/utils/__tests__/helpers.test.ts > parseData > 处理null输入
  AssertionError: expected null to equal { data: [] }
  - Expected: { data: [] }
  + Received: null
  at src/utils/__tests__/helpers.test.ts:25:10

摘要：
---------
测试文件：12个通过，2个失败（共14个）
测试用例：45个通过，3个失败，2个跳过（共50个）
时长：4.23s

Error Handling

错误处理

Error: "Cannot find vitest"

错误："Cannot find vitest"

Cause: Vitest not installed or node_modules missing Solution: Check

grep vitest package.json

for presence, then advise user to run

npm install

npm install -D vitest

原因：Vitest未安装或node_modules缺失解决方案：检查

grep vitest package.json

确认是否存在，然后建议用户运行

npm install

或

npm install -D vitest

Error: "No test files found"

错误："No test files found"

Cause: Test file patterns don't match vitest.config include/exclude globs Solution: Verify test files exist with correct naming (*.test.ts, *.spec.ts) and check vitest.config include patterns

原因：测试文件模式与vitest.config中的include/exclude通配符不匹配解决方案：验证测试文件是否存在且命名正确（.test.ts、.spec.ts），并检查vitest.config中的include模式

Error: "Test environment not found"

错误："Test environment not found"

Cause: Missing jsdom or happy-dom dependency for DOM tests Solution: Check vitest.config.ts environment setting; advise installing

@testing-library/jest-dom

jsdom

as devDependency

原因：DOM测试缺少jsdom或happy-dom依赖解决方案：检查vitest.config.ts中的environment设置；建议安装

@testing-library/jest-dom

或

jsdom

作为开发依赖

Error: "Out of memory" (large test suites)

错误："Out of memory"（大型测试套件）

Cause: Too many tests running in shared thread pool Solution: Run tests in batches by directory, use

--pool=forks

for memory isolation, or

--shard=N/M

for splitting

原因：太多测试在共享线程池中运行解决方案：按目录分批运行测试，使用

--pool=forks

实现内存隔离，或使用

--shard=N/M

拆分测试

Anti-Patterns

反模式

Anti-Pattern 1: Running Watch Mode

反模式1：运行监听模式

What it looks like: Running

npx vitest

without the

run

subcommand Why wrong: Watch mode is interactive and will never complete in a non-interactive shell Do instead: Always use

npx vitest run

表现：运行

npx vitest

而不带

run

子命令 错误原因：监听模式是交互式的，在非交互式shell中永远不会完成 正确做法：始终使用

npx vitest run

Anti-Pattern 2: Hiding Failures

反模式2：隐藏失败信息

What it looks like: Reporting "3 tests failed" without showing which tests or why Why wrong: Users need full failure details (test name, error, stack trace) to fix tests Do instead: Show complete failure output for every failing test

表现：仅报告“3个测试失败”而不显示具体是哪些测试及失败原因 错误原因：用户需要完整的失败细节（测试名称、错误、堆栈跟踪）才能修复测试 正确做法：显示每个失败测试的完整输出

Anti-Pattern 3: Auto-Fixing Test Assertions

反模式3：自动修复测试断言

What it looks like: Seeing a failing assertion and updating the expected value to match actual Why wrong: The test might be correct and the implementation wrong; needs user judgment Do instead: Present the failure clearly, let user decide if test or code needs fixing

表现：看到失败的断言后，将预期值更新为匹配实际值 错误原因：可能是测试正确而实现错误，需要用户判断 正确做法：清晰呈现失败信息，让用户决定是修复测试还是代码

Anti-Pattern 4: Running Without Project Context

反模式4：无项目上下文运行测试

What it looks like: Running

npx vitest run

in a directory without package.json Why wrong: Vitest needs project context, dependencies, and configuration Do instead: Verify package.json exists and vitest is configured before running

表现：在没有package.json的目录中运行

npx vitest run

错误原因：Vitest需要项目上下文、依赖和配置 正确做法：运行前确认package.json存在且已配置Vitest

References

参考资料

This skill uses these shared patterns:

Verification Checklist - Pre-completion checks
Anti-Rationalization - Prevents shortcut rationalizations

本Skill使用以下共享模式：

验证清单 - 完成前检查
反合理化 - 防止捷径式合理化

Domain-Specific Anti-Rationalization

领域特定反合理化

Rationalization	Why It's Wrong	Required Action
"Tests probably pass"	Assumption, not evidence	Run the tests
"Only one test failed, not important"	Every failure is signal	Report all failures completely
"I'll fix the assertion to make it pass"	May hide real bugs	Present failure, let user decide
"No need to show stack traces"	Stack traces locate the problem	Always include stack traces

合理化借口	错误原因	要求操作
"测试可能通过了"	这是假设而非证据	运行测试
"只有一个测试失败，不重要"	每个失败都是信号	完整报告所有失败
"我会修改断言使其通过"	可能隐藏真实bug	呈现失败信息，由用户决定
"不需要显示堆栈跟踪"	堆栈跟踪可定位问题	始终包含堆栈跟踪