Nimbus - Local Apex Test Runner
Run Salesforce Apex tests locally without deploying to an org. Nimbus provides a full Apex execution environment with an embedded PostgreSQL database, giving you instant feedback on test results, coverage, and diagnostics — all from your editor.
Getting Started
Prerequisites
- Nimbus CLI installed and on your
PATH — if it's missing, the extension will offer to install it automatically
- A Salesforce project with
sfdx-project.json
First Run
- Open your Salesforce project folder in VSCode
- The extension activates automatically when it detects
sfdx-project.json or .cls files
- Check the status bar — you should see $(check) Nimbus when the daemon is connected
- Open any
@isTest class — you'll see Run Test and Debug Test buttons above each test method
- Click
Run Test to run your first test
If the status bar shows $(circle-slash) Nimbus, the daemon failed to start. Run Nimbus: Restart Daemon from the command palette (Cmd+Shift+P) and check the Nimbus output channel for errors.
Running Tests
Every @isTest class shows CodeLens actions directly in the editor:
- On the class line:
Run All Tests runs every test method in that class, Validate checks syntax
- On each test method:
Run Test runs that single method, Debug Test starts a debug session, View Trace opens the trace viewer
Non-test classes also get CodeLens:
- On the class line:
Validate checks syntax
- On each public method:
Run executes the method, Debug starts a debug session
From the Command Palette
| Command |
What it does |
Nimbus: Run All Tests |
Runs every @isTest class in the project |
Nimbus: Run Tests in Current File |
Runs all tests in the active .cls file |
Nimbus: Run Test Class |
Runs a specific test class by name |
Nimbus: Run Test Method |
Runs a specific test method |
Nimbus: Cancel Test Run |
Stops the currently running tests |
From the Test Explorer
Nimbus integrates with VSCode's native Test Explorer sidebar. Tests are discovered automatically when the daemon connects. You can run, debug, or view results from there.
Understanding Results
After a test run:
- A notification shows pass/fail summary with total time
- The Nimbus output channel shows detailed results grouped by class
- Inline decorations appear in the editor on executed lines (pass/fail indicators)
- The status bar shows progress during the run (
3/10 tests...)
Debugging
Nimbus supports the full VSCode debug experience for Apex code.
How to Debug a Test
- Open a test class
- Click
Debug Test above any @isTest method (or use Nimbus: Debug Test Method)
- Set breakpoints by clicking the gutter (left margin) on any line
- The debugger pauses at breakpoints — use the debug toolbar to:
- Step Over (
F10) — execute the next line
- Step In (
F11) — enter a method call
- Step Out (
Shift+F11) — return to the caller
- Continue (
F5) — resume until the next breakpoint
- Inspect variables in the Variables panel in the Debug sidebar
- View the call stack in the Call Stack panel
How to Debug Any Method
Not limited to tests — you can debug any public method:
- Open any
.cls file (non-test class)
- Click
Debug above any method
- If the method has parameters, Nimbus prompts you to enter values
- Breakpoints and stepping work the same as test debugging
Launch Configurations
You can also configure debug targets in .vscode/launch.json:
{
"type": "nimbus-apex",
"request": "launch",
"name": "Debug My Test",
"test": "MyTestClass.myTestMethod",
"stopOnEntry": false
}
Coverage
Enabling Coverage
Set nimbus.coverage.enabled to true in settings, or pass the --coverage flag from the CLI. After a test run with coverage enabled, three things appear:
Gutter Icons
Colored icons appear in the editor gutter (left margin) next to each line:
- Green circle — line was executed during the test
- Red circle — line was not executed
- Yellow circle — branch partially covered (e.g., only the
true path of an if was taken)
Toggle gutter icons on/off with the nimbus.coverage.showGutterIcons setting.
Method Coverage Annotations
After each method signature, an inline annotation shows the coverage percentage:
public static void processRecords(List<Account> accounts) // 75% (3/4 lines)
Coverage Command
Run Nimbus: Show Coverage to view the full coverage report in the output channel.
Trace Viewer
The trace viewer shows a detailed execution trace of every method call, branch decision, and variable assignment during a test run.
How to Open
- From CodeLens: Click
View Trace above any test method after running it
- From the command palette:
Nimbus: View Execution Trace
What You See
The trace viewer opens as a side panel with three tabs:
- Call Tree — An indented tree of all method invocations. Each node shows the method name, duration, and status (pass/fail). Click a node to select it.
- Timeline — A horizontal waterfall chart showing execution over time. Wider bars = slower methods. Useful for spotting bottlenecks.
- Log — A filterable list of all trace events with timestamps. Use the search box at the top to filter by method name or event type.
Variable Inspector
When you select a span in any view, the right sidebar shows:
- Variables — all local variables captured at that point
- Debug Output — any
System.debug() output from that span
- Attributes — span metadata like source file, line number, and status
Click the Nimbus icon in the activity bar (left sidebar) to open three dedicated views.
Test History
Shows a list of past test runs, sorted newest first.
How to use:
- Click the Nimbus icon in the activity bar
- The Test History view shows past runs with pass/fail icons and summary (e.g.,
3/3 passed (250ms))
- Expand a run to see results grouped by class, then by method
- Click a method to see its duration and error message (if failed)
- Use the refresh button in the view title to reload
Additional actions from the view title bar:
- Show History Trends — opens a chart showing pass rate over the last 30 days, plus a table of flaky tests (tests that flip between pass and fail)
Context menu on runs:
- Compare With... — select two runs to see a side-by-side diff (see Test Diff below)
Governor Limits
Shows Salesforce governor limit consumption per test method. Updated automatically after each test run.
How to use:
- Run some tests
- Open the Governor Limits view in the Nimbus sidebar
- Each test method is listed with its highest limit usage percentage
- Expand a method to see individual limits:
- SOQL Queries, SOQL Query Rows, DML Statements, DML Rows, CPU Time, Heap Size, HTTP Callouts, Future Calls, Queueable Jobs, Email Invocations
- Limits are color-coded:
- Green $(check) — under 50% used
- Yellow $(warning) — 50-80% used
- Red $(error) — over 80% used (close to hitting the limit)
Schema Explorer
Browse the local PostgreSQL database schema that Nimbus uses to store SObject data.
How to use:
- Open the Schema Explorer view in the Nimbus sidebar
- Tables are listed with row counts and column counts
- Expand a table to see:
- Columns — name, data type, and constraints (PK, nullable, FK)
- Outgoing references (
→) — foreign keys from this table to others
- Incoming references (
←) — foreign keys from other tables pointing here
- Use the refresh button to reload after schema changes (e.g., after importing new metadata)
Watch Mode
Automatically re-run tests when Apex files change.
How to Use
- Click the $(eye-closed) Watch: off button in the status bar, or run
Nimbus: Toggle Watch Mode from the command palette
- If your project has multiple package directories (in
sfdx-project.json), a picker appears:
- Choose All Packages to watch everything
- Choose a specific package (e.g.,
force-app) to only watch that directory
- The status bar updates to show
$(eye) Watch: force-app (or Watch: all)
- When you save any
.cls or .trigger file, tests re-run automatically
- After a watch-triggered run, the status bar briefly shows the result (e.g.,
Watch: all passed or Watch: 2 failed)
- Click the watch button again to disable
After a test run, method execution times appear as inline annotations:
public static void processRecords(List<Account> accounts) // ⏱ 45ms
For methods called multiple times: ⏱ 45ms avg (3 calls)
How it works:
- Timings come from trace data when available (most accurate), or from test progress events as a fallback
- Annotations appear on method signatures in the active editor
- Toggle with the
nimbus.performance.showInlineTimings setting
Test Diff (Compare Runs)
Compare two test runs side by side to see what changed.
How to Use
- Run
Nimbus: Compare Test Runs from the command palette
- A picker shows your last 20 test runs — select Run A
- Select Run B from the remaining runs
- A side panel opens showing:
- Summary — pass/fail counts and dates for both runs
- Flipped Tests (highlighted) — tests that changed from pass→fail or fail→pass
- All Tests — full comparison table with status, duration changes (arrows show faster/slower), and change type (Flipped, Same, New, Removed)
You can also right-click a run in the Test History sidebar and select Compare With....
Diagnostics & Validation
Nimbus validates Apex syntax in real time and reports errors in the Problems panel.
- On save: If
nimbus.validateOnSave is enabled (default: true), every .cls and .trigger file is validated when you save
- Manual: Run
Nimbus: Validate Current File to check the active file
- Quick fixes: Some parse errors offer code actions (lightbulb icon) with suggested fixes — e.g., adding missing semicolons
Errors appear as red squiggles in the editor and in the Problems panel (Cmd+Shift+M).
Execute Anonymous Apex
Run arbitrary Apex code without creating a class or test.
How to Use
- Open any
.cls file or create a new untitled file
- Write or select some Apex code
- Run
Nimbus: Execute Anonymous Apex from the command palette
- If you have text selected, only the selection runs. Otherwise the entire file runs.
- Output appears in the Nimbus output channel —
System.debug() statements show as DEBUG: lines
Run Any Method
Not just tests — you can run any public method directly from the editor.
How to Use
- Open any
.cls file (non-test class)
- Click the
Run CodeLens above a method
- If the method has parameters, input boxes appear for each parameter (with type hints)
- The method executes and results appear as:
- An inline decoration next to the method showing return value and execution time
- A notification if the method failed with an error message
When tests fail because of missing SObjects, fields, or other metadata not in your local project, Nimbus detects what's missing.
How it Works
- Run tests — if metadata is missing, a warning notification appears: "3 missing metadata items detected"
- Choose one of:
- Fetch & Re-run — Nimbus retrieves the missing metadata from your connected Salesforce org and automatically re-runs the failed tests
- Show Details — Opens the output channel showing exactly which metadata items are missing and the
sf CLI commands to retrieve them manually
- Dismiss — Ignore for now
- You can also run
Nimbus: Fetch Missing Metadata & Re-run from the command palette at any time
All Commands
| Command |
Description |
Nimbus: Run All Tests |
Run every test in the project |
Nimbus: Run Tests in Current File |
Run tests in the active editor file |
Nimbus: Run Test Class |
Run all tests in a specific class |
Nimbus: Run Test Method |
Run a specific test method |
Nimbus: Debug Test Method |
Debug a test with breakpoints |
Nimbus: Cancel Test Run |
Stop the current test execution |
Nimbus: Validate Current File |
Check Apex syntax, report errors |
Nimbus: Execute Anonymous Apex |
Run selected/all Apex code |
Nimbus: Show Coverage |
Display full coverage report |
Nimbus: Toggle Watch Mode |
Enable/disable auto-run on save |
Nimbus: Show Status |
Show daemon version, uptime, DB status |
Nimbus: Restart Daemon |
Restart the background daemon |
Nimbus: View Execution Trace |
Open trace viewer for a test |
Nimbus: Show Test History |
Show history in output channel |
Nimbus: Show History Trends |
Open pass rate chart + flaky test table |
Nimbus: Compare Test Runs |
Diff two historical runs side by side |
Nimbus: Refresh Schema |
Reload schema explorer |
Nimbus: Fetch Missing Metadata & Re-run |
Retrieve missing metadata from org |
Settings
| Setting |
Type |
Default |
Description |
nimbus.binaryPath |
string |
nimbus |
Path to the nimbus binary |
nimbus.parallel |
number |
4 |
Number of parallel test workers |
nimbus.coverage.enabled |
boolean |
false |
Collect coverage data on test runs |
nimbus.coverage.showGutterIcons |
boolean |
true |
Show green/red/yellow coverage icons in the gutter |
nimbus.validateOnSave |
boolean |
true |
Validate Apex syntax on save |
nimbus.autoRun.onOpen |
boolean |
false |
Auto-run tests when a test file is opened |
nimbus.autoRun.onSave |
boolean |
false |
Auto-run tests when a test file is saved |
nimbus.performance.showInlineTimings |
boolean |
true |
Show method execution time annotations |
License
Proprietary — see LICENSE for terms. Free tier available; Pro features require a paid license.
