Record the package once, then test without the org

What nimbus record does

nimbus record is two passes in one. First it reads the package's real surface straight out of the org: every global class and signature, every constant, plus the labels, fields and objects your code touches. Then it runs your tests with the package's calls forwarded live to the org and writes down what came back, one cassette per test method.

nimbus record -o my-org                    # the whole suite
nimbus record -o my-org DonationRollupTest # one class
nimbus record -o my-org --namespaces Nebula,npe01
nimbus record -o my-org --data             # settings + metadata rows too

The package stays a black box, but it now runs on your machine.

Recording writes stubs

What nimbus record writes to disk is a stub, a local implementation of a class Nimbus cannot otherwise see. Recording produces them for installed packages; you can also write them by hand for anything else. Three categories of code need them:

public class AccountService {
    public static void logAccountCreation(Account acc) {
        // Nebula Logger is a managed package - source is hidden
        Nebula.Logger.info('Created account: ' + acc.Name);
        Nebula.Logger.saveLog();
        // ← Can't execute - Nimbus can't see the code
    }
}

What gets recorded

The first half of nimbus record is available on its own as nimbus stub pull: the package's real surface and real values, with no test run and nothing executed in the org:

nimbus stub pull --org my-org --namespaces Nebula,npe01

Wrote stubs/labels/npe01.labels-meta.xml (14 labels: 14 new, 0 updated)
Wrote stubs/objects/Contact/fields/npe01__Private__c.field-meta.xml
Wrote stubs/Nebula/Logger.cls
Wrote stubs/Nebula/LogEntryEventBuilder.cls
Wrote stubs/npe4/Relationships_INST.cls
...
108 labels in 5 files, 162 fields, 2 objects, 17 classes (1 recorded constant), 0 skipped.

• Classes: the Tooling API's SymbolTable exposes a package's exact global surface: every method overload, constructor, property, inner class, and enum, with the org's own signatures. Builder methods hand back constructed objects, so Nebula.Logger.info('x').addTag('y') chains work instead of NPE'ing.
• Constant values: global constants have no value in a SymbolTable, so their actual values are read by running one short anonymous Apex script per class against the org.
• Labels, fields, objects: custom labels from the only API that can read another package's labels, plus field and object schema for everything your project references.
• Data, opt-in (--data): custom-setting rows become seed lines in a fenced block of nimbus.properties; custom-metadata records become ordinary stubs/customMetadata/ files. getInstance() and SOQL then return what the org returns.

Re-running is safe: anything your project defines, and anything already under stubs/, is left alone. Recorded stubs are plain files. Hand-edit them and commit them to git. See the full flag reference.

Stubs generated from your code Pro

Writing stubs by hand means walking every reference to find which methods get called, with which arguments, returning what type. nimbus stub auto does that walk. It scans the project AST, finds every reference to a class Nimbus cannot resolve, infers the surface from how your code uses it, and writes one .cls per class.

Workflow

# Preview without writing — see what would be generated
nimbus stub auto --dry-run

# Generate (skips files that already exist)
nimbus stub auto

# Re-run after adding new code that exercises the package
nimbus stub auto --merge        # appends only new methods; keeps your edits
nimbus stub auto --force        # full rewrite (discards hand edits)

Or generate stubs after a successful test run:

nimbus test --write-stubs
nimbus test --write-stubs --write-stubs-merge

What it captures

• Method names and arities exactly as your code calls them
• Argument types from declared local variables (String s = ...; X.foo(s) → foo(String arg0))
• Return types from surrounding context: assignment LHS, return statements, casts, !/&&/|| (Boolean), 'msg: ' + X.bar() (String)
• Generic types preserved: List<MyType> rows = X.fetch() → fetch() returns List<MyType>
• Constructors with their arities

What it does not capture

• Parameter names: call sites do not carry them. Expect arg0, arg1. The package's published surface is the source of truth if you care about names; hand-edit afterwards.
• Method bodies: generated stubs increment callCount and append to a calls list so tests can assert on invocation count, but the return value is a type-default (null, 0, false, ''). Hand-edit the body if you need richer behavior.

Dynamic dispatch

Apex supports a few runtime-resolved patterns the static walker cannot see, chiefly Type.forName('Pkg.X').newInstance() (used by fflib mocks, Force-DI, at4dx) and Database.query(buildAtRuntime). When you run nimbus test --write-stubs, the test pass surfaces these to the cross-run registry alongside the static scan: any class name passed to Type.forName at runtime that doesn't resolve becomes a type-only stub. Standalone nimbus stub auto only sees the static surface, since no tests run.

