@oclif/test

What is @oclif/test?

@oclif/test is a testing framework specifically designed for testing oclif-based CLI applications. It provides utilities to simulate command execution, check outputs, and handle various test scenarios.

What are @oclif/test's main functionalities?

Simulate Command Execution

This feature allows you to simulate the execution of a CLI command and check the output. In this example, the command 'hello --name world' is executed, and the test checks if the output contains 'hello world'.

const {expect, test} = require('@oclif/test');

test
  .stdout()
  .command(['hello', '--name', 'world'])
  .it('runs hello --name world', ctx => {
    expect(ctx.stdout).to.contain('hello world');
  });

Check Command Errors

This feature allows you to test how your CLI handles errors. In this example, the command 'hello --name' is missing a required value, and the test checks if the error message contains 'Missing required flag'.

const {expect, test} = require('@oclif/test');

test
  .stderr()
  .command(['hello', '--name'])
  .catch(err => {
    expect(err.message).to.contain('Missing required flag');
  })
  .it('runs hello --name with missing value', ctx => {});

Mocking HTTP Requests

This feature allows you to mock HTTP requests during your tests. In this example, a GET request to 'https://api.example.com/data' is mocked to return 'test data', and the test checks if the command 'fetch-data' outputs 'test data'.

const {expect, test} = require('@oclif/test');
const nock = require('nock');

test
  .nock('https://api.example.com', api => api
    .get('/data')
    .reply(200, {data: 'test data'})
  )
  .stdout()
  .command(['fetch-data'])
  .it('runs fetch-data and mocks HTTP request', ctx => {
    expect(ctx.stdout).to.contain('test data');
  });

Other packages similar to @oclif/test

mocha

Mocha is a feature-rich JavaScript test framework running on Node.js and in the browser, making asynchronous testing simple and fun. While Mocha is a general-purpose testing framework, @oclif/test is specifically designed for testing oclif-based CLI applications.

jest

Jest is a delightful JavaScript Testing Framework with a focus on simplicity. It works with projects using Babel, TypeScript, Node.js, React, Angular, Vue.js, and Svelte. Jest is more general-purpose compared to @oclif/test, which is tailored for oclif CLI applications.

chai

Chai is a BDD / TDD assertion library for node and the browser that can be paired with any JavaScript testing framework. Chai provides assertions that can be used in conjunction with @oclif/test, but it does not provide the CLI-specific testing utilities that @oclif/test offers.

README

@oclif/test

test helpers for oclif CLIs

Usage

@oclif/test is an extension of fancy-test. Please see the fancy-test documentation for all the features that are available.

The following are the features that @oclif/test adds to fancy-test.

.loadConfig()

.loadConfig() creates and returns a new Config instance. This instance will be available on the ctx variable that's provided in the callback.

import {join} from 'node:path'
import {expect, test} from '@oclif/test'

const root = join(__dirname, 'fixtures/test-cli')
test
  .loadConfig({root})
  .stdout()
  .command(['foo:bar'])
  .it('should run the command from the given directory', (ctx) => {
    expect(ctx.stdout).to.equal('hello world!\n')
    expect(ctx.config.root).to.equal(root)
    const {name} = ctx.returned as {name: string}
    expect(name).to.equal('world')
  })

If you would like to run the same test without using @oclif/test:

import {Config, ux} from '@oclif/core'
import {expect} from 'chai'
import {join} from 'node:path'
import {SinonSandbox, SinonStub, createSandbox} from 'sinon'

const root = join(__dirname, 'fixtures/test-cli')
describe('non-fancy test', () => {
  let sandbox: SinonSandbox
  let config: Config
  let stdoutStub: SinonStub

  beforeEach(async () => {
    sandbox = createSandbox()
    stdoutStub = sandbox.stub(ux.write, 'stdout')
    config = await Config.load({root})
  })

  afterEach(async () => {
    sandbox.restore()
  })

  it('should run command from the given directory', async () => {
    const {name} = await config.runCommand<{name: string}>('foo:bar')
    expect(stdoutStub.calledWith('hello world!\n')).to.be.true
    expect(config.root).to.equal(root)
    expect(name).to.equal('world')
  })
})

