Running Apex Tests

The apextests trigger command allows you to independently execute Apex tests in your Salesforce org. While the validate command automatically runs tests per package during validation, this command gives you direct control over test execution with support for multiple test levels, code coverage validation, and output formats.

Primary Testing Patterns

sfp follows a package-centric testing approach where tests are organized and executed at the package or domain level, rather than running all org tests together. This aligns with how the validate command works and provides better isolation and faster feedback.

# Test a specific package (primary pattern)
sfp apextests trigger -o my-org -l RunAllTestsInPackage -n my-package

# Test all packages in a domain (recommended for domain validation)
sfp apextests trigger -o my-org -l RunAllTestsInDomain -r config/release-config.yaml

# Test multiple packages together
sfp apextests trigger -o my-org -l RunAllTestsInPackage -n package-a -n package-b

# Quick test during development
sfp apextests trigger -o my-org -l RunSpecifiedTests --specifiedtests MyTest

Test Levels

RunAllTestsInPackage (Recommended)

Runs all tests within specified package(s). This is the primary testing pattern in sfp and matches how the validate command executes tests. Supports code coverage validation at both package and individual class levels.

# Single package
sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n sales-core

# Multiple packages
sfp apextests trigger -o dev-org -l RunAllTestsInPackage \
  -n sales-core \
  -n sales-ui \
  -n sales-integration

This pattern matches how validate command executes tests - each package is tested independently with its own test classes. This provides:

Better test isolation and faster feedback
Package-level code coverage validation
Clear attribution of test failures to specific packages
Parallel test execution per package (when enabled)

RunAllTestsInDomain (Recommended for Domain Validation)

Runs tests for all packages defined in a domain from your release config. This is the recommended pattern for validating entire domains and matches how you would validate a domain for release.

sfp apextests trigger -o dev-org -l RunAllTestsInDomain \
  -r config/release-config-sales.yaml

-r is what selects the domain. Without it the package list is empty and the command succeeds without running any tests, so always pass it with this test level.

This executes tests for each package in the domain sequentially, providing comprehensive domain validation. Use this when:

Validating changes across a domain before release
Testing related packages together as a unit
Performing end-to-end domain validation

RunSpecifiedTests

Runs specific test classes or methods. Useful for rapid iteration during active development.

# Run specific test classes
sfp apextests trigger -o dev-org -l RunSpecifiedTests \
  --specifiedtests AccountTest,ContactTest

# Run specific test methods
sfp apextests trigger -o dev-org -l RunSpecifiedTests \
  --specifiedtests AccountTest.testCreate,ContactTest.testUpdate

Use during development for quick feedback cycles when working on specific features.

RunApexTestSuite

Runs all tests in a test suite defined in your org.

sfp apextests trigger -o dev-org -l RunApexTestSuite \
  --apextestsuite QuickTests

Useful for running pre-defined test groups or smoke test suites.

RunLocalTests

Runs all tests in your org except those from managed packages. This is the default when -l is omitted, but not the recommended pattern in sfp.

sfp apextests trigger -o dev-org -l RunLocalTests

Note: While this is the Salesforce default, sfp recommends package-level or domain-level testing for better isolation and faster feedback. Use this only when you specifically need to run all org tests together, such as for compliance requirements or full org validation.

RunAllTestsInOrg

Runs all tests in your org, including managed packages. Rarely used due to long execution time.

sfp apextests trigger -o dev-org -l RunAllTestsInOrg

Use only for complete org validation scenarios.

Code Coverage Validation

Individual Class Coverage

Validates that each Apex class in the package meets the minimum coverage threshold. Every class must meet or exceed the specified percentage.

sfp apextests trigger -o dev-org -l RunAllTestsInPackage \
  -n my-package \
  -c \
  -p 80

Coverage threshold:

Default: 75%
Raised with the -p flag. Values below 75 are ignored — 75 is the floor
Applied per class, not as an average

Output includes:

List of all classes with their coverage percentages
Classes that meet the threshold
Classes that fail to meet the threshold
Overall package coverage percentage

Package Coverage

Validates that the overall package coverage meets the minimum threshold. The average coverage across all classes must meet or exceed the specified percentage.

sfp apextests trigger -o dev-org -l RunAllTestsInPackage \
  -n my-package \
  --validatepackagecoverage \
  -p 75

Coverage calculation:

Aggregates coverage across all classes in package
Calculated as: (total covered lines / total lines) * 100
Only classes with Apex code count toward coverage

