The @salesforce/source-testkit library wraps around @salesforce/cli-plugins-testkit to provide a simple interface for Salesforce CLI plug-in authors to compose source (e.g. deploy, retrieve, push, and pull) related non-unit-tests (NUTs).

Specifically, SourceTestKit provides the following conveniences:

1. Wrapper methods for the source CLI commands. For example, the force:source:deploy and force:source:retrieve commands can be invoked like so:

   const sourceTestkit = await SourceTestkit.create({
     repository: 'https://github.com/trailheadapps/dreamhouse-lwc.git',
     nut: __filename,
   });
   sourceTestkit.deploy({ args: `--sourcepath force-app` });
   sourceTestkit.retrieve({ args: `--sourcepath force-app` });

2. Common assertions like expecting a file to be deployed or expecting a file to be retrieved. These are all accessible under sourceTestkit.expect. For example:

   const sourceTestkit = await SourceTestkit.create({
     repository: 'https://github.com/trailheadapps/dreamhouse-lwc.git',
     nut: __filename,
   });
   sourceTestkit.deploy({ args: `--sourcepath force-app` });
   sourceTestkit.expect.filesToBeDeployed('force-app/**/*');

   NOTE When providing files paths to these assertion methods, you need to provide a glob pattern, NOT an OS specific file path. We have chosen this approach because it provides a lot of flexibility when writing tests and because it's OS agnostic.

Add this library as a dev dependencies to your project.

yarn add @salesforcecli/source-testkit --dev

import { SourceTestkit } from '@salesforce/source-testkit';

context('Deploy from source path NUT', () => {
  let sourceTestkit: SourceTestkit;

  before(async () => {
    sourceTestkit = await SourceTestkit.create({
      repository: 'https://github.com/trailheadapps/dreamhouse-lwc.git',
      nut: __filename,
    });
  });

  after(async () => {
    await sourceTestkit?.clean();
  });

  describe('--sourcepath flag', () => {
    it(`should deploy force-app`, async () => {
      await sourceTestkit.deploy({ args: '--sourcepath force-app' });
      await sourceTestkit.expect.filesToBeDeployed(['force-app/**/*']);
    });

    it('should throw an error if the sourcepath is not valid', async () => {
      const deploy = await sourceTestkit.deploy({ args: '--sourcepath DOES_NOT_EXIST', exitCode: 1 });
      sourceTestkit.expect.errorToHaveName(deploy, 'SourcePathInvalid');
    });
  });
});