Type-only stubs (no methods, no fields) let Type.forName('Pkg.X').newInstance() succeed at test time instead of NPE'ing on the null return. Hand-edit the surface, or call the class statically once so the next --merge picks up its methods.

Detecting and registering namespaces

Auto-stub needs to know which chain roots are managed-package namespaces and which are plain class names; otherwise it cannot tell Pkg.Logger.info() apart from OuterClass.Inner.method(). The signal is nimbus.stubs.namespaces in your nimbus.properties; without an entry there, auto-stub falls back to a flat type-only shell (stubs/Pkg.cls) that doesn't match the runtime resolution path.

The walker detects this and tells you. After every run, any chain root that looks namespace-shaped (used as Root.Class.something with Root unresolved) is surfaced as a suggestion with a copy-pasteable config line:

→ 1 chain root looks like a managed-package namespace
    Hoplog               (6 chained reference sites)

  Adding it to nimbus.stubs.namespaces lets nimbus stub auto
  generate the correct namespaced layout (stubs/<Pkg>/<Class>.cls)
  instead of a flat type-only shell.

    nimbus.stubs.namespaces=Hoplog

  Or re-run with --update-config to write the line and regenerate.

Pass --update-config (or --write-stubs-update-config for the test-loop variant) to do both in one step. The flag merges the new entries into nimbus.properties, then re-walks with the augmented namespace set so the stubs land in the right shape:

nimbus stub auto --update-config
# ✓ Wrote 1 new stub
#     stubs/Hoplog/Logger.cls
# ✓ Registered 1 namespace(s) in nimbus.properties
#     Hoplog               (6 chained reference sites)

Existing config lines and comments are preserved; only the nimbus.stubs.namespaces= line is touched (or appended if missing). Safe to combine with --merge and --dry-run.

Iterating with --merge

By default an existing stub is left alone, so hand edits are safe, but new usage in the project does not reach the stub. --merge parses the existing file, finds which methods, fields and constructors are already declared, and appends only the new ones. Existing method bodies, parameter names and custom additions are preserved.

# Day 1: generate from scratch
nimbus stub auto

# You hand-edit the stub: real return value, meaningful arg names

# Day 30: project added Pkg.X.newMethod() in three new tests
nimbus stub auto --merge
# → appends newMethod, leaves your edits intact

Idempotent: running --merge twice in a row is a no-op when nothing's changed.

Two equivalent layouts

Nimbus accepts two equivalent on-disk layouts for namespaced stubs. nimbus stub auto writes one file per class:

stubs/Nebula/Logger.cls            # public class Logger { ... }
stubs/Nebula/LogEntryEventBuilder.cls

The hand-written convention bundles everything into a single file with the namespace as the outer class:

stubs/Nebula/Nebula.cls            # public class Nebula { class Logger { ... } class LogEntryEventBuilder { ... } }

Both resolve Nebula.Logger the same way at runtime: the per-class layout uses the stub loader's alias registration, the nested layout uses Apex's own inner-class semantics. --merge works against either.

Running without stubs

Stubs are not required for a first run. When Nimbus encounters a class it does not know (a managed package, an unsupported API), it logs a warning, returns null and continues. A test fails only if it asserts on the return value of the missing class.

[warn] nebula.logger.Logger not found - returning null (add a stub to control behavior)
[warn] fsl.FieldServiceAPI not found - returning null

The workflow is:

1. Run nimbus test and see which tests pass and which fail
2. For failing tests, check if the failure is a missing dependency
3. Add a stub only for classes whose return values you need to control

Most logging and telemetry calls (Nebula Logger, for example) need no stub, because nothing asserts on them.

Writing effective stubs

public class Nebula {
    public class Logger {
        public static LogEntryEventBuilder info(String msg) {
            System.debug(msg);
            return new LogEntryEventBuilder();
        }
        public static void saveLog() { }
    }
    public class LogEntryEventBuilder { }
}

// Match the real Nebula signature exactly
public static LogEntryEventBuilder info(String message)

// Not:
public static void log(String msg)

public class DataService {
    public static List<Record> getRecords(String query) {
        // Stub: return empty list for testing
        return new List<Record>();
    }
}