|
| 1 | +# Experimental unit testing system |
| 2 | + |
| 3 | +The Angular CLI provides an experimental unit test system that can use [Vitest](https://vitest.dev/) as a test runner. |
| 4 | + |
| 5 | +IMPORTANT: This experimental unit testing system requires the use of the `application` build system. |
| 6 | +The `application` build system is the default for all newly created projects. |
| 7 | + |
| 8 | +## Set up testing |
| 9 | + |
| 10 | +The Angular CLI includes the test system within a new project but must be configured before it can be used. |
| 11 | + |
| 12 | +The project you create with the CLI is setup to use the `karma` test system by default. |
| 13 | +To change to the experimental unit test system, update the `test` target as follows: |
| 14 | + |
| 15 | +<docs-code language="json"> |
| 16 | +"test": { |
| 17 | + "builder": "@angular/build:unit-test", |
| 18 | + "options": { |
| 19 | + "tsConfig": "tsconfig.spec.json", |
| 20 | + "runner": "vitest", |
| 21 | + "buildTarget": "::development", |
| 22 | + } |
| 23 | +} |
| 24 | +</docs-code> |
| 25 | + |
| 26 | +The `buildTarget` operates similarly to the option available to the development server. |
| 27 | +The `build` target configures build options for the tests. |
| 28 | +If the `development` build configuration is missing for a project or you need |
| 29 | +different options for testing, you can create and use a `testing` or similarly named build configuration. |
| 30 | + |
| 31 | +To execute the application's testing, just run the [`ng test`](cli/test) CLI command as before: |
| 32 | + |
| 33 | +<docs-code language="shell"> |
| 34 | + |
| 35 | +ng test |
| 36 | + |
| 37 | +</docs-code> |
| 38 | + |
| 39 | +The `ng test` command builds the application in *watch mode*, and launches the configured runner. |
| 40 | + |
| 41 | +The console output looks like below: |
| 42 | + |
| 43 | +<docs-code language="shell"> |
| 44 | + ✓ spec-app-app.spec.js (2 tests) 31ms |
| 45 | + ✓ App > should create the app 22ms |
| 46 | + ✓ App > should render title 8ms |
| 47 | + |
| 48 | + Test Files 1 passed (1) |
| 49 | + Tests 2 passed (2) |
| 50 | + Start at 14:24:15 |
| 51 | + Duration 1.16s (transform 628ms, setup 703ms, collect 64ms, tests 31ms, environment 188ms, prepare 33ms) |
| 52 | +</docs-code> |
| 53 | + |
| 54 | +Watch mode is enabled by default when using an interactive terminal and not running on CI. |
| 55 | + |
| 56 | +## Configuration |
| 57 | + |
| 58 | +The Angular CLI takes care of the Vitest configuration for you. It constructs the full configuration in memory, based on options specified in the `angular.json` file. |
| 59 | +Directly customizing the underlying test runner configuration is currently not supported. |
| 60 | + |
| 61 | +## Bug reports |
| 62 | + |
| 63 | +Report issues and feature requests on [GitHub](https://github.com/angular/angular-cli/issues). |
| 64 | + |
| 65 | +Please provide a minimal reproduction where possible to aid the team in addressing issues. |
0 commit comments