Configuring Angular CLI to leverage Headless Chrome for Unit and E2E tests

Headless Chrome is a useful tool for running automated tests in environments where it isn’t practical to actually launch a browser. In this article we explain how to configure Angular CLI to run your Unit and E2E Tests using Headless Chrome.

This will become important for our upcoming set of articles in The Angular DevOps Series where we will want to run our automated tests in a Continuous Integration environment.


For our convenience Angular CLI adds the karma-chrome-launcher by default as one of our devDependencies in our package.json. So, we don’t need to install anything more to use Headless Chrome.

Unit Tests

By default, when we do npm run test, our unit tests are set up to watch for updates in the code and then run each time there are changes. However, we are targeting a test script that can eventually be used for continuous integration. So, let’s configure a new npm script to run our unit tests only once using Headless Chrome and then exit.

In package.json we just need to add a new entry called test-headless in our scripts. It should look something like this:

"scripts": {
  "ng": "ng",
  "start": "ng serve",
  "build": "ng build",
  "test": "ng test",
  "test-headless": "ng test --watch=false --browsers=ChromeHeadless",
  "lint": "ng lint",
  "e2e": "ng e2e"

Note the flags:

  • --watch=false
    Specifies that we only want the tests to run once and then exit instead of watching for changes.
  • --browsers=ChromeHeadless
    Specifies that we want to use Headless Chrome as the browser for the tests.

Now to run our unit tests with Headless Chrome we can use:

npm run test-headless

E2E Tests

When we create a new work space using Angular CLI, it configures Protractor to run our End-to-End tests (E2E).

We want configure our E2E tests to run using Headless Chrome. Unlike unit tests, it isn’t quite as simple as just adding a new npm script. This is because the arguments that are supported by ng e2e are different than the actual command line arguments supported natively by Protractor. But, not to worry, we can leverage the Protractor configuration file.

The Protractor configuration file for our E2E tests is:

We need to modify the capabilities entry in our protractor.conf.js file to include a chromeOptions object like this:

capabilities: {
  chromeOptions: {
    args: [ "--headless" ]
  'browserName': 'chrome'

In chromeOptions we have the args entry. With it, we can pass an array of string arguments into Protractor. For our purposes we only need one:

  • --headless
    Run Chrome in headless mode.

This is the minimal configuration necessary to run the E2E tests. Additionally, you may have code that relies on browser properties such as the window size. Then, you may need to add other flags such as --window-size=800x600.

To run your E2E tests use:

npm run e2e