Debugging Karma Tests

Karma's debug.html Page

Karma automatically generates a debug page at /debug.html on its local server, in addition to the automated capture page it uses for normal runs. Opening this page in a real (non-headless) browser while Karma runs in watch mode gives you full access to real devtools against your actual test files.

# With Karma running in watch mode (autoWatch: true, singleRun: false)
open http://localhost:9876/debug.html

This works even if your configured browsers list only includes headless browsers — the debug page is served independently and can be opened manually in any browser.

The Debugging Toolkit at a Glance

1. Read the terminal failure output carefully (assertion + stack trace)
2. Reproduce with a single spec: karma start --single-run
3. Switch to a visible browser (Chrome instead of ChromeHeadless)
4. Open http://localhost:9876/debug.html for real devtools access
5. Add debugger; statements or console.log() (with captureConsole)
6. Check source maps if stack traces point at bundled/compiled code

• Start with the cheapest technique (reading output carefully) before reaching for heavier tools.
• Switching from headless to a visible browser is often the single fastest way to actually see what's happening.
• debugger; statements pause execution exactly like they would in any other browser debugging session.
• Source map issues (covered in a later lesson) are a common, underestimated cause of confusing stack traces.

Debugging Strategy Cheat Sheet

Match the symptom to the right technique.

Isolating a Single Failing Spec

Before deep debugging, narrow the problem to the smallest reproducible case. Jasmine's fit() (focused it) and fdescribe() (focused describe) run only the marked spec(s), skipping everything else in the suite temporarily.

describe('UserService', function() {
  fit('handles the specific failing case', function() {
    // only this spec runs while fit() is used
  });

  it('this spec is skipped for now', function() {
    // ...
  });
});

Always remove fit()/fdescribe() before committing — leaving them in accidentally disables the rest of the suite.

A General Debugging Mindset for Karma

Because Karma spans configuration, browser behavior, and application code, it helps to explicitly ask which layer a failure belongs to before diving in: is this a real application bug, a test setup mistake, a Karma configuration issue, or a browser-specific quirk?

• Reproduce the same failure with Chrome and ChromeHeadless — does it differ?
• Reproduce with a second browser (like Firefox) — is it browser-specific?
• Check whether the failure survives running the spec completely alone, isolated from the rest of the suite.
• If it only fails in CI, suspect environment/timeout differences before suspecting the test itself.

Common Mistakes

• Jumping straight to breakpoints and devtools before carefully rereading the terminal's actual error message.
• Leaving fit()/fdescribe() in committed code, silently disabling the rest of a test suite.
• Assuming a CI-only failure is 'flakiness' without checking browser flags, timeouts, or environment differences first.
• Debugging in headless mode when switching to a visible browser would provide far more direct visibility.

Key Takeaways

• Karma's /debug.html page provides full devtools access to your test files in any real browser.
• fit()/fdescribe() isolate a single failing spec quickly, but must be removed before committing.
• Explicitly identifying which layer (app code, test setup, config, browser) a failure belongs to speeds up debugging.
• CI-only failures are often environment/timeout differences, not necessarily flaky tests.