ScreenshotNeo

BlogHow-to

How to Fix Angular ChromeHeadless Unit Test Failures on Visual Studio Online

Fix Angular ChromeHeadless failures in Visual Studio Online with Karma settings, Azure Pipelines YAML, diagnostics, and CI reliability tips.

By the ScreenshotNeo team30 September 20266 min read

How to Fix Angular ChromeHeadless Unit Test Failures on Visual Studio Online

Angular unit tests commonly fail in Visual Studio Online (now Azure DevOps) when Karma starts a headed browser, stays in watch mode, or cannot find a Chrome binary. For a Karma-based Angular project, run:

ng test --no-watch --no-progress --browsers=ChromeHeadless

The --no-watch and --no-progress flags make the CI run execute once and exit cleanly. Microsoft’s Azure Pipelines guidance also pairs ChromeHeadless with Karma’s singleRun: true.

1. Confirm which Angular test runner you use

This fix applies to Angular projects that use Karma and Jasmine, which is common in older Angular CLI projects. Check angular.json, your test target, and karma.conf.js.

cat angular.json
ls karma.conf.js
npm ls karma karma-chrome-launcher jasmine-core

If your project uses the newer Angular unit-test builder with Vitest, ChromeHeadless settings do not apply. Angular documents a separate Karma-to-Vitest migration path; do not migrate just to mask a browser provisioning problem.

2. Make the local command CI-safe

Run the explicit one-shot command locally before changing the pipeline:

The CI path: install dependencies, launch ChromeHeadless, run Karma once, and exit with the test result.
The CI path: install dependencies, launch ChromeHeadless, run Karma once, and exit with the test result.
npm ci
ng test --no-watch --no-progress --browsers=ChromeHeadless

If this passes locally but fails in Visual Studio Online, the likely difference is the hosted agent’s browser installation, sandbox, display environment, or Node dependency cache.

3. Configure Karma for ChromeHeadless

In karma.conf.js, select the headless launcher and make Karma terminate after one run:

module.exports = function (config) {
  config.set({
    basePath: '',
    frameworks: ['jasmine', '@angular-devkit/build-angular'],
    plugins: [
      require('karma-jasmine'),
      require('karma-chrome-launcher'),
      require('karma-jasmine-html-reporter'),
      require('@angular-devkit/build-angular/plugins/karma')
    ],
    client: {
      clearContext: false
    },
    reporters: ['progress'],
    browsers: ['ChromeHeadless'],
    singleRun: true,
    restartOnFileChange: false,
    captureTimeout: 120000,
    browserDisconnectTolerance: 2,
    browserDisconnectTolerance: 2,
    browserNoActivityTimeout: 120000
  });
};

Keep only the options supported by your installed Karma version. If your existing file already contains Angular CLI defaults, change the browser and lifecycle settings rather than replacing the entire file.

When to add Chrome flags

Hosted Linux agents can fail when Chrome’s sandbox cannot initialize. Add flags only when the log identifies a sandbox or shared-memory problem:

customLaunchers: {
  ChromeHeadlessCI: {
    base: 'ChromeHeadless',
    flags: ['--no-sandbox', '--disable-dev-shm-usage']
  }
},
browsers: ['ChromeHeadlessCI']

--no-sandbox reduces isolation and should be limited to the controlled CI agent. It is not a general fix for assertion failures, Angular compilation errors, or a missing executable.

4. Use an Azure Pipelines job that installs dependencies and exits

A minimal YAML pipeline for a Linux hosted agent is:

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '20.x'
  displayName: Use Node.js

- script: npm ci
  displayName: Install dependencies

- script: ng test --no-watch --no-progress --browsers=ChromeHeadless
  displayName: Run Angular unit tests
  env:
    CI: true

If your project’s scripts or Angular version require a different Node release, match the version declared by the repository. Pinning the major version avoids a browser launcher or dependency change appearing unexpectedly on a hosted image.

Using the npm script

You can keep the command in package.json and call it from YAML:

{
  "scripts": {
    "test:ci": "ng test --no-watch --no-progress --browsers=ChromeHeadless"
  }
}
- script: npm run test:ci
  displayName: Run Angular tests once

5. Read the failure class before changing code

