You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This commit updates the testing documentation to reflect the introduction of Vitest as the default test runner, while ensuring Karma testing instructions are still available.
Key changes include:
- Adding a new guide for "Testing with Karma" (`guide/testing/karma.md`).
- Updating the "Code Coverage" guide (`guide/testing/code-coverage.md`) to use `angular.json` for coverage enforcement and referencing Vitest documentation.
- Modifying the "Testing Overview" guide (`guide/testing/overview.md`) to introduce Vitest as the default, update `ng test` output examples, and link to the new Karma guide.
- Updating navigation data to include the new Karma testing guide.
Copy file name to clipboardExpand all lines: adev/src/content/guide/testing/code-coverage.md
+16-23Lines changed: 16 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ Code coverage reports show you any parts of your code base that might not be pro
7
7
To generate a coverage report run the following command in the root of your project.
8
8
9
9
<docs-codelanguage="shell">
10
-
ng test --no-watch --code-coverage
10
+
ng test --no-watch --coverage
11
11
</docs-code>
12
12
13
13
When the tests are complete, the command creates a new `/coverage` directory in the project.
@@ -18,40 +18,33 @@ If you want to create code-coverage reports every time you test, set the followi
18
18
<docs-codelanguage="json">
19
19
"test": {
20
20
"options": {
21
-
"codeCoverage": true
21
+
"coverage": true
22
22
}
23
23
}
24
24
</docs-code>
25
25
26
26
## Code coverage enforcement
27
27
28
28
The code coverage percentages let you estimate how much of your code is tested.
29
-
If your team decides on a set minimum amount to be unit tested, enforce this minimum with the Angular CLI.
29
+
If your team decides on a set minimum amount to be unit tested, you can enforce this minimum directly in your Angular CLI configuration.
30
30
31
31
For example, suppose you want the code base to have a minimum of 80% code coverage.
32
-
To enable this, open the [Karma](https://karma-runner.github.io) test platform configuration file, `karma.conf.js`, and add the `check` property in the `coverageReporter:` key.
To enable this, open the `angular.json` file and add the `coverageThresholds` option to your test configuration:
33
+
34
+
<docs-codelanguage="json">
35
+
"test": {
36
+
"options": {
37
+
"coverage": true,
38
+
"coverageThresholds": {
39
+
"statements": 80,
40
+
"branches": 80,
41
+
"functions": 80,
42
+
"lines": 80
48
43
}
49
44
}
50
45
}
51
46
</docs-code>
52
47
53
-
HELPFUL: Read more about creating and fine tuning Karma configuration in the [testing guide](guide/testing#configuration).
54
-
55
-
The `check` property causes the tool to enforce a minimum of 80% code coverage when the unit tests are run in the project.
48
+
Now, when you run `ng test`, the tool will throw an error if the coverage drops below 80%.
56
49
57
-
Read more on coverage configuration options in the [karma coverage documentation](https://github.com/karma-runner/karma-coverage/blob/master/docs/configuration.md).
50
+
HELPFUL: Read more about coverage configuration options in the [Vitest documentation](https://vitest.dev/config/#coverage-thresholds).
While Vitest is the default testing framework for new Angular projects, Karma is still a supported and widely used test runner. This guide provides instructions for testing your Angular application using the Karma and Jasmine testing stack.
4
+
5
+
## Setting Up and Running Tests
6
+
7
+
For new projects, you can configure Karma during generation by specifying the `testRunner` option:
8
+
9
+
<docs-codelanguage="shell">
10
+
ng new my-karma-app --test-runner=karma
11
+
</docs-code>
12
+
13
+
If you are adding Karma to an existing project, you must first install the necessary dependencies:
After installing the packages, update your `tsconfig.spec.json` to include the Jasmine types in the `compilerOptions`. This ensures that TypeScript recognizes the global testing functions like `describe` and `it`.
The test output is displayed in the browser using [Karma Jasmine HTML Reporter](https://github.com/dfederm/karma-jasmine-html-reporter).
64
+
65
+
<imgalt="Jasmine HTML Reporter in the browser"src="assets/images/guide/testing/initial-jasmine-html-reporter.png">
66
+
67
+
Click on a test row to re-run just that test or click on a description to re-run the tests in the selected test group ("test suite").
68
+
69
+
Meanwhile, the `ng test` command is watching for changes. To see this in action, make a small change to a source file and save. The tests run again, the browser refreshes, and the new test results appear.
70
+
71
+
## Configuration
72
+
73
+
The Angular CLI takes care of Jasmine and Karma configuration for you. It constructs the full configuration in memory, based on options specified in the `angular.json` file.
74
+
75
+
### Customizing Karma Configuration
76
+
77
+
If you want to customize Karma, you can create a `karma.conf.js` by running the following command:
78
+
79
+
<docs-codelanguage="shell">
80
+
81
+
ng generate config karma
82
+
83
+
</docs-code>
84
+
85
+
HELPFUL: Read more about Karma configuration in the [Karma configuration guide](http://karma-runner.github.io/6.4/config/configuration-file.html).
86
+
87
+
### Setting the Test Runner in `angular.json`
88
+
89
+
To explicitly set Karma as the test runner for your project, locate the `test` target in your `angular.json` file and set the `runner` option to `karma`:
90
+
91
+
<docs-codelanguage="json"title="angular.json">
92
+
{
93
+
// ...
94
+
"projects": {
95
+
"your-project-name": {
96
+
// ...
97
+
"architect": {
98
+
"test": {
99
+
"builder": "@angular/build:unit-test",
100
+
"options": {
101
+
"runner": "karma",
102
+
// ... other options
103
+
}
104
+
}
105
+
}
106
+
}
107
+
}
108
+
}
109
+
</docs-code>
110
+
111
+
## Code coverage enforcement
112
+
113
+
To enforce a minimum code coverage level, you can use the `check` property in the `coverageReporter` section of your `karma.conf.js` file.
114
+
115
+
For example, to require a minimum of 80% coverage:
This will cause the test run to fail if the specified coverage thresholds are not met.
137
+
138
+
Read more on coverage configuration options in the [karma coverage documentation](https://github.com/karma-runner/karma-coverage/blob/master/docs/configuration.md).
139
+
140
+
## Testing in continuous integration
141
+
142
+
To run your Karma tests in a CI environment, use the following command:
143
+
144
+
<docs-codelanguage="shell">
145
+
ng test --no-watch --no-progress --browsers=ChromeHeadless
Copy file name to clipboardExpand all lines: adev/src/content/guide/testing/overview.md
+27-28Lines changed: 27 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,9 +2,11 @@
2
2
3
3
Testing your Angular application helps you check that your application is working as you expect.
4
4
5
+
NOTE: While Vitest is the default test runner, Karma is still fully supported. For information on testing with Karma, see the [Karma testing guide](guide/testing/karma).
6
+
5
7
## Set up testing
6
8
7
-
The Angular CLI downloads and installs everything you need to test an Angular application with [Jasmine testing framework](https://jasmine.github.io).
9
+
The Angular CLI downloads and installs everything you need to test an Angular application with the [Vitest testing framework](https://vitest.dev).
8
10
9
11
The project you create with the CLI is immediately ready to test.
10
12
Just run the [`ng test`](cli/test) CLI command:
@@ -15,48 +17,43 @@ ng test
15
17
16
18
</docs-code>
17
19
18
-
The `ng test` command builds the application in *watch mode*,
19
-
and launches the [Karma test runner](https://karma-runner.github.io).
20
+
The `ng test` command builds the application in *watch mode* and launches the [Vitest test runner](https://vitest.dev).
20
21
21
22
The console output looks like below:
22
23
23
24
<docs-codelanguage="shell">
24
25
25
-
02 11 2022 09:08:28.605:INFO[karma-server]: Karma v6.4.1 server started at http://localhost:9876/
26
-
02 11 2022 09:08:28.607:INFO[launcher]: Launching browsers Chrome with concurrency unlimited
The last line of the log shows that Karma ran three tests that all passed.
35
-
36
-
The test output is displayed in the browser using [Karma Jasmine HTML Reporter](https://github.com/dfederm/karma-jasmine-html-reporter).
37
-
38
-
<imgalt="Jasmine HTML Reporter in the browser"src="assets/images/guide/testing/initial-jasmine-html-reporter.png">
39
-
40
-
Click on a test row to re-run just that test or click on a description to re-run the tests in the selected test group \("test suite"\).
41
-
42
37
Meanwhile, the `ng test` command is watching for changes.
43
38
44
-
To see this in action, make a small change to `app.component.ts` and save.
45
-
The tests run again, the browser refreshes, and the new test results appear.
39
+
To see this in action, make a small change to `app.ts` and save.
40
+
The tests run again, and the new test results appear in the console.
46
41
47
42
## Configuration
48
43
49
-
The Angular CLI takes care of Jasmine and Karma configuration for you. It constructs the full configuration in memory, based on options specified in the `angular.json` file.
44
+
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.
50
45
51
-
If you want to customize Karma, you can create a `karma.conf.js` by running the following command:
46
+
If you want to customize Vitest, you can create a `vitest-base.config.ts` by running the following command:
52
47
53
48
<docs-codelanguage="shell">
54
49
55
-
ng generate config karma
50
+
ng generate config vitest
56
51
57
52
</docs-code>
58
53
59
-
HELPFUL: Read more about Karma configuration in the [Karma configuration guide](http://karma-runner.github.io/6.4/config/configuration-file.html).
54
+
IMPORTANT: Using a custom `vitest-base.config.ts` provides powerful customization options. However, the Angular team does not provide support for the specific contents of this file or for any third-party plugins used within it.
55
+
56
+
HELPFUL: Read more about Vitest configuration in the [Vitest configuration guide](https://vitest.dev/config/).
60
57
61
58
### Other test frameworks
62
59
@@ -65,12 +62,12 @@ Each library and runner has its own distinctive installation procedures, configu
65
62
66
63
### Test file name and location
67
64
68
-
Inside the `src/app` folder the Angular CLI generated a test file for the `AppComponent`named `app.component.spec.ts`.
65
+
Inside the `src/app` folder the Angular CLI generated a test file for the `App` component named `app.spec.ts`.
69
66
70
-
IMPORTANT: The test file extension **must be `.spec.ts`** so that tooling can identify it as a file with tests \(also known as a *spec* file\).
67
+
IMPORTANT: The test file extension **must be `.spec.ts` or `.test.ts`** so that tooling can identify it as a file with tests \(also known as a *spec* file\).
71
68
72
-
The `app.component.ts` and `app.component.spec.ts` files are siblings in the same folder.
73
-
The root file names \(`app.component`\) are the same for both files.
69
+
The `app.ts` and `app.spec.ts` files are siblings in the same folder.
70
+
The root file names \(`app`\) are the same for both files.
74
71
75
72
Adopt these two conventions in your own projects for *every kind* of test file.
76
73
@@ -106,9 +103,11 @@ Continuous integration \(CI\) servers let you set up your project repository so
106
103
To test your Angular CLI application in Continuous integration \(CI\) run the following command:
107
104
108
105
<docs-codelanguage="shell">
109
-
ng test --no-watch --no-progress --browsers=ChromeHeadless
106
+
ng test --no-watch --no-progress
110
107
</docs-code>
111
108
109
+
NOTE: The `--no-watch` flag is often unnecessary in CI environments, as they typically don't use a TTY, which automatically disables watch mode.
110
+
112
111
## More information on testing
113
112
114
113
After you've set up your application for testing, you might find the following testing guides useful.
|`configureTestingModule`| The testing shims \(`karma-test-shim`, `browser-test-shim`\)establish the [initial test environment](guide/testing) and a default testing module. The default testing module is configured with basic declaratives and some Angular service substitutes that every tester needs. <br /> Call `configureTestingModule` to refine the testing module configuration for a particular set of tests by adding and removing imports, declarations \(of components, directives, and pipes\), and providers. |
62
+
|`configureTestingModule`| The testing shims establish the [initial test environment](guide/testing) and a default testing module. The default testing module is configured with basic declaratives and some Angular service substitutes that every tester needs. <br /> Call `configureTestingModule` to refine the testing module configuration for a particular set of tests by adding and removing imports, declarations \(of components, directives, and pipes\), and providers. |
63
63
|`compileComponents`| Compile the testing module asynchronously after you've finished configuring it. You **must** call this method if _any_ of the testing module components have a `templateUrl` or `styleUrls` because fetching component template and style files is necessarily asynchronous. See [compileComponents](guide/testing/components-scenarios#calling-compilecomponents). <br /> After calling `compileComponents`, the `TestBed` configuration is frozen for the duration of the current spec. |
64
64
|`createComponent<T>`| Create an instance of a component of type `T` based on the current `TestBed` configuration. After calling `createComponent`, the `TestBed` configuration is frozen for the duration of the current spec. |
65
65
|`overrideModule`| Replace metadata for the given `NgModule`. Recall that modules can import other modules. The `overrideModule` method can reach deeply into the current testing module to modify one of these inner modules. |
@@ -70,7 +70,7 @@ Here are the most important static methods, in order of likely utility.
70
70
|
71
71
`inject` | Retrieve a service from the current `TestBed` injector. The `inject` function is often adequate for this purpose. But `inject` throws an error if it can't provide the service. <br /> What if the service is optional? <br /> The `TestBed.inject()` method takes an optional second parameter, the object to return if Angular can't find the provider \(`null` in this example\): <docs-codeheader="app/demo/demo.testbed.spec.ts"path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts"visibleRegion="testbed-get-w-null"/> After calling `TestBed.inject`, the `TestBed` configuration is frozen for the duration of the current spec. |
72
72
|
73
-
`initTestEnvironment` | Initialize the testing environment for the entire test run. <br /> The testing shims \(`karma-test-shim`, `browser-test-shim`\)call it for you so there is rarely a reason for you to call it yourself. <br /> Call this method _exactly once_. To change this default in the middle of a test run, call `resetTestEnvironment` first. <br /> Specify the Angular compiler factory, a `PlatformRef`, and a default Angular testing module. Alternatives for non-browser platforms are available in the general form `@angular/platform-<platform_name>/testing/<platform_name>`. |
73
+
`initTestEnvironment` | Initialize the testing environment for the entire test run. <br /> The testing shims call it for you so there is rarely a reason for you to call it yourself. <br /> Call this method _exactly once_. To change this default in the middle of a test run, call `resetTestEnvironment` first. <br /> Specify the Angular compiler factory, a `PlatformRef`, and a default Angular testing module. Alternatives for non-browser platforms are available in the general form `@angular/platform-<platform_name>/testing/<platform_name>`. |
74
74
|`resetTestEnvironment`| Reset the initial test environment, including the default testing module. |
75
75
76
76
A few of the `TestBed` instance methods are not covered by static `TestBed`_class_ methods.
0 commit comments