doc: document using Jest as test engine (40dfae81) · Commits · to be continuous... / Angular

README.md

+99 −2

Original line number	Diff line number	Diff line
		@@ -76,7 +76,8 @@ The next chapters presents some requirements related to your unit tests (using K
		To be able to launch unit tests with Angular CLI, the Angular template requires a headless browser within the Docker
		image `NG_CLI_IMAGE` (it is the case with the default image, [docker-ng-cli-karma](https://github.com/trion-development/docker-ng-cli-karma)).

		#### Code Coverage reports
		#### 1. Using Karma
		##### Code Coverage reports

		In order to be able to compute and enable [GitLab code coverage integration](https://docs.gitlab.com/ee/user/project/merge_requests/test_coverage_visualization.html),
		the Angular template expects the following in your `karma.conf.js`:
		@@ -116,7 +117,7 @@ the Angular template expects the following in your `karma.conf.js`:
		},
		```

		#### Unit Tests reports
		##### Unit Tests reports

		In order to be able to [integrate your test reports to GitLab](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportsjunit):

		@@ -167,6 +168,102 @@ Additionally, if using SonarQube, you may also want to generate [SonarQube g
		NG_TEST_ARGS: test --reporters junit,sonarqubeUnit`
		```

		#### 2. Using Jest
		##### Unit Tests reports
		To be able to use Jest instead Karma, you first have to install some jest packages.
		Then you have to create a dedicated jest config file, and to modify your angular.json and tsconfig.spec.json files to set Jest as test builder.

		1. Add [jest](https://www.npmjs.com/package/jest), [jest-junit](https://github.com/jest-community/jest-junit#readme), [jest-preset-angular](https://www.npmjs.com/package/jest-preset-angular), [@types/jest](https://www.npmjs.com/package/@types/jest) and [@angular-builders/jest](https://www.npmjs.com/package/@angular-builders/jest) to your project as a dev dependency:
		```shell
		npm install jest jest-preset-angular jest-junit @types/jest @angular-builders/jest --save-dev
		```

		2. Create the file `jest.config.js`, and add the following lines:
		```js
		module.exports = {
		reporters: [
		'default',
		["jest-junit",
		{
		outputDirectory: "reports",
		outputName: "ng-test.xunit.xml"
		}],
		],
		preset: 'jest-preset-angular',
		globalSetup: 'jest-preset-angular/global-setup',
		};
		```

		3. Open the `angular.json` file. Replace the test builder with jest, and convert "inlineStyleLanguage" option to array instead string:

		```js
		"test": {
		// REPLACE: "builder": "@angular-devkit/build-angular:karma",
		// With:
		"builder": "@angular-builders/jest:run",
		...
		// REPLACE: "inlineStyleLanguage": "scss",
		// With:
		"inlineStyleLanguage": ["scss"],
		```

		4. Open the `tsconfig.spec.json`file and replace the following line:
		```js
		"types": [
		// REPLACE: "jasmine"
		// With:
		"jest"
		]
		```

		##### Code Coverage reports

		1. Modify the file `jest.config.js`, and add the following lines into the module.exports:
		```js
		coverageDirectory: "reports",
		coverageReporters: [
		// 'text' to let GitLab grab coverage from stdout
		"text",
		// 'cobertura' to enable GitLab test coverage visualization
		["cobertura",{file: 'ng-coverage.cobertura.xml'}],
		// [OPTIONAL] only if using SonarQube
		// 'lcovonly' to enable SonarQube test coverage reporting
		"lcovonly",
		],
		```

		2. Open the `angular.json` file and add the following line to the test options:
		```js
		"ci": true,
		"coverage": true,
		```

		3. Finally, override the NG_TEST_ARGS from your `gitlab-ci.yml` variables:
		```
		NG_TEST_ARGS: test --coverage
		```

		Additionally, if using SonarQube, you may also want to generate [SonarQube generic test report](https://docs.sonarqube.org/latest/analysis/generic-test/):

		1. Add [jest-sonar-reporter](https://www.npmjs.com/package/jest-sonar-reporter) to your project as a dev dependency:
		```shell
		npm install --save-dev jest-sonar-reporter
		```
		2. In your `jest.config.js`, add this config line to the exports:
		```js
		testResultsProcessor: "jest-sonar-reporter",
		```
		3. In your `jest.config.js`, add a jestSonar section to configure the name of the jest report.
		```js
		"devDependencies": {
		...
		},
		"jestSonar": {
		"reportPath": "reports",
		"reportFile": "ng-test.sonar.xml"
		}
		```

		### `ng-e2e` job

		The Angular template features a job `ng-e2e` that performs protractor tests