Package-average validation applies to unlocked packages. For a source package, --validatepackagecoverage falls back to per-class validation, the same as -c.

Both coverage flags are accepted only with RunAllTestsInPackage. Passing them with any other test level, including RunAllTestsInDomain, fails the command.

Coverage vs No Coverage

Running tests without coverage flags still executes tests but doesn't fetch or validate coverage data:

# Run tests without coverage data
sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package

# Run tests with coverage fetching and validation
sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package -c

Note: Fetching coverage data adds time to test execution, so only use it when needed.

Output Formats

Note: The dashboard output format is a new feature introduced in the November 2025 release.

Raw Format (Default)

Standard Salesforce API output with JUnit XML and JSON results. This is the default format.

sfp apextests trigger -o dev-org -l RunLocalTests

Generates:

.testresults/test-result-<testRunId>.json - Raw Salesforce test results
.testresults/test-result-<testRunId>-junit.xml - JUnit XML format
.testresults/test-result-<testRunId>-coverage.json - Coverage data (only when coverage was fetched)
.sfpowerscripts/testresults.md - Markdown summary

Dashboard Format

Available in: November 2025 release and later

Structured JSON format optimized for dashboards, metrics systems, and reporting tools. Unlike the raw Salesforce API output, the dashboard format provides enriched, pre-processed data that's ready for consumption by external systems.

# Generate dashboard format
sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package \
  --outputformat dashboard \
  --environment dev

Generates all raw format files plus:

.testresults/<testRunId>/result.json - Structured test results
.testresults/<testRunId>/testresults.md - Enhanced markdown summary

Dashboard JSON Schema

The result.json file contains a comprehensive test execution report:

{
  "environment": "dev",
  "timestamp": "2025-11-24T10:30:00.000Z",
  "duration": 125000,
  "testExecutionTime": 120000,
  "commandTime": 115000,
  "repository": "https://github.com/myorg/myrepo",
  "commitSha": "abc123def",
  "branch": "main",

  "summary": {
    "totalTests": 150,
    "passed": 145,
    "failed": 5,
    "skipped": 0,
    "passingRate": 96.67,
    "overallCoverage": 82.5,
    "coveredLines": 8250,
    "totalLines": 10000,
    "outcome": "Failed"
  },

  "coverage": {
    "overallCoverage": 82.5,
    "totalLines": 10000,
    "coveredLines": 8250,
    "classes": [
      {
        "name": "AccountService",
        "id": "01p...",
        "coverage": 95.5,
        "totalLines": 200,
        "coveredLines": 191,
        "status": "pass"
      }
    ],
    "uncoveredClasses": ["LegacyHelper"],
    "belowThreshold": [
      {
        "name": "OldProcessor",
        "coverage": 65.0,
        "threshold": 75
      }
    ]
  },

  "testCases": [
    {
      "id": "07M...",
      "name": "AccountService.testCreateAccount",
      "className": "AccountService",
      "methodName": "testCreateAccount",
      "time": 250,
      "status": "passed"
    }
  ],

  "topFailingTests": [
    {
      "name": "ContactTest.testValidation",
      "className": "ContactTest",
      "methodName": "testValidation",
      "failureMessage": "System.AssertException: Expected 5, but got 3"
    }
  ],

  "metadata": {
    "testRunId": "707...",
    "orgId": "00D...",
    "username": "dev@example.com",
    "package": "sales-core",
    "testLevel": "RunAllTestsInPackage"
  }
}

How Dashboard Output is Used

For Metrics and Observability:

# Run tests and extract metrics
sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package \
  --outputformat dashboard --json > results.json

# Extract key metrics
PASSING_RATE=$(jq -r '.result.summary.passingRate' results.json)
COVERAGE=$(jq -r '.result.summary.overallCoverage' results.json)

# Push to your metrics backend
TEST_RUN_ID=$(jq -r '.result.metadata.testRunId' results.json)
curl -X POST https://metrics.example.com/api/tests \
  -d @.testresults/$TEST_RUN_ID/result.json

For Test History Tracking:

Each run writes to its own .testresults/<testRunId>/ directory, so results accumulate rather than overwrite:

# Track coverage trends across runs
jq -r '.coverage.belowThreshold[] | "\(.name): \(.coverage)%"' \
  .testresults/$TEST_RUN_ID/result.json

Dashboard vs Raw Format

Feature

Raw Format

Dashboard Format

Output

Salesforce API response

Processed, enriched data

Structure

Flat, verbose

