进阶 oclif.io 2026-10-18 02:37:03 · 26 阅读
第44章 CLI 测试
测试
oclif 支持使用任意测试框架进行测试。你可以调用 `MyCommand.run()`,它会返回一个 Promise,你可以对其执行等待操作。
不过,开发 CLI 工具时有一些常见的测试任务。为此,我们提供了 `@oclif/test`,它包含了一套我们在测试 oclif CLI 时认为实用的常规工具。
使用 oclif 构建的任何 CLI 都会预装 mocha(这是我们首选的测试框架,但你完全可以自由使用任何偏好的框架)以及 `@oclif/test`,并附带一个示例测试文件,该测试应能直接通过 `npm test` 或 `yarn test` 运行。
举个例子,我们来看这个 `whoami` 命令,它发起 API 请求以获取当前登录用户的信息。如果用户未登录,该命令将以状态码 100 退出。
src/commands/whoami.ts
import {Command} from '@oclif/core'
export class Whoami extends Command {
async run() {
try {
let {body: account} = await this.api.get('/account')
this.log(account.email)
} catch (err) {
if (err.statusCode === 401) {
this.error('not logged in', {exit: 100})
}
throw err
}
}
}
另一个在测试 oclif CLI 时常用的工具是 nock。请将 nock 包作为 devDependency 安装。 以下是测试代码 test/commands/whoami.test.ts import {runCommand} from '@oclif/test'
import {expect} from 'chai'
import nock from 'nock'
describe('whoami', () => {
it('shows user email when logged in', async () => {
nock('https://api.example.com')
.get('/account')
// user is logged in, return their name
.reply(200, {email: 'jeff@example.com'})
const {stdout} = await runCommand('whoami')
expect(stdout).to.equal('jeff@example.com')
})
it('exits with status 100 when not logged in', async () => {
nock('https://api.example.com')
.get('/account')
// HTTP 401 means the user is not logged in with valid credentials
.reply(401)
const {error} = await runCommand('whoami')
expect(error?.oclif?.exit).to.equal(100)
})
})
关于使用 oclif 进行测试的更多细节,请参考 @oclif/test 的文档。 在 Vitest 中捕获 stdout 和 stderr 将 @oclif/test 与 Vitest 配合使用时需注意,Vitest 默认会拦截 console.log、console.error 等 console 方法。这可能会干扰 @oclif/test 在调用 runCommand() 时捕获 stdout 和 stderr 的能力。 为了确保正确捕获 stdout 和 stderr(例如使用 const { stdout, stderr } = await runCommand("config:dump"); 时),必须在 Vitest 配置中禁用 console 拦截。具体做法是在 vitest.config.ts 中添加一行 disableConsoleIntercept: true。 vitest.config.ts 示例 ts
CopyEdit
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
setupFiles: ["./src/vitest.setup.ts"],
disableConsoleIntercept: true
}
});
为什么这很重要 @oclif/test 依赖原生的 stdout/stderr 流来验证命令行输出。如果 Vitest 拦截了这些流,捕获到的输出就会不完整或缺失,导致断言失败或产生误导。 代码覆盖率 JavaScript 和 TypeScript 项目通过 nyc 自动提供代码覆盖率。只需运行 yarn test 即可显示覆盖率数据。如有需要,也可以在 CI 脚本中将覆盖率数据发送到 codecov。
export class Whoami extends Command {
async run() {
try {
let {body: account} = await this.api.get('/account')
this.log(account.email)
} catch (err) {
if (err.statusCode === 401) {
this.error('not logged in', {exit: 100})
}
throw err
}
}
}
另一个在测试 oclif CLI 时常用的工具是 nock。请将 nock 包作为 devDependency 安装。 以下是测试代码 test/commands/whoami.test.ts import {runCommand} from '@oclif/test'
import {expect} from 'chai'
import nock from 'nock'
describe('whoami', () => {
it('shows user email when logged in', async () => {
nock('https://api.example.com')
.get('/account')
// user is logged in, return their name
.reply(200, {email: 'jeff@example.com'})
const {stdout} = await runCommand('whoami')
expect(stdout).to.equal('jeff@example.com')
})
it('exits with status 100 when not logged in', async () => {
nock('https://api.example.com')
.get('/account')
// HTTP 401 means the user is not logged in with valid credentials
.reply(401)
const {error} = await runCommand('whoami')
expect(error?.oclif?.exit).to.equal(100)
})
})
关于使用 oclif 进行测试的更多细节,请参考 @oclif/test 的文档。 在 Vitest 中捕获 stdout 和 stderr 将 @oclif/test 与 Vitest 配合使用时需注意,Vitest 默认会拦截 console.log、console.error 等 console 方法。这可能会干扰 @oclif/test 在调用 runCommand() 时捕获 stdout 和 stderr 的能力。 为了确保正确捕获 stdout 和 stderr(例如使用 const { stdout, stderr } = await runCommand("config:dump"); 时),必须在 Vitest 配置中禁用 console 拦截。具体做法是在 vitest.config.ts 中添加一行 disableConsoleIntercept: true。 vitest.config.ts 示例 ts
CopyEdit
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
setupFiles: ["./src/vitest.setup.ts"],
disableConsoleIntercept: true
}
});
为什么这很重要 @oclif/test 依赖原生的 stdout/stderr 流来验证命令行输出。如果 Vitest 拦截了这些流,捕获到的输出就会不完整或缺失,导致断言失败或产生误导。 代码覆盖率 JavaScript 和 TypeScript 项目通过 nyc 自动提供代码覆盖率。只需运行 yarn test 即可显示覆盖率数据。如有需要,也可以在 CI 脚本中将覆盖率数据发送到 codecov。