From 21d6c94c257173497c5397121652ad3904cc1893 Mon Sep 17 00:00:00 2001 From: Bill Glesias Date: Wed, 6 Nov 2024 13:48:41 -0500 Subject: [PATCH] chore: update angular documentation with supported versions from Cypress 14 (#5983) * chore: update angular documentation with supported versions from cypress 14 and add migration guide documentation * address comments from code review --- docs/app/component-testing/angular/api.mdx | 18 +++++---- .../component-testing/angular/examples.mdx | 11 +++-- .../component-testing/angular/overview.mdx | 6 +-- docs/app/component-testing/get-started.mdx | 2 +- docs/app/references/migration-guide.mdx | 40 +++++++++++++++++++ 5 files changed, 61 insertions(+), 16 deletions(-) diff --git a/docs/app/component-testing/angular/api.mdx b/docs/app/component-testing/angular/api.mdx index 1dd878b7fa..5a8b28ef2d 100644 --- a/docs/app/component-testing/angular/api.mdx +++ b/docs/app/component-testing/angular/api.mdx @@ -12,12 +12,6 @@ sidebar_label: API import { mount } from 'cypress/angular' ``` -Be sure to use the `cypress/angular-signals` package if using Angular `17.2` and up and wishing to test `signal()`s within your component tests. - -```js -import { mount } from 'cypress/angular-signals' -``` - @@ -159,8 +153,16 @@ providers, declarations, imports and even component @Inputs() - - + +
Description
componentPropertiesPartial<{[P in keyof T]: T[P];}> (optional) If using the `cypress/angular-signals` test harness, this type is adapted to `Partial<{[P in keyof T]: T[P] extends InputSignal ? InputSignal | WritableSignal | V : T[P]}>` to allow for generic types to be wrapped inside a signal + Partial<{[P in keyof T]: T[P] extends InputSignal<infer V> + ? InputSignal<V> | WritableSignal<V> | V : T[P]}> + (optional) + + {' '} + signal based inference types need only apply if you are using signals within + your component tests +
diff --git a/docs/app/component-testing/angular/examples.mdx b/docs/app/component-testing/angular/examples.mdx index 1c9e23250b..a3ee8976d8 100644 --- a/docs/app/component-testing/angular/examples.mdx +++ b/docs/app/component-testing/angular/examples.mdx @@ -208,10 +208,13 @@ in the future ### Signals -With the releases of Angular versions [17.1](https://github.com/angular/angular/blob/main/CHANGELOG.md#1710-2024-01-17) and [17.2](https://github.com/angular/angular/blob/main/CHANGELOG.md#1720-2024-02-14), [input](https://github.com/angular/angular/pull/53521) and [model](https://github.com/angular/angular/pull/54252) signals were introduced into the `@angular/core` API. -Since signals introduced new methods and types to the core API, Cypress introduced a new test harness, `@cypress/angular-signals`. +With the releases of Angular versions [17.1](https://github.com/angular/angular/blob/main/CHANGELOG.md#1710-2024-01-17) and [17.2](https://github.com/angular/angular/blob/main/CHANGELOG.md#1720-2024-02-14), [input](https://github.com/angular/angular/pull/53521) and [model](https://github.com/angular/angular/pull/54252) signals were introduced into the `@angular/core` API. Though basic signals were introduced in Angular `16`, using all signals requires Angular `17.2` and above. -Though basic signals were introduced in Angular `16`, this testing harness requires Angular `17.2` and above. +:::info + +With Cypress 14, signal support is directly included in the `cypress/angular` testing harness. + +::: For the below examples, we'll be working with a very simple component called `TestComponent`, which looks something like shown below: @@ -268,7 +271,7 @@ cy.get('[data-cy="test-component-title-display"]').should( ``` :::info -Under the hood, Cypress wraps the generic value in a writable `signal()` and merges it into the prop. In other words, the `@cypress/angular-signals` test harness in this example is really: +Under the hood, Cypress wraps the generic value in a writable `signal()` and merges it into the prop. In other words, this example is really: ```typescript cy.mount(TestComponent, { diff --git a/docs/app/component-testing/angular/overview.mdx b/docs/app/component-testing/angular/overview.mdx index 21028fd1a5..533fba0fb7 100644 --- a/docs/app/component-testing/angular/overview.mdx +++ b/docs/app/component-testing/angular/overview.mdx @@ -15,7 +15,7 @@ sidebar_label: Overview ## Framework Support -Cypress Component Testing supports Angular 13+. +Cypress Component Testing supports Angular 17.2.0+. ## Tutorial @@ -119,5 +119,5 @@ export default { #### Sample Angular Apps -- [Angular 14](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/angular) -- [Angular 16 Standalone](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/angular-standalone) +- [Angular 17](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/angular) +- [Angular 18 Standalone](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/angular-standalone) diff --git a/docs/app/component-testing/get-started.mdx b/docs/app/component-testing/get-started.mdx index e68ea12605..9d64a86ab8 100644 --- a/docs/app/component-testing/get-started.mdx +++ b/docs/app/component-testing/get-started.mdx @@ -47,7 +47,7 @@ following development servers and frameworks: | [Vue CLI 4-5](/app/component-testing/vue/overview#Vue-CLI) | Vue 3 | Webpack 4-5 | | [Vue with Vite](/app/component-testing/vue/overview#Vue-with-Vite) | Vue 3 | Vite 4-5 | | [Vue with Webpack](/app/component-testing/vue/overview#Vue-with-Webpack) | Vue 3 | Webpack 4-5 | -| [Angular](/app/component-testing/angular/overview#Framework-Configuration) | Angular 13-18 | Webpack 5 | +| [Angular](/app/component-testing/angular/overview#Framework-Configuration) | Angular 17-18 | Webpack 5 | | [Svelte with Vite](/app/component-testing/svelte/overview#Svelte-with-Vite) Alpha | Svelte 3-4 | Vite 4-5 | | [Svelte with Webpack](/app/component-testing/svelte/overview#Svelte-with-Webpack) Alpha | Svelte 3-4 | Webpack 4-5 | diff --git a/docs/app/references/migration-guide.mdx b/docs/app/references/migration-guide.mdx index bf56030ca4..89d870b7a7 100644 --- a/docs/app/references/migration-guide.mdx +++ b/docs/app/references/migration-guide.mdx @@ -108,6 +108,46 @@ it('renders', () => { }) ``` +### Angular versions under `17.2.0` are no longer supported in Component Testing. + +With [LTS ending](https://angular.dev/reference/releases#actively-supported-versions) for Angular 16, the minimum required Angular version for component testing is now `17.2.0` in order to support [signals](/app/component-testing/angular/examples#Signals) as a first class citizen. + +If for any reason an older version of Angular must be used, please download [`@cypress/angular`](https://www.npmjs.com/package/@cypress/angular) `2.x` from `npm`. + +```sh +npm install --save-dev @cypress/angular@2 +``` + +Then, import the `mount` from this package in place of `cypress/angular`. + +```ts +import { mount } from `cypress/angular` +``` + +to + +```ts +import { mount } from `@cypress/angular` +``` + +This version of `@cypress/angular` is not actively supported and is only recommended as a workaround until you are able to upgrade. + +### `cypress/angular` now supports signals. The `cypress/angular-signals` test harness has been removed from the binary. + +Now that the minimum version of Angular supported for Component Testing is `17.2.0`, Cypress is able to merge the `cypress/angular-signals` test harness into the main `cypress/angular` test harness. Because of this, the `@cypress/angular-signals` harness is deprecated and no longer shipped with the binary. Support has been moved to `cypress/angular`. + +To migrate, just change the test harness from `cypress/angular-signals` to `cypress/angular`: + +```ts +import { mount } from `cypress/angular-signals` +``` + +to + +```ts +import { mount } from `cypress/angular` +``` + ## Migrating to Cypress 13.0 This guide details the changes and how to change your code to migrate to Cypress