Karma singleRun flag: variable process termination across plugin ecosystems

Short answer

No — singleRun: true does not guarantee that the process exits before plugin exit/cleanup hooks run, and it does not override plugin behavior. It tells Karma to execute one test cycle and then shut down, but shutdown still goes through Karma's normal teardown sequence. If a plugin leaves asynchronous work pending, the Node process can linger or hang even with singleRun set. The flag controls when teardown starts, not whether teardown completes.

Answering your three questions

1. Does singleRun exit before plugin onExit hooks?

No. Karma's plugin system is dependency-injection based, and reporters, launchers, and custom factories participate in the normal startup and shutdown sequence. Reporter completion and plugin cleanup run as part of that teardown; Karma exits only after its internal shutdown finishes. There is no documented ordering guarantee that process exit precedes plugin hooks — in practice, the opposite is true: Karma waits for its own teardown, and a plugin that never finishes blocks exit.

2. What happens when a plugin returns a promise from initialization?

Karma will generally wait for its own server and browser teardown, but the more common failure mode is different: a plugin that holds open handles — timers, sockets, intercepted console streams, unresolved promises — keeps the Node event loop alive after Karma's teardown completes. In that case the test cycle finishes, results are reported, and the process simply never exits. The hang is in the plugin, not in singleRun itself.

3. Can watch mode silently override the flag?

singleRun and autoWatch are independent flags. singleRun performs one cycle and ignores watch restarts, but explicitly setting autoWatch: true alongside it has produced version-dependent behavior historically — don't combine them. The genuinely silent scenario is configuration precedence: CLI flags override config values, and a base config merged or mutated by another config file can change singleRun without it being obvious from the file you're reading.

How to verify for your setup

Exact ordering and forced-exit behavior vary across Karma versions, so verify against the version pinned in your project rather than assuming current behavior:

1. Run karma start --single-run with a minimal config (no custom plugins) and confirm the process exits with code 0.
2. Re-add plugins one at a time to isolate which one delays termination.
3. Confirm the resolved configuration with karma start --log-level debug, or log config.singleRun and config.autoWatch from inside a plugin, to rule out a silent override.
4. If the process hangs after results print, attach why-is-node-running (or use node --trace-exit) to identify the open handles the plugin left behind.

Caveats

Karma was officially deprecated in 2023, so unspecified edge cases in the plugin API are unlikely to be clarified upstream — treat any undocumented ordering as implementation detail, not contract. If deterministic CI termination matters, a pragmatic safeguard is a CI-level timeout on the test step, plus fixing or replacing any plugin shown to hold the event loop open. For new projects, migrating to a maintained runner avoids this class of ambiguity entirely.