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.
BREAKING CHANGE: Node.js v16 support has been removed
Node.js v16 is planned to be End-of-Life on 2023-09-11. Angular will stop supporting Node.js v16 in Angular v17.
For Node.js release schedule details, please see: https://github.com/nodejs/release#release-schedule
For now this just runs ESBuild-er to build test code, Jest is not actually invoked yet.
This uses `glob` to find test files matching the given pattern. I went out of my way to limit `glob` functionality as much as possible in case we change the implementation later.
The deprecated 'defaultCollection' workspace option has been removed
BREAKING CHANGE:
The deprecated `defaultCollection` workspace option has been removed. Use `schematicCollections` instead.
Before
```json
"defaultCollection": "@angular/material"
```
After
```json
"schematicCollections": ["@angular/material"]
```
The deprecated 'defaultProject' workspace option has been removed
BREAKING CHANGE: The deprecated `defaultProject` workspace option has been removed. The project to use will be determined from the current working directory.
BREAKING CHANGE: Node.js v14 support has been removed
Node.js v14 is planned to be End-of-Life on 2023-04-30. Angular will stop supporting Node.js v14 in Angular v16.
Angular v16 will continue to officially support Node.js versions v16 and v18.
This causes sub broken DX
```
ng bui[TAB]Your global Angular CLI version (14.2.6) is greater than your local version (14.1.3). The local Angular CLI version is used.
To disable this warning use "ng config -g cli.warnings.versionMismatch false".
ld --conf[TAB]Your global Angular CLI version (14.2.6) is greater than your local version (14.1.3). The local Angular CLI version is used.
To disable this warning use "ng config -g cli.warnings.versionMismatch false".
iguration dev[TAB]Your global Angular CLI version (14.2.6) is greater than your local version (14.1.3). The local Angular CLI version is used.
To disable this warning use "ng config -g cli.warnings.versionMismatch false".
elopment
```
Closes#24133
This change updates the analytics collector collector to use GA4 instead of UA. The motivation behind this change is that UA will stop collecting data in 2023.
BREAKING CHANGE:
`analyticsSharing` option in the global angular configuration has been
removed without replacement. This option was used to configure the Angular CLI to access to your own users' CLI usage data.
If this option is used, it can be removed using `ng config --global cli.analyticsSharing undefined`.
The global require function is not present in Node.js ESM mode. To support
the eventual transition of the `@angular/cli` package to ESM, usage of the
`require.resolve` function has been converted to use locally created `require`
functions via `createRequire` from the `module` builtin.
Previously when having completion enabled and the current workspaces has an older version of the Angular CLI installed in the terminal the below errors is show. This is because the older versions of the CLI do not implement this command. Now we exit gracefully.
```
The specified command ("completion") is invalid. For a list of available options,
run "ng help".
Did you mean "analytics"?
```
Closes#23518
- Prevent additional properties being set in cli subproperties (i.e. cli.warnings.zzzz).
- Create cliGlobalOptions definition and reference in the global.cli schema.
- Use global.cli schema to validate changes made with --global flag.
- Add test coverage for validating global/local-only changes.
- Add test coverage for setting invalid properties and sub-properties.
Running autocompletion with `14.0.1` installed globally in a `14.0.0` project logs the version warning in a very annoying fashion:
```
$ ng verYour global Angular CLI version (14.0.1) is greater than your local version (14.0.0). The local Angular CLI version is used.
To disable this warning use "ng config -g cli.warnings.versionMismatch false".
sion
```
This adds an exception for `ng completion` commands to avoid this edge case.
Prepares the `@angular/cli` package for the eventual change of enabling the
TypeScript `useUnknownInCatchVariables` option. This option provides additional
code safety by ensuring that the catch clause variable is the proper type before
attempting to access its properties. Similar changes will be needed in the other
packages in the repository prior to enabling `useUnknownInCatchVariables`.
Angular CLI versions prior to v14 may not exit correctly if not forcibly exited
via `process.exit`. When the local CLI version is less than v14, the CLI will now
use `process.exit` to ensure the process exits with these older CLI versions.
Fixes#23289
In certain situations the existing console logger created via `@angular-devkit/core` `createConsoleLogger`
could try to write to a closed stdout pipe stream. This would result in an error during
execution. For cases such as the completion script command, this would also prevent the
command from functioning. To mitigate these cases, `createConsoleLogger` is no longer used
and instead a logger instance is directly created within the CLI that uses `Console.log`
and `Console.error` to write output. Exiting the CLI also now waits for messages to be
logged before proceeding with the exit.
This option is never set and doesn't provide any value, since typically when one wants to debug, you add a `debugger` statement where needed or use the `break on exception` option in the debugger.
The `schematicCollections` can be placed under the `cli` option in the global `.angular.json` configuration, at the root or at project level in `angular.json` .
```jsonc
{
"$schema": "./node_modules/@angular/cli/lib/config/schema.json",
"version": 1,
"cli": {
"schematicCollections": ["@schematics/angular", "@angular/material"]
}
// ...
}
```
**Rationale**
When this option is not configured and a user would like to run a schematic which is not part of `@schematics/angular`,
the collection name needs to be provided to `ng generate` command in the form of `[collection-name:schematic-name]`. This make the `ng generate` command too verbose for repeated usages.
This is where `schematicCollections` comes handle. When adding `@angular/material` to the list of `schematicCollections`, the generate command will try to locate the schematic in the specified collections.
```
ng generate navigation
```
is equivalent to:
```
ng generate @angular/material:navigation
```
**Conflicting schematic names**
When multiple collections have a schematic with the same name. Both `ng generate` and `ng new` will run the first schematic matched based on the ordering (as specified) of `schematicCollections`.
DEPRECATED:
The `defaultCollection` workspace option has been deprecated in favor of `schematicCollections`.
Before
```json
"defaultCollection": "@angular/material"
```
After
```json
"schematicCollections": ["@angular/material"]
```
Closes#12157
With this change we deprecate the angular.json `defaultProject` option.
DEPRECATED:
The `defaultProject` workspace option has been deprecated. The project to use will be determined from the current working directory.
Closes#20661
With this change we update yargs help method to output help in JSON format which is needed to generate the documents that are used to generate AIO man pages.
With this change we refactor the Angular CLI and replace the underlying args parser and command builder. We choose to use Yargs as our parser and command builder of choice. The main advantages of Yargs over other command builders are;
- Highly configurable.
- We already use it in other packages such as the compiler-cli/dev-infra etc..
- Commands and options can be added during runtime. This is a requirement that is needed to support architect and schematics commands.
- Outstanding documentation.
- The possibility to parse args without parser configuration (Free form).
- Commands are built lazily based on the arguments passed.
BREAKING CHANGE:
Several changes in the Angular CLI commands and arguments handling.
- `ng help` has been removed in favour of the `—-help` option.
- `ng —-version` has been removed in favour of `ng version` and `ng v`.
- Deprecated camel cased arguments are no longer supported. Ex. using `—-sourceMap` instead of `—-source-map` will result in an error.
- `ng update`, `—-migrate-only` option no longer accepts a string of migration name, instead use `—-migrate-only -—name <migration-name>`.
- `—-help json` help has been removed.
Closes#20976, closes#16614 and closes#16241
Node.js v12 will become EOL on 2022-04-30. As a result, Angular CLI v14 will no longer support Node.js v12.
BREAKING CHANGE:
Support for Node.js v12 has been removed as it will become EOL on 2022-04-30. Please use Node.js v14.15 or later.
Previously, when using an older version of the Angular CLI, during `ng update`, we download the temporary `latest` version to run the update. The ensured that when running that the runner used to run the update contains the latest bug fixes and improvements.
This however, can be problematic in some cases. Such as when there are API breaking changes, when running a relatively old schematic with the latest CLI can cause runtime issues, especially since those schematics were never meant to be executed on a CLI X major versions in the future.
With this change, we improve the logic to determine which version of the Angular CLI should be used to run the update.
Below is a summarization of this.
- When using the `--next` command line argument, the `@next` version of the CLI will be used to run the update.
- When updating an `@angular/` or `@nguniversal/` package, the target version will be used to run the update. Example: `ng update @angular/core@12`, the update will run on most recent patch version of `@angular/cli` of that major version `@12.2.6`.
- When updating an `@angular/` or `@nguniversal/` and no target version is specified. Example: `ng update @angular/core` the update will run on most latest version of the `@angular/cli`.
- When updating a third-party package, the most recent patch version of the installed `@angular/cli` will be used to run the update. Example if `13.0.0` is installed and `13.1.1` is available on NPM, the latter will be used.
Persistent disk build cache is now enabled by default. A number of options have been added to allow fine tuning of the cache.
The options can be configuration in `cli.cache` section in the `angular.json` as shown below.
- `enabled`: Configure whether disk caching is enabled. Defaults to `true`
- `environment`: Configure in which environment disk cache is enabled. Valid values `ci`, `local` or `all`. Defaults to: `local`
- `path`: cache base path. Defaults to `.angular/cache`
DEPRECATED: `NG_BUILD_CACHE` environment variable option will be removed in the next major version. Configure `cli.cache` in the workspace configuration instead.
BREAKING CHANGE: `NG_PERSISTENT_BUILD_CACHE` environment variable option no longer have effect. Configure `cli.cache` in the workspace configuration instead.
```json
{
"$schema": "./node_modules/@angular/cli/lib/config/schema.json",
"version": 1,
"cli": {
"cache": {
"enabled": true,
"path": ".custom-cache-path",
"environment": "all"
}
}
...
}
```
Node.js v16 will be entering an LTS state prior to the release of Angular v13 which allows Node.js v16 to be marked as officially supported by the Angular CLI. The initial bootstrapping check now adds Node.js v16 to the output message in the event of an unsupported Node.js version.
NOTE: Prior to the final v13 release, the Node.js v16 minor should be updated to the actual LTS version once available.
All Angular builders are now located within one subdirectory of the `src` directory. This organization provides better discovery of the builders and will allow builder specific code to be stored in a single area.
The CLI contains a helper class instance that provides the version of the executing CLI. By using this helper throughtout the code, repeat `require` calls are no longer necessary.
All TypeScript files have been updated to pass the new eslint-based linting checks. eslint compatible disabling comments have also been added in place of the previous tslint comments.