.command()

.command() let's you run a command from your CLI.

import {expect, test} from '@oclif/test'

describe('hello world', () => {
  test
    .stdout()
    .command(['hello:world'])
    .it('runs hello world cmd', (ctx) => {
      expect(ctx.stdout).to.contain('hello world!')
    })
})

For a single command cli you would provide '.' as the command. For instance:

import {expect, test} from '@oclif/test'

describe('hello world', () => {
  test
    .stdout()
    .command(['.'])
    .it('runs hello world cmd', (ctx) => {
      expect(ctx.stdout).to.contain('hello world!')
    })
})

If you would like to run the same test without using @oclif/test:

import {Config, ux} from '@oclif/core'
import {expect} from 'chai'
import {SinonSandbox, SinonStub, createSandbox} from 'sinon'

describe('non-fancy test', () => {
  let sandbox: SinonSandbox
  let config: Config
  let stdoutStub: SinonStub

  beforeEach(async () => {
    sandbox = createSandbox()
    stdoutStub = sandbox.stub(ux.write, 'stdout')
    config = await Config.load({root: process.cwd()})
  })

  afterEach(async () => {
    sandbox.restore()
  })

  it('should run command', async () => {
    // use '.' for a single command CLI
    const {name} = await config.runCommand<{name: string}>('hello:world')
    expect(stdoutStub.calledWith('hello world!\n')).to.be.true
    expect(name).to.equal('world')
  })
})

.exit()

.exit() let's you test that a command exited with a certain exit code.

import {join} from 'node:path'
import {expect, test} from '@oclif/test'

describe('exit', () => {
  test
    .loadConfig()
    .stdout()
    .command(['hello:world', '--code=101'])
    .exit(101)
    .do((output) => expect(output.stdout).to.equal('exiting with code 101\n'))
    .it('should exit with code 101')
})

If you would like to run the same test without using @oclif/test:

import {Config, Errors, ux} from '@oclif/core'
import {expect} from 'chai'
import {SinonSandbox, createSandbox} from 'sinon'

describe('non-fancy test', () => {
  let sandbox: SinonSandbox
  let config: Config

  beforeEach(async () => {
    sandbox = createSandbox()
    sandbox.stub(ux.write, 'stdout')
    config = await Config.load({root: process.cwd()})
  })

  afterEach(async () => {
    sandbox.restore()
  })

  it('should run command from the given directory', async () => {
    try {
      await config.runCommand('.')
      throw new Error('Expected CLIError to be thrown')
    } catch (error) {
      if (error instanceof Errors.CLIError) {
        expect(error.oclif.exit).to.equal(101)
      } else {
        throw error
      }
    }
  })
})

.hook()

.hook() let's you test a hook in your CLI.

import {join} from 'node:path'

import {expect, test} from '@oclif/test'

const root = join(__dirname, 'fixtures/test-cli')

describe('hooks', () => {
  test
    .loadConfig({root})
    .stdout()
    .hook('foo', {argv: ['arg']}, {root})
    .do((output) => expect(output.stdout).to.equal('foo hook args: arg\n'))
    .it('should run hook')
})

If you would like to run the same test without using @oclif/test:

import {Config, ux} from '@oclif/core'
import {expect} from 'chai'
import {SinonSandbox, SinonStub, createSandbox} from 'sinon'

describe('non-fancy test', () => {
  let sandbox: SinonSandbox
  let config: Config
  let stdoutStub: SinonStub

  beforeEach(async () => {
    sandbox = createSandbox()
    stdoutStub = sandbox.stub(ux.write, 'stdout')
    config = await Config.load({root: process.cwd()})
  })

  afterEach(async () => {
    sandbox.restore()
  })

  it('should run hook', async () => {
    const {name} = await config.runHook('foo', {argv: ['arg']})
    expect(stdoutStub.calledWith('foo hook args: arg\n')).to.be.true
  })
})

Changelog

3.1.3 (2023-11-27)

Bug Fixes

• deps: bump @oclif/core from 3.10.8 to 3.12.0 (a87acdd)