mirror of
https://github.com/angular/angular-cli.git
synced 2025-05-17 19:13:34 +08:00
68dae539ad
This is a new `@angular-devkit/build-angular:web-test-runner` builder which invokes Web Test Runner to execute unit tests in a real browser.
The implementation calls `application` builder under the hood with some option overrides build the application to a temporary directory and then runs Web Test Runner on the output. This set up is still minimal, but sufficient to run and pass tests in the generated `ng new` application.
The `schema.json` file is directly copied from the `karma` builder, since this is intended to serve as a migration target for users coming from Karma. Most of the options don't actually work yet, which is logged when they are used.
The most interesting part of this change is configuring Jasmine to execute in Web Test Runner. This is done through the `testRunnerHtml` option which allows us to control the HTML page tests are executed on. We use `test_page.html` which very carefully controls the loading process. I opted to make a single `<script type="module">` which dynamic imports all the relevant pieces so the ordering can be directly controlled more easily. This is better than trying to manage multiple `<script>` tags and pass data between them. Ideally everything would be bundled into a single entry point, however this is not feasible due to the way that ordering requirements do not align with typical `import` structure. Jasmine must come before polyfills which must come before the runner which invokes user code. In an ideal world, this ordering relationship would be represented in `import` statements, but this is not practically feasible because Angular CLI doesn't own all the files (`./polyfills.js` is user-defined) and Jasmine's loading must be split into two places so Zone.js can properly patch it.
`jasmine_runner.js` serves the purpose of executing Jasmine tests and reporting their results to Web Test Runner. I tried to write `jasmine_runner.js` in TypeScript and compile it with a `ts_library`. Unfortunately I don't think this is feasible because it needs to import `@web/test-runner-core` at runtime. This dependency has some code generated at runtime in Web Test Runner, meaning we cannot bundle this dependency and must mark it as external and dynamic `import()` the package at runtime. This works fine in native ESM, but compiling with TypeScript outputs CommonJS code by default (and I don't believe our `@build_bazel_rules_nodejs` setup can easily change that), so any `import('@web/test-runner-core')` becomes `require('@web/test-runner-core')` which fails because that package is ESM-only. The `loadEsmModule` trick does work here either because Web Test Runner is applying Node module resolution at serve time, meaning it looks for `import('@web/test-runner-core')` and rewrites it to something like `import('/node_modules/@web/test-runner-core')`. In short, there is no easy syntax which circumvents the TypeScript compiler while also being statically analyzable to Web Test Runner.
@angular-devkit/build-angular
This package contains Architect builders used to build and test Angular applications and libraries.
Builders
| Name | Description |
|---|---|
| application | Build an Angular application targeting a browser and server environment using esbuild. |
| app-shell | Build an Angular App shell. |
| browser | Build an Angular application targeting a browser environment using Webpack. |
| browser-esbuild | Build an Angular application targeting a browser environment using esbuild. |
| dev-server | A development server that provides live reloading. |
| extract-i18n | Extract i18n messages from an Angular application. |
| karma | Execute unit tests using Karma test runner. |
| ng-packagr | Build and package an Angular library in Angular Package Format (APF) format using ng-packagr. |
| prerender | Prerender pages of your application. Prerendering is the process where a dynamic page is processed at build time generating static HTML. |
| server | Build an Angular application targeting a Node.js environment. |
| ssr-dev-server | A development server which offers live reload during development, but uses server-side rendering. |
| protractor | Deprecated - Run end-to-end tests using Protractor framework. |
Disclaimer
While the builders when executed via the Angular CLI and their associated options are considered stable, the programmatic APIs are not considered officially supported and are not subject to the breaking change guarantees of SemVer.