如何用TAP格式化工具自定义Node.js原生测试输出及排查问题

问题背景 #

Node.js原生测试运行器默认输出体验较差，希望结合社区TAP格式化工具（如tap-parser）优化输出，但使用node:test模块的run方法批量执行测试文件时，无法看到子测试的详细信息，仅能获取文件级别的测试结果。

现有代码 #

test.js

import { run } from 'node:test'

const files = ['./example.test.js']

run({ files }).pipe(process.stdout)

example.test.js

import test from 'node:test'

test('foo', () => {
  console.log('start')
})

异常现象 #

执行node ./test.js的输出（缺失子测试信息）：

TAP version 13
# Subtest: ./example.test.js
ok 1 - ./example.test.js
  ---
  duration_ms: 415.054557
  ...
1..1
# tests 1
# pass 1
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 417.190938

直接执行node ./example.test.js的正常输出（包含子测试）：

TAP version 13
# Subtest: foo
ok 1 - foo
  ---
  duration_ms: 1.786378
  ...
1
# tests 1
# pass 1
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 210.586371

问题原因 #

使用run()批量执行测试文件时，默认将每个文件作为顶层测试，且默认不输出子测试的详细TAP内容，仅返回文件级别的汇总结果。

解决方案 #

1. 开启子测试输出 #

修改run()的配置，明确指定TAP报告器并匹配所有测试，确保子测试内容被输出：

import { run } from 'node:test'

const files = ['./example.test.js']

run({
  files,
  reporter: 'tap', // 强制使用TAP格式输出
  testNamePattern: '.' // 匹配所有测试，包含子测试
}).pipe(process.stdout)

执行后即可看到包含子测试的完整TAP输出。

2. 结合tap-parser自定义格式化输出 #

通过tap-parser解析TAP输出并自定义展示格式：

1. 安装依赖：

npm install tap-parser

2. 修改test.js：

import { run } from 'node:test'
import { Parser } from 'tap-parser'

const files = ['./example.test.js']
const parser = new Parser()

// 监听测试结果事件，自定义输出
parser.on('result', (result) => {
  if (result.type === 'test') {
    console.log(`测试 ${result.name}: ${result.ok ? '✅ 通过' : '❌ 失败'}`)
    result.time && console.log(`耗时: ${result.time}ms`)
  }
})

// 监听测试总结事件
parser.on('summary', (summary) => {
  console.log('\n--- 测试总结 ---')
  console.log(`总测试数: ${summary.count}`)
  console.log(`通过: ${summary.pass}`)
  console.log(`失败: ${summary.fail}`)
})

// 将测试输出传递给parser处理
run({ files, reporter: 'tap' }).pipe(parser)

执行node ./test.js会得到自定义格式的输出：

测试 foo: ✅ 通过
耗时: 1.786378ms

--- 测试总结 ---
总测试数: 1
通过: 1
失败: 0

3. 使用成熟TAP格式化工具 #

除了tap-parser，还可以用node-tap工具一键格式化输出：

1. 安装工具：

npm install -g tap

2. 管道输出处理：

node ./test.js | tap

即可得到美观的标准化测试报告。

内容的提问来源于stack exchange，提问作者Lance Pollard