Record the package. Keep it forever.

One command. Then never again.

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 is still a black box. It just runs on your machine now.

Recording is one case of a bigger idea

What nimbus record writes to disk is a stub — a local implementation of a class Nimbus can't otherwise see. Recording produces them automatically 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 freely and commit them to git. See the full flag reference.

Auto-generate stubs from your code Pro

Writing stubs by hand is straightforward, but tedious — you have to walk every reference to figure out which methods get called, with which arguments, returning what type. nimbus stub auto does that walk for you. It scans the project AST, finds every reference to a class Nimbus can't resolve, infers the surface from how your code actually 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 fold it into the test loop — generate stubs after a successful 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 doesn't

• Parameter names — call sites don't 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 can't 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 vs. plain class names — otherwise it can't 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 shot — 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

The default behavior is conservative: if a stub already exists, it's left alone — your hand edits are safe. But that means new project usage doesn't trickle into the stub. --merge is the answer: it parses the existing file, identifies which methods/fields/ctors are already declared, and appends only the new ones. Existing method bodies, parameter names, even custom additions you wrote — all 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 layouts, both work

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 automatic alias registration; the nested layout uses Apex's own inner-class semantics. Pick whichever you prefer; --merge works against either.

Zero-stub start

You don't need stubs to get your first green run. When Nimbus encounters a class it doesn't know - a managed package, an unsupported API, anything - it degrades gracefully: logs a warning, returns null, and continues. Tests only fail if they assert on the return value of that missing class.

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

This means your workflow is:

1. Run nimbus test - 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, etc.) require no stub at all - you don't assert 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>();
    }
}