Karma and Chrome: Configuring retry behavior for browser disconnects

There is currently no configuration flag in stable Karma releases to define a specific number of fresh browser instance launches (retries) after a terminal disconnect. The browserRetry flag proposed by the community has not been merged into the main stable branch.

Managing Disconnects via Configuration

While you cannot configure a "retry count" for launching new browser processes, you can tune how Karma handles the loss of connection to an existing instance. These settings are applied in your karma.conf.js:

• browserDisconnectTolerance: This defines the number of times a browser is allowed to disconnect and reconnect before Karma fails the entire run. If a browser disconnects but reconnects within the timeout period, this counter is used.
• browserDisconnectTimeout: The duration (in milliseconds) Karma waits for a browser to reconnect before it considers the browser permanently gone and attempts to capture the failure or restart.
• browserNoActivityTimeout: The time Karma waits for a response from the browser before assuming it has hung.

Behavior During autoWatch Cycles

When autoWatch is enabled, Karma maintains a persistent connection to push updated assets. If a browser disconnects during this cycle, the behavior often differs from a single-run execution:

• Immediate Failure: Because the runner expects a stable socket to synchronize the state of the application under test, a disconnect during a watch cycle frequently triggers an immediate error rather than a graceful retry.
• Browser Consistency: This behavior is generally consistent across browsers that utilize the WebSocket/Socket.io transport (including Chrome). However, if a browser fails to initialize the socket entirely, the browserDisconnectTolerance is typically ignored because a stable connection was never established.

Practical Workarounds

Since native retry limits for browser launches are unavailable, consider these alternatives for CI stability:

1. CI Wrapper: Wrap the Karma CLI command in a shell script or CI pipeline step (e.g., GitHub Actions or GitLab CI) that retries the entire test command once or twice upon a non-zero exit code.
2. Increase Tolerance: Raise browserDisconnectTolerance to allow for transient network hiccups, though this may mask memory leaks.

Verification

To verify your current settings, check your configuration and simulate a crash:

# Check installed version
npm list karma

# In karma.conf.js
module.exports = function(config) {
  config.set({
    browserDisconnectTolerance: 3,
    browserDisconnectTimeout: 10000,
    // ...
  });
};

Missing Diagnostic Detail: Are you running Chrome in headless mode within a Docker container? Resource constraints in containerized environments often cause the "hard" crashes that bypass browserDisconnectTolerance.