How to run Apex tests locally

What you need

• An SFDX project — the same force-app/main/default layout you'd push to an org.
• macOS, Linux, or Windows. No JVM, no Docker, no Postgres install — the embedded database ships with the binary.
• 5 minutes.

Step 1 — Install Nimbus

One line, no admin required:

# macOS / Linux
curl -sSL https://testnimbus.dev/install.sh | bash

# Windows (PowerShell)
iwr -useb https://testnimbus.dev/install.ps1 | iex

Verify the install:

nimbus --version

Step 2 — Run the doctor (one-time sanity check)

nimbus doctor looks at your project, validates the layout, and lists anything it needs you to set up. On a clean SFDX project, it usually reports green and you skip the rest of this section.

cd path/to/your/sfdx-project
nimbus doctor

Step 3 — Run your tests

Same command structure as the Salesforce CLI, but local:

# Run everything
nimbus test "*"

# Run a specific test class
nimbus test "OrderServiceTest"

# Run a single method
nimbus test "OrderServiceTest.testDiscountApplies"

# Glob patterns
nimbus test "Order*Test.*"

Output mirrors what you'd expect from sf apex run test: pass/fail counts, failure messages, stack traces, code coverage. Failures point at the file and line.

Step 4 — Iterate with watch mode

nimbus watch re-runs affected tests on save. It tracks which classes each test exercises, so editing a single trigger only re-runs the tests that touch it.

nimbus watch

Watch mode is a Pro feature. The Free tier supports one-shot runs and the full Dev UI; watch is the loop-tightening upgrade.

What about CI?

Same binary, same project, JUnit XML and Cobertura XML output for whatever CI you use:

# .github/workflows/test.yml
name: Apex Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -sSL https://testnimbus.dev/install.sh | bash
      - run: nimbus test "*" --junit results.xml --coverage cobertura.xml
      - uses: actions/upload-artifact@v4
        with: { name: test-results, path: results.xml }

For a deeper walkthrough see Apex CI without a connected org.

Common gotchas

• Multi-currency org behaviour. Set nimbus.org.multi-currency=true in nimbus.properties so CurrencyType queries and per-record currency fields behave the way they do in production.
• Managed package types. If your code references a managed package, install stubs with nimbus stub add <namespace>. See Managed Packages.
• Org defaults. Custom settings need seeding. Add them in nimbus.properties with nimbus.seed.org-default.MySetting__c=... rather than relying on @testSetup boilerplate everywhere.