Hierarchical, organized

File Location

.testresults/ root

.testresults/<testRunId>/

Coverage

Separate file

Integrated in JSON

Metadata

Limited

Environment, repo, commit

Use Case

Salesforce tooling

External systems, dashboards

Exit on Failure

Yes (exit code 1)

No (exit code 0)

--outputformat both generates both sets of files but keeps the raw format's exit behaviour — it still exits 1 when tests fail.

Non-Blocking Dashboard Mode

In dashboard mode, test failures don't cause the command to exit with error code 1, allowing you to collect test results even when tests fail:

# Command succeeds even if tests fail
sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package \
  --outputformat dashboard

echo $?  # Always 0 in dashboard mode

This is useful for:

Collecting metrics regardless of test outcome
Generating reports without blocking pipelines
Archiving test history across passing and failing runs
Trend analysis and test reliability tracking

Both Format

Available in: November 2025 release and later

Generates both raw and dashboard formats in a single execution.

sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package \
  --outputformat both \
  --environment ci

When to use:

Maintaining compatibility while adopting dashboard format
Comprehensive test result archiving

Output Directory Structure

After running tests, sfp creates a .testresults directory:

.testresults/
├── test-result-<testRunId>-junit.xml      # JUnit XML format
├── test-result-<testRunId>.json           # Raw Salesforce test results
├── test-result-<testRunId>-coverage.json  # Code coverage data
└── <testRunId>/                           # Dashboard format directory
    ├── result.json                        # Structured test results
    └── testresults.md                     # Enhanced markdown summary

The markdown summary for the raw format is written to .sfpowerscripts/testresults.md, outside this directory.

Troubleshooting

Tests Timeout

Control how long the command waits for tests to complete:

# Wait up to 120 minutes
sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package -w 120

# Wait indefinitely (no timeout) - useful for very large test suites
sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package -w 0

# Omitting the flag also waits indefinitely
sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package

Wait time behavior:

Omit -w flag: Wait indefinitely (no timeout)
-w 0: Wait indefinitely (no timeout)
-w <minutes>: Wait up to specified minutes before timing out

For most scenarios, omitting the wait time or using 0 is recommended to avoid premature timeouts on large test suites.

Parallel vs Serial Execution

Tests run with RunAllTestsInPackage always execute serially, so classes that interfere with each other in parallel are not a concern at that test level. The other test levels run in parallel and there is no flag to force serial execution.

Coverage Validation Failures

See which classes failed coverage requirements:

sfp apextests trigger -o dev-org -l RunAllTestsInPackage \
  -n my-package -c --loglevel debug

The debug output shows:

Each class and its coverage percentage
Which classes passed/failed threshold
Overall package coverage

Tests Not Found

If no tests are executed:

Check that test classes exist in the package:
```
# Verify package contents
sfp build -v mydevhub -p my-package --loglevel debug
```
Ensure test classes follow naming conventions:
- Class name ends with Test
- Methods are annotated with @isTest
Verify test classes are in the correct package directory

Mixed Results with Retries

sfp retries failed tests serially when a failure is a row-lock error (UNABLE_TO_LOCK_ROW), which is the failure mode parallel execution produces. Ordinary assertion failures are not retried.

First run: Tests execute in parallel
If a row-lock failure occurs: the failed tests are re-run serially
Final results: Combines both runs, removes duplicates

Additional Options

Wait Time Control

Control test execution timeout behavior:

# Wait indefinitely (recommended for large test suites)
sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package -w 0

# Wait up to 120 minutes
sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package -w 120

# Omitting -w also waits indefinitely
sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package

Options:

Omit -w: Wait indefinitely
-w 0: Wait indefinitely
-w <minutes>: Wait specified minutes before timeout

Specifying API Version

Override the API version for the test run:

sfp apextests trigger -o dev-org -l RunAllTestsInPackage -n my-package --api-version 60.0

--apiversion is accepted as an alias.

Git Metadata

Include the repository URL in test results:

sfp apextests trigger -o dev-org -l RunLocalTests \
  --repourl https://github.com/myorg/myrepo

The commit is read from the working tree, so it does not have to be supplied.

This metadata appears in:

Dashboard JSON output
Markdown summaries
Test reports

Custom Environment Name

Specify environment name for dashboard format:

sfp apextests trigger -o dev-org -l RunLocalTests \
  --outputformat dashboard \
  --environment "dev-feature-branch"

Defaults to the target org alias if not specified.

Last updated 1 month ago

Was this helpful?