apex-tests-git-delta

A Salesforce CLI plugin that extracts Apex test class names from git commit messages for incremental test execution during deployments.

• Why This Plugin?
• Install
• Usage
• Command
• Output Formats
• Alternatives
• Issues
• License

Why This Plugin?

sfdx-git-delta identifies changed Apex classes but running only those modified tests may not cover all required tests. This plugin lets you declare which tests belong to each commit directly in the commit message, giving you explicit control over test selection. It uses the same --from / --to SHA arguments as sfdx-git-delta, so the two tools compose naturally.

Install

sf plugins install apex-tests-git-delta

Requires Node.js >=22.0.0. No git CLI dependency — git operations are handled entirely in TypeScript.

Usage

Create a config file

Create a .apextestsgitdeltarc file in your Salesforce DX project root. The file accepts up to two non-empty lines:

• Line 1 (required): regular expression to capture individual Apex test class names.
• Line 2 (optional): regular expression to capture Apex Test Suite names. Each matched suite name is resolved at the --to commit as <suiteName>.testSuite-meta.xml inside your sfdx-project.json package directories, and its <testClassName> entries are merged into the output.

[Aa][Pp][Ee][Xx]::(.*?)::[Aa][Pp][Ee][Xx]
[Ss][Uu][Ii][Tt][Ee]::(.*?)::[Ss][Uu][Ii][Tt][Ee]

Omitting line 2 disables suite parsing and is fully backward compatible.

Use the format in commit messages

fix: update triggers Apex::AccountTriggerHandlerTest OpportunityTriggerHandlerTest::Apex
chore: add sandbox setup Apex::PrepareMySandboxTest::Apex
fix: resolve quoting issues Apex::QuoteControllerTest::Apex
chore: regression pass Suite::AccountRegressionSuite::Suite

Apex Test Suite wildcards

The plugin supports the same <testClassName> wildcard conventions documented by Salesforce for ApexTestSuite metadata:

<testClassName> entry	Resolution at --to
LocalTestClass	Literal local class. Validated like any class name from a commit message.
A*Class, *Test, Foo_*	Local wildcard. Expanded against all .cls files in your package directories.
*	Expands to every local Apex class at --to.
Namespace1.NamespacedTestClass	Managed-package test. Passed through as-is (not validated).
Namespace1.*	Managed-package wildcard. Passed through as-is; Salesforce resolves at runtime.

Wildcard patterns that match nothing locally produce a warning and contribute no tests.

Run the command to extract tests

sf atgd delta --from "HEAD~1" --to "HEAD"

Output is alphabetically sorted and space-separated:

AccountTriggerHandlerTest OpportunityTriggerHandlerTest PrepareMySandboxTest QuoteControllerTest

Use the output in a deployment command

Use the default space format with a single --tests flag (or -t) that you supply with the CLI command (which accepts a space-separated list):

sf project deploy start -x package/package.xml -l RunSpecifiedTests --tests $(sf atgd delta --from "HEAD~1" --to "HEAD")

Use the sf format to inline tests directly into commands that expect repeated --tests flags (e.g. sf apex run test):

sf apex run test $(sf atgd delta --from "HEAD~1" --to "HEAD" --format sf)
# expands to: sf apex run test --tests AccountTriggerHandlerTest --tests QuoteControllerTest ...

Command

sf atgd delta

USAGE
  $ sf atgd delta -f <value> -t <value> -v [-o space|sf] [--json]

FLAGS
  -f, --from=<value>          Commit SHA from where the commit message log is done.
                              This SHA's commit message will not be included in the results.
  -t, --to=<value>            Commit SHA to where the commit message log is done.
                              [default: HEAD]
  -v, --skip-test-validation  Skip validating that tests exist in the local package directories.
                              [default: false]
  -o, --format=<option>       Output format for the test list.
                              [default: space] <options: space|sf>

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Parse commit messages over a range and return the Apex tests to deploy against.

EXAMPLES
  Get tests from the most recent commit, confirming they exist in the local package directories.

    $ sf atgd delta --from "HEAD~1" --to "HEAD"

  Get tests from the most recent commit, skipping the local package directory validation.

    $ sf atgd delta --from "HEAD~1" --to "HEAD" -v

  Get tests formatted for use with sf apex run test.

    $ sf atgd delta --from "HEAD~1" --to "HEAD" --format sf

Output Formats

Format	Flag	Output	Use with
space (default)	(omit)	ClassA ClassB ClassC	sf project deploy start -t $(...)
sf	--format sf	--tests ClassA --tests ClassB --tests ClassC	sf apex run test $(...)

The sf format lets you compose this plugin directly into Salesforce CLI commands without any shell post-processing:

sf apex run test $(sf atgd delta --from "HEAD~1" --to "HEAD" --format sf)

Alternatives

Plugin	Approach
apex-tests-git-delta	Extracts test classes from commit messages
sfdx-git-delta	Run modified Apex classes
apex-test-list	Uses test annotations in Apex files

Issues

Report bugs or suggest features by creating an issue.

License

MIT