Log symptom Likely cause First fix
ChromeHeadless have not captured in 60000 ms Chrome did not launch, crashed, or could not connect Verify the agent browser and launcher; increase timeout only after launch is confirmed
Can not find Chrome binary Chrome or Chromium is absent, or CHROME_BIN points to a stale path Inspect the agent image and remove or correct the binary override
Failed to move to new namespace or sandbox errors Chrome sandbox restrictions on the agent Use a controlled CI launcher with --no-sandbox
Disconnected during a run Browser crash, resource pressure, or a long-running test Check memory and test duration; then tune disconnect and activity timeouts
Assertions fail but Chrome starts Application or test failure Fix the failing spec, fixture, compile error, or environment assumption
Pipeline never finishes Watch mode or file-change restart remains enabled Use --no-watch, --no-progress, singleRun: true, and restartOnFileChange: false

6. Troubleshoot ChromeHeadless launch failures

Check the executable path

On Linux agents, inspect common browser variables and the executable:

echo "$CHROME_BIN"
command -v google-chrome || true
command -v chromium || true
node -e "console.log(process.platform, process.arch)"

If CHROME_BIN is set to a path that does not exist, unset it or set it to the browser installed on the agent. Do not guess a path from a different operating system.

Check dependency installation

Use npm ci with a committed lockfile. A partial install can omit karma-chrome-launcher or produce a launcher version that does not match Karma.

npm ls karma karma-chrome-launcher @angular-devkit/build-angular
npm ci

Increase timeouts only for slow startup

Timeouts can help a busy hosted agent, but they cannot install Chrome or repair a failing test. Start with:

captureTimeout: 120000,
browserNoActivityTimeout: 120000,
browserDisconnectTolerance: 2

Keep the values finite so a broken browser does not consume an agent indefinitely.

Capture useful CI diagnostics

Print versions and preserve the test log as a pipeline artifact:

node --version
npm --version
ng version
npm run test:ci 2>&1 | tee test-output.log

Compare the failing job with a passing local run: Node version, Angular CLI version, browser executable, operating system, and environment variables.

7. Common configuration mistakes

  • Using Chrome in CI: a headed browser needs a graphical display. Select ChromeHeadless.
  • Leaving watch mode enabled: the process waits for file changes. Pass --no-watch and disable file-change restarts.
  • Setting singleRun to false: Karma stays alive after tests. Set it to true in CI.
  • Changing assertions for a launch error: browser connection messages occur before test assertions run.
  • Mixing test runners: Vitest configuration will not fix a Karma launcher problem, and Karma options do not configure Vitest.
  • Relying on a global Angular CLI: use the repository’s local CLI through ng in npm scripts or npx ng so versions stay aligned.

8. Reliability and performance practices

  • Run npm ci from a lockfile and pin the Node major version.
  • Use one CI command that always disables watch mode and progress output.
  • Keep browser startup diagnostics separate from assertion output.
  • Split unusually large test suites only when the project’s test architecture supports it; the supplied Angular and Microsoft guidance does not publish a speed benchmark.
  • Reserve longer timeouts for proven slow startup or heavy suites. Longer timeouts increase the time before a genuine failure is reported.
  • Use a clean agent when investigating flaky browser state. Cache dependencies carefully and invalidate the cache when the lockfile changes.

9. When to consider Vitest

Angular documents migration from Karma to Vitest through the @angular/build:unit-test builder. Evaluate that change using browser requirements, CI process lifecycle, existing Jasmine/Karma compatibility, debugging workflow, and migration effort. Vitest migration is a separate project decision; it is not the first-line repair for a missing Chrome binary or a misconfigured headless launcher.

10. Or skip the browser setup

If your goal is to capture a rendered Angular page for a visual artifact or review, ScreenshotNeo can take the screenshot through one HTTP request. It does not run Angular unit tests or replace Karma; it removes the browser automation setup for screenshot capture.

ScreenshotNeo removes common consent banners, popups, and chat widgets before capture.
ScreenshotNeo removes common consent banners, popups, and chat widgets before capture.

Before the capture, ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. Every plan includes the features; 1,000 screenshots per month are free with no card, and paid plans start at $5 for 3,000 shots.

See the ScreenshotNeo API documentation for the request options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Create a free ScreenshotNeo account with 1,000 screenshots a month and no card.

FAQ

Does ChromeHeadless run the same tests as Chrome?

It runs the browser-based Karma tests without a graphical interface. Browser-specific behavior can still differ, so investigate a genuine browser behavior failure separately from a launch failure.

Should I use --no-sandbox on every pipeline?

No. Add it only when the agent reports a sandbox initialization problem and use a controlled CI environment.

Why does increasing the timeout not fix the failure?

A timeout only gives a successfully starting browser more time. It cannot correct a missing executable, an invalid CHROME_BIN, or a crashed browser.

Can ScreenshotNeo replace Angular unit tests?

No. It captures web pages and PDFs. Karma or another test runner still executes Angular unit-test assertions.