@j-schreiber/sf-cli-plugin-api-testing

A small utility to create, maintain, and run data-driven API tests. Scaffolds directories, creates test cases, provides frameworks for test data setup/teardown and assertions, and finally runs tests.

Installation

To build from source, follow these steps

git clone https://github.com/j-schreiber/js-sf-cli-api-testing
cd js-sf-cli-api-testing
yarn && yarn build
sf plugins link .

To install the latest version from NPM

sf plugins install @j-schreiber/sf-cli-plugin-api-testing

To use in CI (example with two plugins)

steps:
  - name: Install CLI Bundle
    uses: allvest/salesforce-gha-tools/.github/actions/install@main
    with:
      plugins: |
        @j-schreiber/sf-plugin
        @j-schreiber/sf-cli-plugin-api-testing

Local Development & NUTs (Scratch Org Integration Tests)

CI currently does not run NUTs - they are commited, but only run locally. NUTs depend on dotenv. Use .env.example to set up your .env. .mocharc.json requires dotenv/config, which exports the AUTH_URL and INSTALLATION_KEY for the test run execution.

yarn test:nuts

Documentation

• sf allvest tests debug
• sf allvest tests discover
• sf allvest tests run

sf allvest tests debug

Run a single event test case and stream its request and response to the console.

USAGE
  $ sf allvest tests debug -f <value> -o <value> [--json] [--flags-dir <value>] [--api-version <value>] [--verbose]

FLAGS
  -f, --file=<value>         (required) Path to a single event test-case file to run.
  -o, --target-org=<value>   (required) Username or alias of the target org. Not required if the `target-org`
                             configuration variable is already set.
      --api-version=<value>  Override the api version used for api requests made by this command
      --verbose              Also print the request body. Hidden by default.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Run a single event test case and stream its request and response to the console.

  Loads one event test case by file path (the same way the "discover" command reads a case, but for a single file) and
  executes it against a target org using the same HTTP transport as the "run" command. Unlike "run", it makes no
  assertions and renders no multi-stage output: it simply streams the request parameters (method, URL, headers, body)
  and the response parameters (status code, body) to the console so you can inspect a single callout end to end.

  The endpoint is derived from the file's location on disk (services/apexrest/v1/<event-dir>/<event-path>), so the file
  must live under an "event" or "events" directory following the Apex Utils EventRegistry convention.

EXAMPLES
  Debug a single test case against your default org

    $ sf allvest tests debug --file test/data/discover-fixtures/non-empty-dirs/event/my-event.v1/bare-body.json \
      --target-org my-scratch

See code: src/commands/allvest/tests/debug.ts

sf allvest tests discover

Discover and validate event test cases in a directory.

USAGE
  $ sf allvest tests discover -d <value> [--json] [--flags-dir <value>]

FLAGS
  -d, --source-dir=<value>  (required) Directory to scan for event test cases.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Discover and validate event test cases in a directory.

  Scans a directory for event test cases and validates each one against the expected schema. Looks for the fixed "event"
  and "events" subdirectories (the Apex Utils EventRegistry convention), treats each of their subdirectories as an event
  path, and reads every JSON file within as a test case.

  Test cases are printed as a tree, with a checkmark for valid files and an error detail for invalid ones. This command
  does not contact an org; it is intended to check and sanitise test cases before they run in CI. It always exits 0,
  even when invalid test cases are found.

EXAMPLES
  Discover all test cases in a directory

    $ sf allvest tests discover --source-dir my-e2e-tests/data

See code: src/commands/allvest/tests/discover.ts

sf allvest tests run

Run event test cases in a directory against a target org.

USAGE
  $ sf allvest tests run -d <value> -o <value> [--json] [--flags-dir <value>] [--api-version <value>] [--strict] [-f
    <value>]

FLAGS
  -d, --source-dir=<value>   (required) Directory to scan for event test cases.
  -f, --filter=<value>       Only run test cases whose event path or test-case name contains this term
                             (case-insensitive).
  -o, --target-org=<value>   (required) Username or alias of the target org. Not required if the `target-org`
                             configuration variable is already set.
      --api-version=<value>  Override the api version used for api requests made by this command
      --strict               Fail before running if the directory contains any invalid test case.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Run event test cases in a directory against a target org.

  Discovers event test cases in a directory (the same way the "discover" command does), then executes each valid test
  case against a target org and asserts its response. Looks for the fixed "event" and "events" subdirectories (the Apex
  Utils EventRegistry convention), treats each of their subdirectories as an event path, and reads every JSON file
  within as a test case.

  Each test case POSTs its "request" payload to the derived Apex REST endpoint
  (services/apexrest/v1/<event-dir>/<event-path>) and asserts the response status code and, when given, a deep-partial
  match of the response body.

  By default, invalid test cases are skipped and reported at the end; the run proceeds with all valid cases. Use
  --strict to fail the command before running anything if any invalid test case is found. The command exits with a
  non-zero code when any test case fails.

EXAMPLES
  Run all valid test cases in a directory against your default org

    $ sf allvest tests run --source-dir my-e2e-tests/data --target-org my-scratch

  Fail fast if any test case in the directory is invalid

    $ sf allvest tests run --source-dir my-e2e-tests/data --target-org my-scratch --strict

  Run only the test cases for one event path

    $ sf allvest tests run --source-dir my-e2e-tests/data --target-org my-scratch --filter my-event.v1

  Run a particular named test case across every event

    $ sf allvest tests run --source-dir my-e2e-tests/data --target-org my-scratch --filter bare-body

See code: src/commands/allvest/tests/run.ts