Test Your Plugin

It’s critical to test your plugin to make sure it works correctly, safely, and in a consistent way.

Our Testing Philosophy

We (the Salesforce CLI dev team) use two types of tests to fortify the quality of our plugins:

Unit tests
Non-unit-tests (NUTs)

We use unit tests to test library-level code and NUTs to test command-level code. With this philosophy, unit tests verify the functionality of the classes and functions consumed by a command. And then NUTs verify that the command itself works as expected.

You can, of course, test your plugin however you want, although we recommend you give our philosophy a try. The next sections describe in more detail how we use NUTs and unit tests.

Unit Tests

For library-level code, we like to write unit tests using mocha to run the tests and nyc for test coverage. You’re not limited to this framework - you’re welcome to use whatever NodeJS-compatible testing framework works best for you, such as jest.

Here are some examples of how we use unit tests across our codebases:

Unit Tests for Commands

While we strongly recommend writing NUTs for command-level unit tests, it’s possible to do this. Here’s a brief example:

1import { expect } from "chai";
2import { TestContext } from "@salesforce/core/lib/testSetup";
3import { stubSfCommandUx } from "@salesforce/sf-plugins-core";
4import { DoStuff } from "../../../../src/commands/do/stuff";
5
6describe("do:stuff", () => {
7  const $$ = new TestContext();
8  let sfCommandUxStubs: ReturnType<typeof stubSfCommandUx>;
9
10  beforeEach(async () => {
11    // stub SfCommand's ux methods so that command output is suppressed
12    // and so that you can assert that certain methods were called with
13    // the correct args.
14    sfCommandUxStubs = stubSfCommandUx($$.SANDBOX);
15  });
16
17  it("should do awesome things", async () => {
18    // run the command using the static run method
19    const result = await DoStuff.run(["--flag1", "--flag2"]);
20
21    expect(result).to.be.ok;
22    expect(sfCommandUxStubs.log.firstCall.firstArg).to.equal("hello world");
23  });
24});

Here are some examples of how we write command-level unit tests across our codebases:

See the stubUx docs for built-in stubs for spinners, tables, warnings, prompts, and more.

Non-Unit-Tests

We use non-unit-tests, known as NUTs, for command-level testing. As the name implies, NUTs are automated tests that aren’t unit tests. NUTs typically include integration, functional, UI, and smoke tests that require a system outside your code to accomplish the test.

This style of testing allows you to use an isolated Salesforce project and file system against production Salesforce orgs. As a result, you can write tests that mimic your customers’ environments as closely as possible. And you’re not required to write and maintain mocked API responses anymore.

See the examples in the @salesforce/cli-plugins-testkit repo.