@oclif/test 4.0.1-beta.2 → 4.0.1-beta.4

package/README.md

@@ -6,230 +6,33 @@ test helpers for oclif CLIs
 [![Downloads/week](https://img.shields.io/npm/dw/@oclif/test.svg)](https://npmjs.org/package/@oclif/test)
 [![License](https://img.shields.io/npm/l/@oclif/test.svg)](https://github.com/oclif/test/blob/main/package.json)
 
+## Migration
+
+See the [V4 Migration Guide](./MIGRATION.md) if you are migrating from v3 or older.
+
 ## Usage
 
-`@oclif/test` is an extension of [fancy-test](https://github.com/oclif/fancy-test). Please see the [fancy-test documentation](https://github.com/oclif/fancy-test#fancy-test) 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`](https://github.com/oclif/core/blob/main/src/config/config.ts) instance. This instance will be available on the `ctx` variable that's provided in the callback.
-
-```typescript
-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`:
-
-```typescript
-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.
-
-```typescript
-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](https://oclif.io/docs/single_command_cli) you would provide `'.'` as the command. For instance:
-
-```typescript
-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`:
-
-```typescript
-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.
-
-```typescript
-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`:
-
-```typescript
-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.
-
-```typescript
-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`:
-
-```typescript
-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
-  })
-})
-```
+`@oclif/test` provides a handful of utilities that make it easy to test your [oclif](https://oclif.io) CLI.
+
+### `captureOutput`
+
+`captureOutput` allows you to get the stdout, stderr, return value, and error of the callback you provide it. This makes it possible to assert that certain strings were printed to stdout and stderr or that the callback failed with the expected error or succeeded with the expected result.
+
+**Options**
+
+- `print` - Print everything that goes to stdout and stderr.
+- `stripAnsi` - Strip ansi codes from everything that goes to stdout and stderr. Defaults to true.
+
+See the [tests](./test/capture-output.test.ts) for example usage.
+
+### `runCommand`
+
+`runCommand` allows you to get the stdout, stderr, return value, and error of a command in your CLI.
+
+See the [tests](./test/run-command.test.ts) for example usage.
+
+### `runHook`
+
+`runHook` allows you to get the stdout, stderr, return value, and error of a hook in your CLI.
+
+See the [tests](./test/run-hook.test.ts) for example usage.

package/lib/index.d.ts

@@ -3,22 +3,52 @@ type CaptureOptions = {
     print?: boolean;
     stripAnsi?: boolean;
 };
-export declare function captureOutput<T>(fn: () => Promise<unknown>, opts?: CaptureOptions): Promise<{
+type CaptureResult<T> = {
     error?: Error & Partial<Errors.CLIError>;
     result?: T;
     stderr: string;
     stdout: string;
-}>;
-export declare function runCommand<T>(args: string | string[], loadOpts?: Interfaces.LoadOptions, captureOpts?: CaptureOptions): Promise<{
-    error?: Error & Partial<Errors.CLIError>;
-    result?: T;
-    stderr: string;
-    stdout: string;
-}>;
-export declare function runHook<T>(hook: string, options: Record<string, unknown>, loadOpts?: Interfaces.LoadOptions, recordOpts?: CaptureOptions): Promise<{
-    error?: Error & Partial<Errors.CLIError>;
-    result?: T;
-    stderr: string;
-    stdout: string;
-}>;
+};
+/**
+ * Capture the stderr and stdout output of a function
+ * @param fn async function to run
+ * @param opts options
+ *  - print: Whether to print the output to the console
+ *  - stripAnsi: Whether to strip ANSI codes from the output
+ * @returns {Promise<CaptureResult<T>>} Captured output
+ *   - error: Error object if the function throws an error
+ *   - result: Result of the function if it returns a value and succeeds
+ *   - stderr: Captured stderr output
+ *   - stdout: Captured stdout output
+ */
+export declare function captureOutput<T>(fn: () => Promise<unknown>, opts?: CaptureOptions): Promise<CaptureResult<T>>;
+/**
+ * Capture the stderr and stdout output of a command in your CLI
+ * @param args Command arguments, e.g. `['my:command', '--flag']` or `'my:command --flag'`
+ * @param loadOpts options for loading oclif `Config`
+ * @param captureOpts options for capturing the output
+ *  - print: Whether to print the output to the console
+ *  - stripAnsi: Whether to strip ANSI codes from the output
+ * @returns {Promise<CaptureResult<T>>} Captured output
+ *   - error: Error object if the command throws an error
+ *   - result: Result of the command if it returns a value and succeeds
+ *   - stderr: Captured stderr output
+ *   - stdout: Captured stdout output
+ */
+export declare function runCommand<T>(args: string | string[], loadOpts?: Interfaces.LoadOptions, captureOpts?: CaptureOptions): Promise<CaptureResult<T>>;
+/**
+ * Capture the stderr and stdout output of a hook in your CLI
+ * @param hook Hook name
+ * @param options options to pass to the hook
+ * @param loadOpts options for loading oclif `Config`
+ * @param captureOpts options for capturing the output
+ *  - print: Whether to print the output to the console
+ *  - stripAnsi: Whether to strip ANSI codes from the output
+ * @returns {Promise<CaptureResult<T>>} Captured output
+ *   - error: Error object if the hook throws an error
+ *   - result: Result of the hook if it returns a value and succeeds
+ *   - stderr: Captured stderr output
+ *   - stdout: Captured stdout output
+ */
+export declare function runHook<T>(hook: string, options: Record<string, unknown>, loadOpts?: Interfaces.LoadOptions, captureOpts?: CaptureOptions): Promise<CaptureResult<T>>;
 export {};

package/lib/index.js

@@ -27,6 +27,18 @@ function findRoot() {
 function makeLoadOptions(loadOpts) {
     return loadOpts ?? { root: findRoot() };
 }
+/**
+ * Capture the stderr and stdout output of a function
+ * @param fn async function to run
+ * @param opts options
+ *  - print: Whether to print the output to the console
+ *  - stripAnsi: Whether to strip ANSI codes from the output
+ * @returns {Promise<CaptureResult<T>>} Captured output
+ *   - error: Error object if the function throws an error
+ *   - result: Result of the function if it returns a value and succeeds
+ *   - stderr: Captured stderr output
+ *   - stdout: Captured stdout output
+ */
 async function captureOutput(fn, opts) {
     const print = opts?.print ?? false;
     const stripAnsi = opts?.stripAnsi ?? true;
@@ -81,6 +93,19 @@ async function captureOutput(fn, opts) {
     }
 }
 exports.captureOutput = captureOutput;
+/**
+ * Capture the stderr and stdout output of a command in your CLI
+ * @param args Command arguments, e.g. `['my:command', '--flag']` or `'my:command --flag'`
+ * @param loadOpts options for loading oclif `Config`
+ * @param captureOpts options for capturing the output
+ *  - print: Whether to print the output to the console
+ *  - stripAnsi: Whether to strip ANSI codes from the output
+ * @returns {Promise<CaptureResult<T>>} Captured output
+ *   - error: Error object if the command throws an error
+ *   - result: Result of the command if it returns a value and succeeds
+ *   - stderr: Captured stderr output
+ *   - stdout: Captured stdout output
+ */
 async function runCommand(args, loadOpts, captureOpts) {
     const loadOptions = makeLoadOptions(loadOpts);
     const argsArray = (Array.isArray(args) ? args : [args]).join(' ').split(' ');
@@ -91,12 +116,26 @@ async function runCommand(args, loadOpts, captureOpts) {
     return captureOutput(async () => (0, core_1.run)(finalArgs, loadOptions), captureOpts);
 }
 exports.runCommand = runCommand;
-async function runHook(hook, options, loadOpts, recordOpts) {
+/**
+ * Capture the stderr and stdout output of a hook in your CLI
+ * @param hook Hook name
+ * @param options options to pass to the hook
+ * @param loadOpts options for loading oclif `Config`
+ * @param captureOpts options for capturing the output
+ *  - print: Whether to print the output to the console
+ *  - stripAnsi: Whether to strip ANSI codes from the output
+ * @returns {Promise<CaptureResult<T>>} Captured output
+ *   - error: Error object if the hook throws an error
+ *   - result: Result of the hook if it returns a value and succeeds
+ *   - stderr: Captured stderr output
+ *   - stdout: Captured stdout output
+ */
+async function runHook(hook, options, loadOpts, captureOpts) {
     const loadOptions = makeLoadOptions(loadOpts);
     debug('loadOpts: %O', loadOptions);
     return captureOutput(async () => {
         const config = await core_1.Config.load(loadOptions);
         return config.runHook(hook, options);
-    }, recordOpts);
+    }, captureOpts);
 }
 exports.runHook = runHook;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/test",
   "description": "test helpers for oclif components",
-  "version": "4.0.1-beta.2",
+  "version": "4.0.1-beta.4",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/test/issues",
   "dependencies": {
@@ -9,7 +9,7 @@
     "debug": "^4.3.4"
   },
   "peerDependencies": {
-    "@oclif/core": "^4.0.0-beta.7"
+    "@oclif/core": ">= 3.0.0"
   },
   "devDependencies": {
     "@commitlint/config-conventional": "^18.6.3",