GeezerVison

Testing your Angular application helps you check that it is working as you expect. Unit tests are crucial for catching bugs early, ensuring code quality, and facilitating safe refactoring.

Set up for testing

The Angular CLI downloads and installs everything you need to test an Angular application with the Vitest testing framework. New projects include vitest and jsdom by default.

Vitest runs your unit tests in a Node.js environment. To simulate the browser's DOM, Vitest uses a library called jsdom. This allows for faster test execution by avoiding the overhead of launching a browser. You can swap jsdom for an alternative like happy-dom by installing it and uninstalling jsdom. Currently, jsdom and happy-dom are the supported DOM emulation libraries.

The project you create with the CLI is immediately ready to test. Run the ng test command:

ng test

The ng test command builds the application in watch mode and launches the Vitest test runner.

The console output looks like this:

✓ src/app/app.spec.ts (2)
  ✓ App should create the app
  ✓ App should render title
Test Files  1 passed (1)
     Tests  2 passed (2)
  Start at  18:18:01
  Duration  2.46s (transform 615ms, setup 2ms, collect 2.21s, tests 5ms)

The ng test command also watches your files for changes. If you modify a file and save it, the tests will run again.

Configuration

The Angular CLI handles most of the Vitest configuration for you. You can customize the test behavior by modifying the test target options in your angular.json file.

Angular.json options

• include: Glob patterns for files to include for testing. Defaults to ['**/*.spec.ts', '**/*.test.ts'].
• exclude: Glob patterns for files to exclude from testing.
• setupFiles: A list of paths to global setup files (e.g., polyfills or global mocks) that are executed before your tests.
• providersFile: The path to a file that exports a default array of Angular providers for the test environment. This is useful for setting up global test providers which are injected into your tests.
• coverage: A boolean to enable or disable code coverage reporting. Defaults to false.
• browsers: An array of browser names to run tests in a real browser (e.g., ["chromium"]). Requires a browser provider to be installed. See the Running tests in a browser section for more details.

Global test setup and providers

The setupFiles and providersFile options are particularly useful for managing global test configuration.

For example, you could create a src/test-providers.ts file to provide provideHttpClientTesting to all your tests:

import {EnvironmentProviders, Provider} from '@angular/core';
import {provideHttpClientTesting} from '@angular/common/http/testing';

const testProviders: (Provider | EnvironmentProviders)[] = [provideHttpClientTesting()];

export default testProviders;

You would then reference this file in your angular.json:

{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "providersFile": "src/test-providers.ts"
          }
        }
      }
    }
  }
}

Advanced Vitest configuration

For advanced use cases, you can provide a custom Vitest configuration file using the runnerConfig option in angular.json.

You can create a Vitest configuration file (e.g., vitest-base.config.mts) and reference it in your angular.json:

{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "runnerConfig": "vitest-base.config.mts"
          }
        }
      }
    }
  }
}

You can also generate a base configuration file using the CLI:

ng generate config vitest

This creates a vitest-base.config.mts file that you can customize.

Code coverage

You can generate a code coverage report by adding the --coverage flag to the ng test command. The report is generated in the coverage/ directory.

For more detailed information, see the Code coverage guide.

Running tests in a browser

While the default Node.js environment is faster for most unit tests, you can also run your tests in a real browser. This is useful for tests that rely on browser-specific APIs (like rendering) or for debugging.

To run tests in a browser, you must first install a browser provider. Read more about Vitest's browser mode in the official documentation.

Once the provider is installed, you can run your tests in the browser by configuring the browsers option in angular.json or by using the --browsers CLI flag. Tests run in a headed browser by default. If the CI environment variable is set, headless mode is used instead. To explicitly control headless mode, you can suffix the browser name with Headless (e.g., chromiumHeadless).

# Example for Playwright (headed)
ng test --browsers=chromium

# Example for Playwright (headless)
ng test --browsers=chromiumHeadless

# Example for WebdriverIO (headed)
ng test --browsers=chrome

# Example for WebdriverIO (headless)
ng test --browsers=chromeHeadless

Choose one of the following browser providers based on your needs:

Playwright

Playwright is a browser automation library that supports Chromium, Firefox, and WebKit.

npm install --save-dev @vitest/browser-playwright playwright

yarn add --dev @vitest/browser-playwright playwright

pnpm add -D @vitest/browser-playwright playwright

bun add --dev @vitest/browser-playwright playwright

WebdriverIO

WebdriverIO is a browser and mobile automation test framework that supports Chrome, Firefox, Safari, and Edge.

npm install --save-dev @vitest/browser-webdriverio webdriverio

yarn add --dev @vitest/browser-webdriverio webdriverio

pnpm add -D @vitest/browser-webdriverio webdriverio

bun add --dev @vitest/browser-webdriverio webdriverio

Preview

The @vitest/browser-preview provider is designed for WebContainer environments like StackBlitz and is not intended for use in CI/CD.

npm install --save-dev @vitest/browser-preview

yarn add --dev @vitest/browser-preview

pnpm add -D @vitest/browser-preview

bun add --dev @vitest/browser-preview

Other test frameworks

You can also unit test an Angular application with other testing libraries and test runners. Each library and runner has its own installation procedures, configuration, and syntax.

Testing in continuous integration

A robust test suite is a key part of a continuous integration (CI) pipeline. CI servers let you automate your tests to run on every commit and pull request.

To test your Angular application in a CI server, run the standard test command:

ng test

Most CI servers set a CI=true environment variable, which ng test detects. This automatically configures your tests to run in a non-interactive, single-run mode.

If your CI server does not set this variable, or if you need to force single-run mode manually, you can use the --no-watch and --no-progress flags:

ng test --no-watch --no-progress

More information on testing

After you've set up your application for testing, you might find the following testing guides useful.