Extending Nimbus with stubs

The solution: user stubs

A stub is a user-provided implementation of any class Nimbus doesn't natively support. Instead of blocking on missing code, you implement just enough for your tests to run - then commit it to git so your team shares the same behavior.

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>();
    }
}