diff --git a/docs/api/commands/intercept.mdx b/docs/api/commands/intercept.mdx index 59b7c25ebc..1a43d5a79c 100644 --- a/docs/api/commands/intercept.mdx +++ b/docs/api/commands/intercept.mdx @@ -136,21 +136,21 @@ glob-matched against the request using [`Cypress.minimatch`](/api/utilities/minimatch) with the `{ matchBase: true }` minimatch option applied. -| Option | Description | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| auth | HTTP Basic Authentication (`object` with keys `username` and `password`) | -| headers | HTTP request headers (`object`) | -| hostname | HTTP request hostname | -| https | `true`: only secure (https://) requests, `false`: only insecure (http://) requests | -| method | HTTP request method (matches any method by default) | -| middleware | `true`: match route first and in defined order, `false`: match route in reverse order (default) | -| path | HTTP request path after the hostname, including query parameters | -| pathname | Like `path`, but without query parameters | -| port | HTTP request port(s) (`number` or `Array`) | -| query | Parsed query string (`object`) | -| resourceType | The resource type of the request. See ["Request object properties"](#Request-object-properties) for a list of possible values for `resourceType`. | -| times | Maximum number of times to match (`number`) | -| url | Full HTTP request URL | +| Option | Description | +| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| auth | HTTP Basic Authentication (`object` with keys `username` and `password`) | +| headers | HTTP request headers (`object`) | +| hostname | HTTP request hostname | +| https | `true`: only secure (https://) requests, `false`: only insecure (http://) requests | +| method | HTTP request method (matches any method by default) | +| middleware | `true`: match route first and in defined order, `false`: match route in reverse order (default) | +| path | HTTP request path after the hostname, including query parameters | +| pathname | Like `path`, but without query parameters | +| port | HTTP request port(s) (`number` or `Array`) | +| query | Parsed query string (`object`) | +| resourceType deprecated | The resource type of the request. See ["Request object properties"](#Request-object-properties) for a list of possible values for `resourceType`. | +| times | Maximum number of times to match (`number`) | +| url | Full HTTP request URL | See [examples](#With-RouteMatcher) below. @@ -1628,6 +1628,7 @@ information about the request and response to the console: | Version | Changes | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [14.0.0](/app/references/changelog#14-0-0) | Deprecated `resourceType` property | | [12.2.0](/app/references/changelog#12-2-0) | Added `resourceType` property to `req` and `RouteMatcher`. | | [7.6.0](/app/references/changelog#7-0-0) | Added `query` option to `req` (The incoming request object yielded to request handler functions). | | [7.0.0](/app/references/changelog#7-0-0) | Removed `matchUrlAgainstPath` option from `RouteMatcher`, reversed handler ordering, added request events, removed substring URL matching, removed `cy.route2` alias, added `middleware` RouteMatcher option, renamed `res.delay()` to `res.setDelay()` and `res.throttle()` to `res.setThrottle()`. | diff --git a/docs/api/commands/mount.mdx b/docs/api/commands/mount.mdx index d89c9c4942..a666292cfa 100644 --- a/docs/api/commands/mount.mdx +++ b/docs/api/commands/mount.mdx @@ -42,10 +42,6 @@ to start with for your commands: ```js -// React 18 -import { mount } from 'cypress/react18' - -// React 16, 17 import { mount } from 'cypress/react' Cypress.Commands.add('mount', (component, options) => { @@ -56,33 +52,7 @@ Cypress.Commands.add('mount', (component, options) => { ``` - - -```js -import { mount } from 'cypress/vue2' - -Cypress.Commands.add('mount', (component, options = {}) => { - // Setup options object - options.extensions = options.extensions || {} - options.extensions.plugins = options.extensions.plugins || [] - options.extensions.components = options.extensions.components || {} - - /* Add any global plugins */ - // options.extensions.plugins.push({ - // install(app) { - // app.use(MyPlugin); - // }, - // }); - - /* Add any global components */ - // options.extensions.components['Button'] = Button; - - return mount(component, options) -}) -``` - - - + ```js import { mount } from 'cypress/vue' diff --git a/docs/api/commands/origin.mdx b/docs/api/commands/origin.mdx index 6ed658a35a..342039bbf7 100644 --- a/docs/api/commands/origin.mdx +++ b/docs/api/commands/origin.mdx @@ -9,8 +9,8 @@ e2eSpecific: true # origin -Visit multiple domains of different -[origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#definition_of_an_origin) +Visit multiple different +[origins](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#definition_of_an_origin) in a single test. In normal use, a single Cypress test may only run commands in a single origin, a @@ -34,6 +34,18 @@ doc. ::: +:::info + +Changes in Cypress [v14.0.0](/app/references/changelog#14-0-0) + +Cypress no longer injects `document.domain` by default, which means `cy.origin()` +must now be used to navigate between any two origins in the same test, even if +the two origins are in the same superdomain. This behavior can be disabled by setting +the `injectDocumentDomain` configuration option to `true`, to allow a smooth transition +of tests to the new behavior. In Cypress 15, this configuration option will be removed. + +::: + ## Syntax ```js @@ -69,26 +81,28 @@ cy.get('h1').contains('My cool site under test') const hits = getHits() cy.visit('https://example.cypress.io/history/founder') // To interact with cross-origin content, move this inside cy.origin() callback -cy.get('h1').contains('About our Founder') -// Domain must be a precise match including subdomain, i.e. example.cypress.io -cy.origin('cypress.io', () => { - cy.visit('/history/founder') - cy.get('h1').contains('About our Founder') - // Fails because hits is not passed in via args - cy.get('#hitcounter').contains(hits) +cy.get('h1').contains('Kitchen Sink') +// Origin must be a precise match including scheme, subdomain and port, i.e. https://www.cypress.io +cy.origin('https://www.cypress.io', () => { + cy.visit('/about-us') + cy.get('h1').contains('About us') + // Fails because doanloads is not passed in via args + cy.contains(downloads) }) -// Won't work because still on cypress.io -cy.get('h1').contains('My cool site under test') +// Won't work because still on www.cypress.io +cy.get('h1').contains('Kitchen Sink') ``` ### Arguments - **url _(String)_** + **origin _(String)_** -A URL specifying the secondary origin in which the callback is to be executed. -This should at the very least contain a hostname, and may also include the -protocol, port number & path. The hostname must precisely match that of the -secondary origin, including all subdomains. Query params are not supported. +A string specifying the origin in which the callback is to be executed. +This should at the very least contain a hostname. It may also include the +scheme and port number. The path may be included, but is not necessary. +The hostname must precisely match that of the secondary origin, including +all subdomains. Query params are not supported. If no scheme is provided, +the scheme defaults to `https`. This argument will be used in two ways: @@ -548,6 +562,7 @@ inclusion in a future version of Cypress. | Version | Changes | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| [14.0.0](/app/references/changelog#14-0-0) | `cy.origin()` is now required when navigating between origins in the same test, rather than superdomains. | | [12.6.0](/app/references/changelog#10-7-0) | Support for `Cypress.require()` added and support for CommonJS `require()` and ES module `import()` removed | | [10.11.0](/app/references/changelog#10-7-0) | Support for CommonJS `require()` and ES module `import()` added and support for `Cypress.require()` removed | | [10.7.0](/app/references/changelog#10-7-0) | Support for `Cypress.require()` added | diff --git a/docs/app/component-testing/angular/api.mdx b/docs/app/component-testing/angular/api.mdx index 3c272f11ca..b7bed7f604 100644 --- a/docs/app/component-testing/angular/api.mdx +++ b/docs/app/component-testing/angular/api.mdx @@ -17,12 +17,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' -``` - @@ -164,8 +158,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 fdced7722f..75eab39e05 100644 --- a/docs/app/component-testing/angular/examples.mdx +++ b/docs/app/component-testing/angular/examples.mdx @@ -74,6 +74,10 @@ If you need to set up any additional `imports`, `declarations`, or `providers` for your component to mount successfully, you can set them in the options (similar to setting them up in `ngModule` in a app): +:::info +Note: `imports`, `declarations`, and `providers` options do not work with `standalone` components as they are set within the test `ngModule`. This is the default behavior in Angular 19. +::: + ```ts cy.mount(ComponentThatFetchesData, { imports: [HttpClientModule], @@ -213,10 +217,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: @@ -273,7 +280,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 36aa91aefc..29d0bb6a48 100644 --- a/docs/app/component-testing/angular/overview.mdx +++ b/docs/app/component-testing/angular/overview.mdx @@ -20,7 +20,7 @@ sidebar_label: Overview ## Framework Support -Cypress Component Testing supports Angular 13+. +Cypress Component Testing supports Angular 17.2.0+. ## Tutorial @@ -124,5 +124,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 18](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/angular) +- [Angular 19 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 1efb25a1fe..143d9bc5e3 100644 --- a/docs/app/component-testing/get-started.mdx +++ b/docs/app/component-testing/get-started.mdx @@ -42,17 +42,14 @@ following development servers and frameworks: | Framework | UI Library | Bundler | | ------------------------------------------------------------------------------------------------------------------ | ------------- | ----------- | -| [Create React App 4-5](/app/component-testing/react/overview#Create-React-App-CRA) | React 16-18 | Webpack 4-5 | -| [Next.js 10-14](/app/component-testing/react/overview#Nextjs) | React 16-18 | Webpack 5 | -| [React with Vite](/app/component-testing/react/overview#React-with-Vite) | React 16-18 | Vite 2-5 | -| [React with Webpack](/app/component-testing/react/overview#React-with-Webpack) | React 16-18 | Webpack 4-5 | -| [Vue CLI 4-5](/app/component-testing/vue/overview#Vue-CLI) | Vue 2-3 | Webpack 4-5 | -| [Nuxt 2](/app/component-testing/vue/overview#Nuxt) Alpha | Vue 2-3 | Webpack 4-5 | -| [Vue with Vite](/app/component-testing/vue/overview#Vue-with-Vite) | Vue 2-3 | Vite 2-5 | -| [Vue with Webpack](/app/component-testing/vue/overview#Vue-with-Webpack) | Vue 2-3 | Webpack 4-5 | -| [Angular](/app/component-testing/angular/overview#Framework-Configuration) | Angular 13-18 | Webpack 5 | -| [Svelte with Vite](/app/component-testing/svelte/overview#Svelte-with-Vite) Alpha | Svelte 3-4 | Vite 2-5 | -| [Svelte with Webpack](/app/component-testing/svelte/overview#Svelte-with-Webpack) Alpha | Svelte 3-4 | Webpack 4-5 | +| [React with Vite](/app/component-testing/react/overview#React-with-Vite) | React 18-19 | Vite 4-6 | +| [React with Webpack](/app/component-testing/react/overview#React-with-Webpack) | React 18-19 | Webpack 4-5 | +| [Next.js 14-15](/app/component-testing/react/overview#Nextjs) | React 18-19 | Webpack 5 | +| [Vue with Vite](/app/component-testing/vue/overview#Vue-with-Vite) | Vue 3 | Vite 4-6 | +| [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 17-19 | Webpack 5 | +| [Svelte with Vite](/app/component-testing/svelte/overview#Svelte-with-Vite) Alpha | Svelte 5 | Vite 4-6 | +| [Svelte with Webpack](/app/component-testing/svelte/overview#Svelte-with-Webpack) Alpha | Svelte 5 | Webpack 4-5 | The following integrations are built and maintained by Cypress community members. @@ -623,14 +620,10 @@ it('clicking + fires a change event with the incremented value', () => { ```js it('clicking + fires a change event with the incremented value', () => { - const changeSpy = cy.spy().as('changeSpy') - cy.mount(Stepper).then(({ component }) => { - component.$on('change', changeSpy) - }) + const onChangeSpy = cy.spy().as('onChangeSpy') + cy.mount(Stepper, { props: { onChange: onChangeSpy } }) cy.get('[data-cy=increment]').click() - cy.get('@changeSpy').should('have.been.calledWithMatch', { - detail: { count: 1 }, - }) + cy.get('@onChangeSpy').should('have.been.calledWith', 1) }) ``` diff --git a/docs/app/component-testing/react/api.mdx b/docs/app/component-testing/react/api.mdx index 48e4a441fc..c2b80f181f 100644 --- a/docs/app/component-testing/react/api.mdx +++ b/docs/app/component-testing/react/api.mdx @@ -14,10 +14,6 @@ sidebar_label: API ### mount ```js -// React 18 -import { mount } from 'cypress/react18' - -// React 16, 17 import { mount } from 'cypress/react' ``` diff --git a/docs/app/component-testing/react/overview.mdx b/docs/app/component-testing/react/overview.mdx index 19d4d9536f..2531e91fcc 100644 --- a/docs/app/component-testing/react/overview.mdx +++ b/docs/app/component-testing/react/overview.mdx @@ -20,13 +20,12 @@ sidebar_label: Overview ## Framework Support -Cypress Component Testing currently supports React 16+ with the following +Cypress Component Testing currently supports React 18 and 19 with the following frameworks: -- [Create React App](#Create-React-App-CRA) -- [Next.js](#Nextjs) - [React with Vite](#React-with-Vite) - [React with Webpack](#React-with-Webpack) +- [Next.js](#Nextjs) ## Tutorial @@ -64,84 +63,14 @@ For usage and examples, visit the ## Framework Configuration -Cypress Component Testing works out of the box with -[Create React App](https://create-react-app.dev/), -[Next.js](https://nextjs.org/), [Vite](https://vitejs.dev/), and a custom +Cypress Component Testing works out of the box with [Vite](https://vitejs.dev/), [Next.js](https://nextjs.org/), and a custom [Webpack](https://webpack.js.org/) config. Cypress will automatically detect one of these frameworks during setup and configure them properly. The examples below are for reference purposes. -### Create React App (CRA) - -Cypress Component Testing works with CRA 4+. - -#### CRA Configuration - -:::cypress-config-example - -```ts -{ - component: { - devServer: { - framework: 'create-react-app', - bundler: 'webpack', - }, - }, -} -``` - -::: - -#### Sample Create React Apps - -- [CRA 4 with JavaScript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/react-cra4-js) -- [CRA 5 with TypeScript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/react-cra5-ts) - -### Next.js - -Cypress Component Testing works with Next.js 11+. - -#### Next.js Configuration - -:::cypress-config-example - -```ts -{ - component: { - devServer: { - framework: 'next', - bundler: 'webpack', - }, - }, -} -``` - -::: - -#### Next.js Caveats - -There are some specific caveats to consider when testing Next.js -[Pages](https://nextjs.org/docs/basic-features/pages) in component testing. - -A page component could have additional logic in its `getServerSideProps` or -`getStaticProps` methods. These methods only run on the server, so they are not -available to run inside a component test. Trying to test a page in a component -test would result in the props being passed into the page to be undefined. - -While you could pass in props directly to the page component in a component -test, that would leave these server-side methods untested. However, an -end-to-end test would execute and test a page entirely. - -Because of this, we recommend using E2E Testing over Component Testing for -Next.js pages and Component Testing for individual components in a Next.js app. - -#### Sample Next.js Apps - -- [Next.js 13 with TypeScript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/react-next13-ts) - ### React with Vite -Cypress Component Testing works with React apps that use Vite 2+ as the bundler. +Cypress Component Testing works with React apps that use Vite 4+ as the bundler. #### Vite Configuration @@ -220,6 +149,49 @@ it via the `webpackConfig` option. - [React Webpack 5 with JavaScript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/react-webpack5-js) +### Next.js + +Cypress Component Testing works with Next.js 14 and Next.js 15. + +#### Next.js Configuration + +:::cypress-config-example + +```ts +{ + component: { + devServer: { + framework: 'next', + bundler: 'webpack', + }, + }, +} +``` + +::: + +#### Next.js Caveats + +There are some specific caveats to consider when testing Next.js +[Pages](https://nextjs.org/docs/basic-features/pages) in component testing. + +A page component could have additional logic in its `getServerSideProps` or +`getStaticProps` methods. These methods only run on the server, so they are not +available to run inside a component test. Trying to test a page in a component +test would result in the props being passed into the page to be undefined. + +While you could pass in props directly to the page component in a component +test, that would leave these server-side methods untested. However, an +end-to-end test would execute and test a page entirely. + +Because of this, we recommend using E2E Testing over Component Testing for +Next.js pages and Component Testing for individual components in a Next.js app. + +#### Sample Next.js Apps + +- [Next.js 14 with TypeScript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/react-next14-ts) +- [Next.js 15 with TypeScript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/react-next15-ts) + ## Community Resources - [Cypress Component Test Driven Design](https://muratkerem.gitbook.io/cctdd/) diff --git a/docs/app/component-testing/styling-components.mdx b/docs/app/component-testing/styling-components.mdx index b22e147e3c..79be94ac84 100644 --- a/docs/app/component-testing/styling-components.mdx +++ b/docs/app/component-testing/styling-components.mdx @@ -269,7 +269,7 @@ covered in the last section. import './main.css' ``` -4. Within a configuration file like `next.config.js` or `nuxt.config.js`. +4. Within a configuration file like `next.config.js`. You're usually providing public paths to these stylesheets. You can import the same paths within your `cypress/support/component-index.html` file. diff --git a/docs/app/component-testing/svelte/api.mdx b/docs/app/component-testing/svelte/api.mdx index 4ee9682601..2e282949c6 100644 --- a/docs/app/component-testing/svelte/api.mdx +++ b/docs/app/component-testing/svelte/api.mdx @@ -25,15 +25,11 @@ import { mount } from 'cypress/svelte' Signature - mount<T extends SvelteComponent>(Component: - SvelteConstructor<T>, options?: MountOptions<T>): - Cypress.Chainable<MountReturn<T>> + mount(Component: Component<Record<string, any>, Record<string, + any>, any>, options?: MountOptions): + Cypress.Chainable<MountReturn> - - Generic Param T - The component type - Returns Cypress.Chainable<MountReturn> @@ -49,12 +45,14 @@ import { mount } from 'cypress/svelte' component - SvelteConstructor<T> + + Component<Record<string, any>, Record<string, any>, any> + Svelte component being mounted options - MountOptions<T> (optional) + MountOptions (optional) options to customize the component being mounted @@ -122,7 +120,7 @@ Type that the `mount` function yields component - T + Record<string, any> diff --git a/docs/app/component-testing/svelte/examples.mdx b/docs/app/component-testing/svelte/examples.mdx index 077007e03a..3f5bc0f494 100644 --- a/docs/app/component-testing/svelte/examples.mdx +++ b/docs/app/component-testing/svelte/examples.mdx @@ -47,21 +47,18 @@ it('mounts', () => { ### Testing Event Handlers -To test emitted events from a Svelte component, we can use access the component -instances and use `$on` method to listen to events raised. We can also pass in a +To test emitted events from a Svelte component, we need to pass in a callback +for when we increment the stepper. The Stepper component +will need to invoke this callback for us. We can also pass in a Cypress spy so we can query the spy later for results. In the example below, we -listen to the `change` event and validate it was called as expected: +pass in the `onChange` callback handler and validate it was called as expected: ```js it('clicking + fires a change event with the incremented value', () => { - const changeSpy = cy.spy().as('changeSpy') - cy.mount(Stepper).then(({ component }) => { - component.$on('change', changeSpy) - }) + const onChangeSpy = cy.spy().as('onChangeSpy') + cy.mount(Stepper, { props: { onChange: onChangeSpy } }) cy.get('[data-cy=increment]').click() - cy.get('@changeSpy').should('have.been.calledWithMatch', { - detail: { count: 1 }, - }) + cy.get('@onChangeSpy').should('have.been.calledWith', 1) }) ``` diff --git a/docs/app/component-testing/svelte/overview.mdx b/docs/app/component-testing/svelte/overview.mdx index 507d8a5a18..2dd164f528 100644 --- a/docs/app/component-testing/svelte/overview.mdx +++ b/docs/app/component-testing/svelte/overview.mdx @@ -21,7 +21,7 @@ sidebar_label: Overview ## Framework Support -Cypress Component Testing supports Svelte 3+ in a variety of different +Cypress Component Testing supports Svelte 5 in a variety of different frameworks: - [Svelte with Vite](#Svelte-with-Vite) @@ -76,7 +76,7 @@ properly. The examples below are for reference purposes. ### Svelte with Vite -Cypress Component Testing works with Svelte apps that use Vite 2+ as the +Cypress Component Testing works with Svelte apps that use Vite 4+ as the bundler. #### Vite Configuration @@ -98,7 +98,7 @@ bundler. #### Svelte Vite Sample Apps -- [Svelte 3 Vite 3 with Typescript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/svelte-vite-ts) +- [Svelte 5 Vite 6 with Typescript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/svelte-vite-ts) ### Svelte with Webpack @@ -134,4 +134,4 @@ in manually via the `webpackConfig` option. #### Svelte Webpack Sample Apps -- [Svelte 3 Webpack 5 with Typescript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/svelte-webpack-ts) +- [Svelte 5 Webpack 5 with Typescript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/svelte-webpack-ts) diff --git a/docs/app/component-testing/vue/api.mdx b/docs/app/component-testing/vue/api.mdx index 809505e39e..1fe313e189 100644 --- a/docs/app/component-testing/vue/api.mdx +++ b/docs/app/component-testing/vue/api.mdx @@ -14,11 +14,7 @@ sidebar_label: API ### mount ```js -// Vue 3 import { mount } from 'cypress/vue' - -// Vue 2 -import { mount } from 'cypress/vue2' ``` @@ -64,8 +60,7 @@ import { mount } from 'cypress/vue2' ### MountOptions ([Vue 3 MountingOptions](https://test-utils.vuejs.org/api/#mount) or -[Vue 2 MountingOptions](https://v1.test-utils.vuejs.org/api/options.html)) from -[Vue Test Utils](https://test-utils.vuejs.org/) +[Vue Test Utils](https://test-utils.vuejs.org/)) ### MountReturn diff --git a/docs/app/component-testing/vue/examples.mdx b/docs/app/component-testing/vue/examples.mdx index fd2c305ad3..eb6793a4ec 100644 --- a/docs/app/component-testing/vue/examples.mdx +++ b/docs/app/component-testing/vue/examples.mdx @@ -40,9 +40,6 @@ it('mounts', () => { You can pass props and events to a component by setting `props` in the options: - - - ```js cy.mount(Stepper, { props: { @@ -51,20 +48,6 @@ cy.mount(Stepper, { }) ``` - - - -```js -cy.mount(Stepper, { - propsData: { - initial: 100, - }, -}) -``` - - - - ### Testing Event Handlers Pass a Cypress [spy](/app/guides/stubs-spies-and-clocks#Spies) to an event @@ -501,8 +484,6 @@ Cypress.Commands.add('mount', (component, ...args) => { To use Vue Router, create a command to register the plugin and pass in a custom implementation of the router via the options param. -#### Vue 3 - @@ -603,95 +584,11 @@ promise's resolve before it continues with other commands: -#### Vue 2 - - - - -```js -import { mount } from 'cypress/vue' -import Vue from 'vue' -import VueRouter from 'vue-router' -import { router } from '../../src/router' - -Cypress.Commands.add('mount', (component, options = {}) => { - // Add the VueRouter plugin - Vue.use(VueRouter) - - // Use the router passed in via options, - // or the default one if not provided - options.router = options.router || router - - return mount(component, options) -}) -``` - - - - -```ts -import { mount } from 'cypress/vue' -import VueRouter from 'vue-router' - -type MountParams = Parameters -type OptionsParam = MountParams[1] & { router?: VueRouter } - -declare global { - namespace Cypress { - interface Chainable { - /** - * Helper mount function for Vue Components - * @param component Vue Component or JSX Element to mount - * @param options Options passed to Vue Test Utils - */ - mount(component: any, options?: OptionsParam): Chainable - } - } -} -``` - - - - -```js -import VueRouter from 'vue-router' -import Navigation from './Navigation.vue' -import { routes } from '../router' - -it('home link should be active when url is "/"', () => { - // No need to pass in custom router as default url is '/' - cy.mount(Navigation) - - cy.get('a').contains('Home').should('have.class', 'router-link-active') -}) - -it('login link should be active when url is "/login"', () => { - // Create a new router instance for each test - const router = new VueRouter({ - mode: 'history', - routes, - }) - - // Change location to `/login` - router.push('/login') - - // Pass the already initialized router for use - cy.mount(Navigation, { router }) - - cy.get('a').contains('Login').should('have.class', 'router-link-active') -}) -``` - - - - ### Vuex To use a component that uses [Vuex](https://vuex.vuejs.org/), create a `mount` command that configures a Vuex store for your component. -#### Vue 3 - @@ -783,102 +680,12 @@ it.only('User profile should display user name', () => { -#### Vue 2 - - - - -```js -import { mount } from 'cypress/vue' -import Vuex from 'vuex' -import { getStore } from '../../src/plugins/store' - -Cypress.Commands.add('mount', (component, options = {}) => { - // Setup options object - options.extensions = options.extensions || {} - options.extensions.plugins = options.extensions.plugins || [] - - // Use store passed in from options, or initialize a new one - options.store = options.store || getStore() - - // Add Vuex plugin - options.extensions.plugins.push(Vuex) - - return mount(component, options) -}) -``` - -:::info - -The `getStore` method is a factory method that initializes Vuex and creates a -new store. It is important that the store be initialized with each new test to -ensure changes to the store don't affect other tests. - -::: - - - - -```ts -import { mount } from 'cypress/vue' -import { Store } from 'vuex' - -type MountParams = Parameters -type OptionsParam = MountParams[1] - -declare global { - namespace Cypress { - interface Chainable { - /** - * Helper mount function for Vue Components - * @param component Vue Component or JSX Element to mount - * @param options Options passed to Vue Test Utils - */ - mount( - component: any, - options?: OptionsParam & { store?: Store } - ): Chainable - } - } -} -``` - - - - -```js -import { getStore } from '@/plugins/store' -import UserProfile from './UserProfile.vue' - -it.only('User profile should display user name', () => { - const user = { name: 'test person' } - - // getStore is a factory method that creates a new store - const store = getStore() - - // mutate the store with user - store.commit('setUser', user) - - cy.mount(UserProfile, { - store, - }) - - cy.get('div.name').should('have.text', user.name) -}) -``` - - - - ### Global Components If you have components that are registered globally in the main application file, set them up in your mount command so your component will render them properly: - - - ```js import { mount } from 'cypress/vue' import Button from '../../src/components/Button.vue' @@ -894,25 +701,3 @@ Cypress.Commands.add('mount', (component, options = {}) => { return mount(component, options) }) ``` - - - - -```js -import { mount } from 'cypress/vue2' -import Button from '../../src/components/Button.vue' - -Cypress.Commands.add('mount', (component, options = {}) => { - // Setup options object - options.extensions = options.extensions || {} - options.extensions.components = options.extensions.components || {} - - // Register global components - options.extensions.components['Button'] = Button - - return mount(component, options) -}) -``` - - - diff --git a/docs/app/component-testing/vue/overview.mdx b/docs/app/component-testing/vue/overview.mdx index a4ba6b6ed4..938683de54 100644 --- a/docs/app/component-testing/vue/overview.mdx +++ b/docs/app/component-testing/vue/overview.mdx @@ -15,16 +15,13 @@ sidebar_label: Overview - How to set up component tests in Vue - How to configure Cypress for Vue projects -- How to use Cypress with Vue CLI, Nuxt, Vite, and custom Webpack config ::: ## Framework Support -Cypress Component Testing supports Vue 2+ with the following frameworks: +Cypress Component Testing supports Vue 3+ with the following frameworks: -- [Vue CLI](#Vue-CLI) -- [Nuxt](#Nuxt) Alpha - [Vue with Vite](#Vue-with-Vite) - [Vue with Webpack](#Vue-with-Webpack) @@ -65,82 +62,13 @@ For usage and examples, visit the ## Framework Configuration Cypress Component Testing works out of the box with -[Vue CLI](https://cli.vuejs.org/), [Nuxt](https://nuxtjs.org/), [Vite](https://vitejs.dev/), and a custom [Webpack](https://webpack.js.org/) config. Cypress will automatically detect one of these frameworks during setup and configure them properly. The examples below are for reference purposes. -### Vue CLI - -Cypress Component Testing works with Vue CLI. - -#### Vue CLI Configuration - -:::cypress-config-example - -```ts -{ - component: { - devServer: { - framework: 'vue-cli', - bundler: 'webpack', - }, - }, -} -``` - -::: - -:::caution - -PWA Caveat - -If you use the Vue CLI's PWA feature, there is a known caveat regarding -configuration. See -[here](https://github.com/cypress-io/cypress/issues/15968#issuecomment-819170918) -for more information. - -::: - -#### Sample Vue CLI Apps - -- [Vue 3 CLI 5 with TypeScript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/vue3-cli5-ts) -- [Vue 2 CLI 4 with JavaScript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/vue2-cli4-js) - -### Nuxt - -Cypress Component Testing works with Nuxt 2. Nuxt 3 is not yet supported. - -:::caution - -Nuxt is currently in alpha support for component testing. - -::: - -#### Nuxt Configuration - -:::cypress-config-example - -```ts -{ - component: { - devServer: { - framework: 'nuxt', - bundler: 'webpack', - }, - }, -} -``` - -::: - -#### Nuxt Sample Apps - -- [Vue 2 Nuxt 2 with JavaScript](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/vue2-nuxt2-js) - ### Vue with Vite -Cypress Component Testing works with Vue apps that use Vite 2+ as the bundler. +Cypress Component Testing works with Vue apps that use Vite 4+ as the bundler. #### Vite Configuration diff --git a/docs/app/faq.mdx b/docs/app/faq.mdx index a2774335c1..7c47192281 100644 --- a/docs/app/faq.mdx +++ b/docs/app/faq.mdx @@ -457,7 +457,7 @@ a remote page and does not resolve until all of the external resources complete their loading phase. Because we expect your applications to observe differing load times, this command's default timeout is set to 60000ms. If you visit an invalid url or a -[second unique domain](/app/guides/cross-origin-testing#Different-superdomain-per-test-requires-cyorigin), +[second unique domain](/app/guides/cross-origin-testing#Different-origins-per-test-require-cyorigin), Cypress will log a verbose yet friendly error message. **_In CI, how do I make sure my server has started?_** @@ -1273,8 +1273,7 @@ If you really need to select React components by their name, props, or state, check out [cypress-react-selector](https://github.com/abhinaba-ghosh/cypress-react-selector). -For component testing, we support various different frameworks like Create React -App, Vite, and Next.js for React applications. See the +For component testing, we support various different frameworks like Vite, Webpack, and Next.js for React applications. See the [Framework Configuration Guide](/app/component-testing/component-framework-configuration) for more info. diff --git a/docs/app/guides/cross-origin-testing.mdx b/docs/app/guides/cross-origin-testing.mdx index 0d355dea9f..4a7318267c 100644 --- a/docs/app/guides/cross-origin-testing.mdx +++ b/docs/app/guides/cross-origin-testing.mdx @@ -37,9 +37,6 @@ and we are _mostly_ able to do this. ### What Cypress does under the hood -- Injects - [`document.domain`](https://developer.mozilla.org/en-US/docs/Web/API/Document/domain) - into `text/html` pages. - Proxies all HTTP / HTTPS traffic. - Changes the hosted URL to match that of the application under test. - Uses the browser's internal APIs for network level traffic. @@ -61,7 +58,7 @@ Cypress must assign and manage browser certificates to be able to modify the traffic in real time. You'll notice Chrome display a warning that the 'SSL certificate does not match'. This is expected behavior. Under the hood we act as our own CA authority and issue certificates dynamically in order to intercept requests -otherwise impossible to access. We only do this for the superdomain currently +otherwise impossible to access. We only do this for the origin currently under test, and bypass other traffic. Note, that Cypress allows you to optionally specify CA / client certificate @@ -78,39 +75,37 @@ It's important to note that although we do our **very best** to ensure your application works normally inside of Cypress, there _are_ some limitations you need to be aware of. -- [Different superdomain per test requires cy.origin command](#Different-superdomain-per-test-requires-cyorigin) +- [Different origins per test require cy.origin()](#Different-origins-per-test-require-cyorigin) - [Cross-origin iframes are not supported](#Cross-origin-iframes) - [Navigating from HTTPS to HTTP will error](#Insecure-Content) - [Cypress requires that the URLs navigated to have the same port](#Same-port-per-test) -### Different superdomain per test requires cy.origin +### Different origins per test require `cy.origin()` Cypress changes its own host URL to match that of your applications. With the exception of `cy.origin`, Cypress requires that the URLs navigated to have the -[same superdomain](/app/guides/cross-origin-testing#Parts-of-a-URL) for the +same [origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin) for the entirety of a single test. -If you attempt to visit two different superdomains, the `cy.origin` command must +If you attempt to visit two different origins, the `cy.origin` command must be used to wrap Cypress commands of the second visited domain. Otherwise, Cypress commands will timeout after the navigation and will eventually error. This is because the commands that were expected to run on the second domain are actually being run on the first domain. -Without `cy.origin`, you can visit different superdomains in _different_ tests, -but not in the _same_ test. Please read our -[Cross Origin Testing Guide](/app/guides/cross-origin-testing) for more -information. +Without `cy.origin()`, you can visit different origins in _different_ tests, +but not in the _same_ test. #### Examples of test cases that will error without the use of `cy.origin` 1. [`.click()`](/api/commands/click) an `` with an `href` to a different - superdomain with subsequent Cypress commands being run. + origin with subsequent Cypress commands being run. 2. [`.submit()`](/api/commands/submit) a `
` that causes your web server to - redirect you a different superdomain where additional Cypress commands are + redirect you to a different origin where additional Cypress commands are run. 3. Issue a JavaScript redirect in your application, such as - `window.location.href = '...'`, to a different superdomain where additional - Cypress commands are run. + `window.location.href = '...'`, which navigates to a different origin + where additional Cypress commands are run. In each of these situations, Cypress will lose the ability to automate your application and will error via command timeout unless the `cy.origin` command is @@ -119,17 +114,6 @@ used. Read on to learn about [working around these common problems](#Common-Workarounds). -#### What is a superdomain? - -But what is same superdomain? It's actually very similar to that of same -origin! Two URLs have the same origin if the **protocol**, **port** (if specified), and -**host** match. Cypress automatically handles hosts of the same superdomain by -injecting the -[`document.domain`](https://developer.mozilla.org/en-US/docs/Web/API/Document/domain) -property into the visited `text/html` pages. This is why navigations without the -use of the [`cy.origin()`](/api/commands/origin) command are solely scoped to the -same superdomain. - #### Parts of a URL @@ -142,38 +126,33 @@ chart to help clarify the differences! alt="Diagram showing the parts of a URL including href broken into protocol, host, pathname, hash and smaller components of hostname, port, path, and search with and example URL" /> -Given the URLs below, all have the same superdomain compared to -`https://www.cypress.io`. - -- `https://cypress.io` -- `https://docs.cypress.io` -- `https://example.cypress.io/commands/querying` +##### Origin -The URLs below, however, will have different superdomains/origins compared to -`https://www.cypress.io`. +An `origin` is comprised of a URL's `scheme`, `hostname`, _and_ `port`. Given the URLs +below, all have the same origin compared to `https://www.cypress.io`: -- `http://www.cypress.io` (Different protocol) -- `https://docs.cypress.io:81` (Different port) -- `https://www.auth0.com/` (Different host of different superdomain) +- `https://www.cypress.io/cloud` +- `https://www.cypress.io/app` -The `http://localhost` URLs differ if their ports are different. For example, -the `http://localhost:3000` URL is considered to be a different origin from the -`http://localhost:8080` URL. +But the following have different origins compared to `https://www.cypress.io`: -The rules are: +- `http://www.cypress.io` (different `scheme`) +- `https://docs.cypress.io` (different `hostname` due to the subdomain) +- `https://www.auth0.com` (different `hostname`) +- `https://www.cypress.io:81` (different `port`) :::danger You **cannot** [visit](/api/commands/visit) -two domains of different superdomains in the same test and continue to interact with -the page without the use of the [`cy.origin()`](/api/commands/origin) command. +two different origins in the same test and continue to interact with the page without +the use of the [`cy.origin()`](/api/commands/origin) command. ::: :::tip You **can** [visit](/api/commands/visit) -two or more domains of different origin in **different** tests without needing [`cy.origin()`](/api/commands/origin). +two or more origins in **different** tests without needing [`cy.origin()`](/api/commands/origin). ::: For practical purposes, this means the following: @@ -182,16 +161,16 @@ For practical purposes, this means the following: // This test will run without error it('navigates', () => { cy.visit('https://www.cypress.io') - cy.visit('https://docs.cypress.io') + cy.visit('https://www.cypress.io/app') cy.get('selector') // yup all good }) ``` ```javascript -// this will error because cypress-dx.com doesn't match the cypress.io superdomain +// this will error because the origin https://docs.cypress.io doesn't match the origin https://www.cypress.io it('navigates', () => { cy.visit('https://www.cypress.io') - cy.visit('https://www.cypress-dx.com') + cy.visit('https://docs.cypress.io') cy.get('selector') }) ``` @@ -202,8 +181,8 @@ the sequential command should run against: ```javascript it('navigates', () => { cy.visit('https://example.cypress.io') - cy.visit('https://www.cypress-dx.com') - cy.origin('https://www.cypress-dx.com', () => { + cy.visit('https://docs.cypress.io') + cy.origin('https://docs.cypress.io', () => { cy.get('selector') // yup all good }) }) @@ -312,7 +291,7 @@ and break down how to work around them in Cypress. ### External Navigation The most common situation where you might encounter this error is when you click -on an `` that navigates to another superdomain. +on an `` that navigates to another origin. ```html title="index.html" @@ -328,14 +307,14 @@ cy.get('selector').should('exist') // Cypress errors :::warning -We don't recommend visiting a superdomain that you don't control in your tests +We don't recommend visiting an origin that you don't control in your tests which you can read more about [here](/app/core-concepts/best-practices#Visiting-External-Sites) ::: -If you control this superdomain, either by owning the hosted instance -or by other means, we recommend testing this superdomain with `cy.origin`. +If you control this origin, either by owning the hosted instance +or by other means, we recommend testing this origin with `cy.origin`. ```javascript title="test.cy.js" cy.visit('http://localhost:8080') // where your web server + HTML is hosted @@ -346,7 +325,7 @@ cy.origin('https://example.cypress.io', () => { }) ``` -If you're not in control of this superdomain, we recommend you test that the `href` +If you're not in control of this origin, we recommend you test that the `href` property is correct instead of performing the navigation. This will help lead to more deterministic tests. @@ -391,7 +370,7 @@ cy.get('form').submit() // submit the form! ``` If your back end server handling the `/submit` route does a `30x` redirect to a -different superdomain, you'll need to use the `cy.origin` command if running +different origin, you'll need to use the `cy.origin` command if running additional Cypress commands after submitting the form. ```javascript title="routes.js" @@ -539,7 +518,7 @@ Setting `chromeWebSecurity` to `false` in Chrome-based browsers allows you to do the following: - Display insecure content -- Navigate to any superdomain without cross-origin errors with or without +- Navigate to any origin without cross-origin errors with or without `cy.origin` - Access cross-origin iframes that are embedded in your application @@ -592,7 +571,7 @@ Want to enable `experimentalModifyObstructiveThirdPartyCode`? Let's do it! ## Other workarounds -There are other ways of testing the interaction between two superdomains. The +There are other ways of testing the interaction between two origins. The browser has a natural security barrier called `origin policy` this means that state like `localStorage`, `cookies`, `service workers` and many other APIs are not shared between them anyways. Cypress does offer APIs around `localStorage`, @@ -602,7 +581,7 @@ As a best practice, you should not visit or interact with any website not under your control. If your organization uses Single Sign On (SSO) or OAuth then you might choose to -test a 3rd party service other than your superdomain, which can be tested with +test a 3rd party service other than your origin, which can be tested with [`cy.origin()`](/api/commands/origin). We've written several other guides specifically about handling this situation. diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx index c192898d46..9a302cf5eb 100644 --- a/docs/app/references/changelog.mdx +++ b/docs/app/references/changelog.mdx @@ -8,6 +8,92 @@ sidebar_label: Changelog # Changelog +## 14.0.0 + +_Released 1/16/2025_ + +**Summary:** + +Cypress v14.0.0 improves performance of component testing and adds support for new framework and dev server versions. +v14.0.0 also includes breaking changes to `cy.origin` that are necessary to handle +[Chrome's deprecation of `document.domain` injection](https://developer.chrome.com/blog/document-domain-setter-deprecation), which should fix issues for some users in recent Chrome versions. Support for older versions of Node.js, Linux distributions, browsers and component testing frameworks and dev servers is removed. + +Overall, we don't anticipate this release to be too disruptive for most users. We recommend bumping your version to see if your +tests still run as expected. As always, open any issues you find [here](https://github.com/cypress-io/cypress/issues/new?assignees=&labels=&projects=&template=1-bug-report.yml). + +**Breaking Changes:** + +:::info + +Refer to the [v14 Migration Guide](/app/references/migration-guide#Migrating-to-Cypress-140) for help migrating your code. + +::: + +- Removed support for Node.js 16 and Node.js 21. Addresses [#29930](https://github.com/cypress-io/cypress/issues/29930). +- Upgraded bundled Node.js version from `18.17.0` to `20.18.1`. Addresses [#29547](https://github.com/cypress-io/cypress/issues/29547). +- Prebuilt binaries for Linux are no longer compatible with Linux distributions based on glibc `<2.28`, for example: Ubuntu 14-18, RHEL 7, CentOS 7, Amazon Linux 2. Addresses [#29601](https://github.com/cypress-io/cypress/issues/29601). +- Cypress now only officially supports the latest 3 major versions of Chrome, Firefox, and Edge - older browser versions may still work, but we recommend keeping your browsers up to date to ensure compatibility with Cypress. A warning will no longer be displayed on browser selection in the Launchpad for any 'unsupported' browser versions. Additionally, the undocumented `minSupportedVersion` property has been removed from `Cypress.browser`. Addressed in [#30462](https://github.com/cypress-io/cypress/pull/30462). +- The `cy.origin()` command must now be used when navigating between subdomains. Because this is a fairly disruptive change for users who frequently navigate between subdomains, a new configuration option is being introduced. `injectDocumentDomain` can be set to `true` in order to re-enable the injection of `document.domain` setters in Cypress. This configuration option is marked as deprecated and you'll receive a warning when Cypress is launched with this option set to `true`. It will be removed in Cypress 15. Addressed in [#30770](https://github.com/cypress-io/cypress/pull/30770). +- The `experimentalSkipDomainInjection` configuration has been removed and replaced with an `injectDocumentDomain` configuration. Addressed in [#30770](https://github.com/cypress-io/cypress/pull/30770). +- It is no longer possible to make a `fetch` or `XMLHttpRequest` request from the `about:blank` page in Electron (i.e. `cy.window().then((win) => win.fetch(''))`). You must use `cy.request` instead or perform some form of initial navigation via `cy.visit()`. Addressed in [#30394](https://github.com/cypress-io/cypress/pull/30394). +- The `experimentalJustInTimeCompile` configuration option for component testing has been replaced with a `justInTimeCompile` option that is `true` by default. This option will only compile resources directly related to your spec, compiling them 'just-in-time' before spec execution. This should result in improved memory management and performance for component tests in `cypress open` and `cypress run` modes, in particular for large component testing suites. `justInTimeCompile` is now only supported for [`webpack`](https://www.npmjs.com/package/webpack). Addresses [#30234](https://github.com/cypress-io/cypress/issues/30234). Addressed in [#30641](https://github.com/cypress-io/cypress/pull/30641). +- Cypress Component Testing no longer supports: + - `create-react-app`. Addresses [#30028](https://github.com/cypress-io/cypress/issues/30028). + - `@vue/cli-service`. Addresses [#30481](https://github.com/cypress-io/cypress/issues/30481). + - `Angular` versions 13, 14, 15, and 16. The minimum supported version is now `17.2.0` in order to fully support Angular [signals](https://angular.dev/guide/signals). Addresses [#29582](https://github.com/cypress-io/cypress/issues/29582). Addressed in [#30539](https://github.com/cypress-io/cypress/pull/30539). + - `Next.js` versions 10, 11, 12, and 13. Addresses [#29583](https://github.com/cypress-io/cypress/issues/29583). + - `Nuxt.js` version 2. Addresses [#30468](https://github.com/cypress-io/cypress/issues/30468). + - `React` versions 16 and 17. Addresses [#29607](https://github.com/cypress-io/cypress/issues/29607). + - `Svelte` versions 3 and 4. Addresses [#30492](https://github.com/cypress-io/cypress/issues/30492) and [#30692](https://github.com/cypress-io/cypress/issues/30692). + - `Vue` version 2. Addresses [#30295](https://github.com/cypress-io/cypress/issues/30295). +- The `cypress/react18` test harness is no longer included in the Cypress binary. Instead, React 18 support is now shipped with `cypress/react`! Addresses [#29607](https://github.com/cypress-io/cypress/issues/29607). +- The `cypress/angular-signals` test harness is no longer included in the Cypress binary. Instead, signals support is now shipped with `cypress/angular`! This requires `rxjs` to be installed as a `peerDependency`. Addresses [#29606](https://github.com/cypress-io/cypress/issues/29606). +- The Cypress configuration wizard for Component Testing supports TypeScript 4.0 or greater. Addresses [#30493](https://github.com/cypress-io/cypress/issues/30493). +- `@cypress/webpack-dev-server` no longer supports `webpack-dev-server` version 3. Additionally, `@cypress/webpack-dev-server` now ships with `webpack-dev-server` version 5 by default. `webpack-dev-server` version 4 will need to be installed alongside Cypress if you are still using `webpack` version 4. Addresses [#29308](https://github.com/cypress-io/cypress/issues/29308), [#30347](https://github.com/cypress-io/cypress/issues/30347), and [#30141](https://github.com/cypress-io/cypress/issues/30141). +- `@cypress/vite-dev-server` no longer supports `vite` versions 2 and 3. Addresses [#29377](https://github.com/cypress-io/cypress/issues/29377) and [#29378](https://github.com/cypress-io/cypress/issues/29378). +- The `delayMs` option of `cy.intercept()` has been removed. This option was deprecated in Cypress 6.4.0. Please use the `delay` option instead. Addressed in [#30463](https://github.com/cypress-io/cypress/pull/30463). +- The `experimentalFetchPolyfill` configuration option was removed. This option was deprecated in Cypress 6.0.0. We recommend using `cy.intercept()` for handling fetch requests. Addressed in [#30466](https://github.com/cypress-io/cypress/pull/30466). +- We removed yielding the second argument of `before:browser:launch` as an array of browser arguments. This behavior has been deprecated since Cypress 4.0.0. Addressed in [#30460](https://github.com/cypress-io/cypress/pull/30460). +- The `cypress open-ct` and `cypress run-ct` CLI commands were removed. Please use `cypress open --component` or `cypress run --component` respectively instead. Addressed in [#30456](https://github.com/cypress-io/cypress/pull/30456) +- The undocumented methods `Cypress.backend('firefox:force:gc')` and `Cypress.backend('log:memory:pressure')` were removed. Addresses [#30222](https://github.com/cypress-io/cypress/issues/30222). + +**Deprecations:** + +- The `resourceType` option on `cy.intercept` has been deprecated. We anticipate the resource types to change or be completely removed in the future. Our intention is to replace essential functionality dependent on the `resourceType` within Cypress in a future version (like hiding network logs that are not fetch/xhr). Please leave feedback on any essential uses of `resourceType` + in this [GitHub issue](https://github.com/cypress-io/cypress/issues/30447). Addresses [#30433](https://github.com/cypress-io/cypress/issues/30433). +- The new `injectDocumentDomain` configuration option is released as deprecated. It will be removed in Cypress 15. Addressed in [#30770](https://github.com/cypress-io/cypress/pull/30770). + +**Features:** + +- `injectDocumentDomain`, a new configuration option, can be set to `true` in order to re-enable the injection of `document.domain` setters in Cypress. Addressed in [#30770](https://github.com/cypress-io/cypress/pull/30770). +- Cypress Component Testing now supports: + - `React` version 19. Addresses [#29470](https://github.com/cypress-io/cypress/issues/29470). + - `Angular` version 19. Addresses [#30175](https://github.com/cypress-io/cypress/issues/30175). + - `Next.js` version >=15.0.4. Versions 15.0.0 - 15.0.3 depend on the React 19 Release Candidate and are not officially supported by Cypress, but should still work. Addresses [#30445](https://github.com/cypress-io/cypress/issues/30445). + - `Svelte` version 5. Addresses [#29641](https://github.com/cypress-io/cypress/issues/29641). + - `Vite` version 6. Addresses [#30591](https://github.com/cypress-io/cypress/issues/30591). + +**Bugfixes:** + +- Elements with `display: contents` will no longer use box model calculations for visibility, and correctly show as visible when they are visible. Fixed in [#29680](https://github.com/cypress-io/cypress/pull/29680). Fixes [#29605](https://github.com/cypress-io/cypress/issues/29605). +- Fixed a visibility issue when the element is positioned `static` or `relative` and the element's offset parent is positioned `absolute`, a descendent of the ancestor, and has no clippable overflow. Fixed in [#29689](https://github.com/cypress-io/cypress/pull/29689). Fixes [#28638](https://github.com/cypress-io/cypress/issues/28638). +- Fixed a visibility issue for elements with `textContent` but without a width or height. Fixed in [#29688](https://github.com/cypress-io/cypress/pull/29688). Fixes [#29687](https://github.com/cypress-io/cypress/issues/29687). +- Elements whose parent elements has `overflow: clip` and no height/width will now correctly show as hidden. Fixed in [#29778](https://github.com/cypress-io/cypress/pull/29778). Fixes [#23852](https://github.com/cypress-io/cypress/issues/23852). +- The CSS pseudo-class `:dir()` is now supported when testing in Electron. Addresses [#29766](https://github.com/cypress-io/cypress/issues/29766). + +**Misc:** + +- Removed some component testing API stubs that were removed in [Cypress v11.0.0](/app/references/migration-guide#Component-Testing-Updates). Addressed in [#30696](https://github.com/cypress-io/cypress/pull/30696). Addresses [#30623](https://github.com/cypress-io/cypress/issues/30623). + +**Dependency Updates:** + +- Upgraded `electron` from `27.3.10` to `33.2.1`. Addresses [#29547](https://github.com/cypress-io/cypress/issues/29547) and [#30561](https://github.com/cypress-io/cypress/issues/30561). +- Upgraded `@electron/rebuild` from `3.2.10` to `3.7.1`. Addresses [#28766](https://github.com/cypress-io/cypress/issues/28766) and [#30632](https://github.com/cypress-io/cypress/issues/30632). +- Upgraded bundled Chromium version from `118.0.5993.159` to `130.0.6723.137`. Addresses [#29547](https://github.com/cypress-io/cypress/issues/29547) and [#30561](https://github.com/cypress-io/cypress/issues/30561). +- Updated `jQuery` from `3.4.1` to `3.7.1`. Addressed in [#30345](https://github.com/cypress-io/cypress/pull/30345). +- Updated `react` from `17.0.2` to `18.3.1` and `react-dom` from `17.0.2` to `18.3.1`. Addresses [#30511](https://github.com/cypress-io/cypress/issues/30511). +- Upgraded [`@vue/test-utils`](https://www.npmjs.com/package/@vue/test-utils) from `2.3.2` to `2.4.6`. Addresses [#26628](https://github.com/cypress-io/cypress/issues/26628). + ## 13.17.0 _Released 12/17/2024_ @@ -56,6 +142,8 @@ _Released 11/19/2024_ ## 13.15.2 +## 13.15.2 + _Released 11/5/2024_ **Bugfixes:** @@ -144,7 +232,9 @@ _Released 8/27/2024_ - Added new [`experimentalJustInTimeCompile`](/app/references/experiments#Configuration) - configuration option for component testing. This option will only compile resources directly related to your spec, compiling them 'just-in-time' before spec execution. This should result in improved memory management and performance for component tests in `cypress open` and `cypress run` modes, in particular for large component testing suites. [`experimentalJustInTimeCompile`](/app/references/experiments#Configuration) is currently supported for [`webpack`](https://www.npmjs.com/package/webpack) and [`vite`](https://www.npmjs.com/package/vite). Addresses [#29244](https://github.com/cypress-io/cypress/issues/29244). + configuration option for component testing. This option will only compile resources directly related to your spec, compiling + them 'just-in-time' before spec execution. This should result in improved memory management and performance for component + tests in `cypress open` and `cypress run` modes, in particular for large component testing suites. [`experimentalJustInTimeCompile`](/app/references/experiments#Configuration) is currently supported for [`webpack`](https://www.npmjs.com/package/webpack) and [`vite`](https://www.npmjs.com/package/vite). Addresses [#29244](https://github.com/cypress-io/cypress/issues/29244). - `.type({upArrow})` and `.type({downArrow})` now also works for date, month, week, time, datetime-local and range input types. Addresses [#29665](https://github.com/cypress-io/cypress/issues/29665). - Added a `CYPRESS_SKIP_VERIFY` flag to enable suppressing Cypress verification checks. Addresses [#22243](https://github.com/cypress-io/cypress/issues/22243). - Updated the protocol to allow making Cloud API requests. Addressed in [#30066](https://github.com/cypress-io/cypress/pull/30066). @@ -1460,11 +1550,11 @@ _Released 1/24/2023_ will help us make decisions to improve memory issues. Addresses [#23391](https://github.com/cypress-io/cypress/issues/23391). - Added new - [`experimentalSkipDomainInjection`](/app/references/experiments#Experimental-Skip-Domain-Injection) + `experimentalSkipDomainInjection` configuration option to disable Cypress from setting `document.domain` on injection, allowing users to test Salesforce domains. If you believe you are having `document.domain` issues, please see the - [`experimentalSkipDomainInjection`](/app/references/experiments#Experimental-Skip-Domain-Injection) + `experimentalSkipDomainInjection` guide. This config option is end-to-end only. Addresses [#2367](https://github.com/cypress-io/cypress/issues/2367), [#23958](https://github.com/cypress-io/cypress/issues/23958), diff --git a/docs/app/references/configuration.mdx b/docs/app/references/configuration.mdx index 33a3117ebd..b9278448e1 100644 --- a/docs/app/references/configuration.mdx +++ b/docs/app/references/configuration.mdx @@ -191,16 +191,17 @@ creating `e2e` and `component` objects inside your Cypress configuration. These options are available to be specified inside the `e2e` configuration object: -| Option | Default | Description | -| ------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `baseUrl` | `null` | URL used as prefix for [`cy.visit()`](/api/commands/visit) or [`cy.request()`](/api/commands/request) command's URL. | -| `setupNodeEvents` | `null` | Function in which node events can be registered and config can be modified. Takes the place of the (removed) pluginFile option. [Please read the notes for examples on using this.](#setupNodeEvents) | -| `supportFile` | `cypress/support/e2e.{js,jsx,ts,tsx}` | Path to file to load before spec files load. This file is compiled and bundled. (Pass `false` to disable) | -| `specPattern` | cypress/e2e/\*\*/\*.cy.\{js,jsx,ts,tsx\} | A String or Array of glob patterns of the test files to load. | -| `excludeSpecPattern` | `*.hot-update.js` | A String or Array of glob patterns used to ignore test files that would otherwise be shown in your list of tests. [Please read the notes on using this.](#excludeSpecPattern) | -| `experimentalRunAllSpecs` | `false` | Enables the "Run All Specs" UI feature, allowing the execution of multiple specs sequentially. | -| `slowTestThreshold` | `10000` | Time, in milliseconds, to consider a test "slow" during `cypress run`. A slow test will display in orange text in the default reporter. | -| `testIsolation` | `true` | Whether or not [test isolation](/app/core-concepts/writing-and-organizing-tests#Test-Isolation) is enabled to ensure a clean browser context between tests. | +| Option | Default | Description | +| --------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `baseUrl` | `null` | URL used as prefix for [`cy.visit()`](/api/commands/visit) or [`cy.request()`](/api/commands/request) command's URL. | +| `setupNodeEvents` | `null` | Function in which node events can be registered and config can be modified. Takes the place of the (removed) pluginFile option. [Please read the notes for examples on using this.](#setupNodeEvents) | +| `supportFile` | `cypress/support/e2e.{js,jsx,ts,tsx}` | Path to file to load before spec files load. This file is compiled and bundled. (Pass `false` to disable) | +| `specPattern` | cypress/e2e/\*\*/\*.cy.\{js,jsx,ts,tsx\} | A String or Array of glob patterns of the test files to load. | +| `excludeSpecPattern` | `*.hot-update.js` | A String or Array of glob patterns used to ignore test files that would otherwise be shown in your list of tests. [Please read the notes on using this.](#excludeSpecPattern) | +| `experimentalRunAllSpecs` | `false` | Enables the "Run All Specs" UI feature, allowing the execution of multiple specs sequentially. | +| `slowTestThreshold` | `10000` | Time, in milliseconds, to consider a test "slow" during `cypress run`. A slow test will display in orange text in the default reporter. | +| `testIsolation` | `true` | Whether or not [test isolation](/app/core-concepts/writing-and-organizing-tests#Test-Isolation) is enabled to ensure a clean browser context between tests. | +| `injectDocumentDomain` deprecated | `false` | Instructs Cypress to use the `document.domain` property to reduce the need for [`cy.origin`](/api/commands/origin). [Please read the notes on using this.](#injectDocumentDomain) | :::cypress-config-example @@ -223,6 +224,7 @@ object: | ------------------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `devServer` | `null` | Required option used to configure the component testing dev server. [Please read the notes for examples on using this.](#devServer) | | `indexHtmlFile` | `cypress/support/component-index.html` | This is where Cypress renders your components and allows you to add in global assets, such as styles, fonts, and external scripts. | +| `justInTimeCompile` | `true` | Compile resources directly related to your spec for webpack, compiling them 'just-in-time' before spec execution. | | `setupNodeEvents` | `null` | Function in which node events can be registered and config can be modified. Takes the place of the (removed) plugins file. [Please read the notes for examples on using this.](#setupNodeEvents) | | `supportFile` | `cypress/support/component.js` | Path to file to load before spec files load. This file is compiled and bundled. (Pass `false` to disable) | | `specPattern` | \*\*/\*.cy.\{js,jsx,ts,tsx\} | A glob pattern String or Array of glob pattern Strings of the spec files to load.

Note that any files found matching the `e2e.specPattern` value will be automatically **excluded.** | @@ -595,6 +597,54 @@ The `**/node_modules/**` pattern is automatically added to `excludeSpecPattern` and does not need to be specified (and can't be overridden). See [`e2e`](#e2e) or [`component`](#component) testing-specific options. +### injectDocumentDomain + +This option is deprecated, and will be removed in Cypress. 15 + +Set this configuration option to `true` to instruct Cypress to +[inject document.domain](/app/guides/cross-origin-testing#What-Cypress-does-under-the-hood) +into your test application. This can reduce the need for `cy.origin()` when [navigating +between subdomains](/app/guides/cross-origin-testing), but comes with compatibility +caveats for some sites. + +This configuration option is provided to ease the transition between `cy.origin()`'s behavior +in Cypress 13 and the default behavior in Cypress 14. It will be removed in Cypress 15. +[Read the Cypress 14 migration guide](/app/references/migration-guide#Migrating-to-Cypress-140) to understand how to update your tests to remove +the need to set this flag. + +This configuration value _must_ be set to true if you are running tests with experimental +WebKit support, as `cy.origin` is not yet supported in WebKit. + +:::caution + +#### Known Incompatibilities + +Setting this configuration value to `true` can cause the application you are testing +to behave in unexpected ways. This is especially true if a site your tests visit +sets the [`Origin-Agent-Cluster`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin-Agent-Cluster) +header. + +At this point in time, we are aware of the following sites that cannot be tested properly +if this option is set to `true`: + +- Azure AD B2C authentication workflows +- Salesforce +- Google + +::: + +:::cypress-config-example + +```js +{ + e2e: { + injectDocumentDomain: true + } +} +``` + +::: + ### isInteractive You can open Cypress in the interactive mode via the `cypress open` command, and @@ -721,6 +771,7 @@ DEBUG=cypress:cli,cypress:data-context:sources:FileDataSource,cypress:data-conte | Version | Changes | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| [14.0.0](/app/references/changelog#14-0-0) | Added support for re-enabling superdomain navigation with the `injectDocumentDomain` configuration option | | [13.16.0](/app/references/changelog#13-16-0) | Added `defaultBrowser` option. | | [13.4.0](/app/references/changelog#13-4-0) | Added support for configuring the Experimental Flake Detection strategy via `retries.experimentalStrategy` and `retries.experimentalOptions`. | | [13.0.0](/app/references/changelog#13-0-0) | Removed `nodeVersion` option. | diff --git a/docs/app/references/experiments.mdx b/docs/app/references/experiments.mdx index bfcce79c4a..1734e01569 100644 --- a/docs/app/references/experiments.mdx +++ b/docs/app/references/experiments.mdx @@ -263,102 +263,26 @@ creating `e2e` and `component` objects inside your Cypress configuration. These experiments are available to be specified inside the `e2e` configuration object: -| Option | Default | Description | -| --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------- | -| `experimentalStudio` | `false` | Generate and save commands directly to your test suite by interacting with your app as an end user would. | -| `experimentalRunAllSpecs` | `false` | Enables the "Run All Specs" UI feature, allowing the execution of multiple specs sequentially. | -| `experimentalOriginDependencies` | `false` | Enables support for `Cypress.require` within `cy.origin`. | -| `experimentalSkipDomainInjection` | `null` | Removes injecting `document.domain` into `text/html` pages for any sites that match the provided patterns. | - -#### Experimental Skip Domain Injection - -Under the hood, Cypress -[injects document.domain](/app/guides/cross-origin-testing#What-Cypress-does-under-the-hood) -into your test application to lessen the burden of navigation. This is well -described in our [Cross Origin Testing](/app/guides/cross-origin-testing) -guide. However, some sites have compatibility issues with this feature. - -The `experimentalSkipDomainInjection` option disables injecting -`document.domain` inside Cypress. When enabled, all cross-origin/subdomain -navigation must use `cy.origin()`, which may make tests a bit more verbose. We -only recommend including your site pattern if you are having issues running -Cypress out of the box and suspect setting `document.domain` is interfering with -your site's ability to render properly. - -Before enabling, verify your application is not implementing frame busting -techniques, which you can mitigate with the -[`modifyObstructiveCode`](/app/references/configuration#modifyObstructiveCode) -and -[`experimentalModifyObstructiveThirdPartyCode`](/app/guides/cross-origin-testing#Modifying-Obstructive-Third-Party-Code) -flags. - -At this point in time, we are aware of the following sites that require the -`experimentalSkipDomainInjection` option to be set to be tested properly: - -- Google -- Salesforce - -This flag can be enabled by passing an array of origin URLs or -[minimatch](https://github.com/isaacs/minimatch) glob patterns: - -:::cypress-config-example - -```js -{ - e2e: { - experimentalSkipDomainInjection: [ - '*.salesforce.com', - '*.force.com', - '*.google.com', - ] - } -} -``` - -::: - -If using other Salesforce domains, such as -[enhanced domains](https://help.salesforce.com/s/articleView?id=sf.domain_name_enhanced.htm&type=5), -you will need to add the correct matching glob pattern. +| Option | Default | Description | +| -------------------------------- | ------- | --------------------------------------------------------------------------------------------------------- | +| `experimentalStudio` | `false` | Generate and save commands directly to your test suite by interacting with your app as an end user would. | +| `experimentalRunAllSpecs` | `false` | Enables the "Run All Specs" UI feature, allowing the execution of multiple specs sequentially. | +| `experimentalOriginDependencies` | `false` | Enables support for `Cypress.require` within `cy.origin`. | ### Component Testing These experiments are available to be specified inside the `component` configuration object: -| Option | Default | Description | -| ------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `experimentalSingleTabRunMode` | `false` | Run all specs in a single tab, instead of creating a new tab per spec. This can improve run mode performance, but can impact spec isolation and reliability on large test suites. | -| `experimentalJustInTimeCompile` | `false` | Enables Just-In-Time (JIT) compiling for component testing, which will only compile assets related to the spec before the spec is run. Currently supported for Vite and Webpack. | - -#### Experimental Just-In-Time Compile - -By default, Cypress compiles all specs used by component testing before allowing any spec to run. This works fine for smaller projects most of the time. - -However, as a component testing suite grows, the dev server (`vite` or `webpack-dev-server`, depending on your application) also grows with it. This can get to a point where the dev server grows so large that it consumes a large majority of CPU and memory resources, leading to: - -- Out Of Memory (OOM) errors. -- `chunk load error`, specific to Webpack where parts of the bundle fail to load. -- long run times while running component tests in CI in `cypress run` mode. -- Unable to efficiently develop tests in `cypress open` mode because the initial and recompiling times for specs and related components are extremely long. -- Inability to leverage [Smart orchestration](/cloud/features/smart-orchestration/overview) effectively to scale resources due to all assets being compiled into the dev server regardless of what specs are run. - -The `experimentalJustInTimeCompile` option is designed to remedy this problem. Enabling this option will enable Just-In-Time (JIT) compiling for component testing, which will only compile assets and resources related to the spec before the spec is run. This is applicable in both `open` and `run` modes. - -In `open` and `run` modes, the dev server will start up when the Cypress application starts with the component testing type, but will only compile the spec once it is selected or run. When a different spec is run, the different spec is then compiled, omitting the previously run spec from the dev server. - -This makes developing your current spec much faster in `open` mode when it comes to initial compiling and recompiling, with a minor tradeoff being to recompile when you switch specs. - -This also significantly reduces the memory requirements needed to run your tests in `run` mode, with a tradeoff being that your tests might run slightly slower since the dev server needs to recompile. If time is a factor, [Smart orchestration](/cloud/features/smart-orchestration/overview) can now be effectively used to parallelize your component testing runs on smaller infrastructure since the dev server only compiles what is needed to run the spec. - -We are using `experimentalJustInTimeCompile` internally within Cypress for our larger component testing suites and have noticed significant reductions in memory when running `cypress run` mode and have gained significantly faster compile times when leveraging `cypress open` to develop our tests. - -If you are using this experiment and would like to leave feedback, please comment on our [github discussion](https://github.com/cypress-io/cypress/discussions/30024). +| Option | Default | Description | +| ------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `experimentalSingleTabRunMode` | `false` | Run all specs in a single tab, instead of creating a new tab per spec. This can improve run mode performance, but can impact spec isolation and reliability on large test suites. | ## History | Version | Changes | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| [14.0.0](/app/references/changelog#14-0-0) | Removed `experimentalJustInTimeCompile` and `experimentalSkipDomainInjection` and made it default behavior. | | [13.14.0](/app/references/changelog#13-14-0) | Added support for configuring the Experimental Just-In-Time (JIT) Compiling for component testing via `experimentalJustInTimeCompile`. | | [13.4.0](/app/references/changelog#13-4-0) | Added support for configuring the Experimental Flake Detection strategy via `retries.experimentalStrategy` and `retries.experimentalOptions`. | | [12.6.0](/app/references/changelog#12-6-0) | Removed `require`/`import` and added `Cypress.require` for `experimentalOriginDependencies`. | diff --git a/docs/app/references/launching-browsers.mdx b/docs/app/references/launching-browsers.mdx index 90eccba08e..97d4aab9d2 100644 --- a/docs/app/references/launching-browsers.mdx +++ b/docs/app/references/launching-browsers.mdx @@ -59,11 +59,14 @@ browser by using the drop down near the top right corner: ### Browser versions supported -Cypress supports the browser versions below: +Cypress officially supports the latest 3 major versions of Chrome, Firefox, and Edge. +(For example, if the stable release of Chrome was 130, Cypress would officially support Chrome 128, 129, and 130.) -- Chrome 64 and above. Chrome 80 and above is required for `cypress open` usage. -- Edge 80 and above. -- Firefox 91 and above. +See each browser's official release schedule for more information. + +- [Chrome Release Schedule](https://chromiumdash.appspot.com/schedule) +- [Firefox Release Schedule](https://whattrainisitnow.com/release/?version=release) +- [Edge Release Schedule](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-release-schedule#microsoft-edge-releases) ### Download specific Chrome version diff --git a/docs/app/references/migration-guide.mdx b/docs/app/references/migration-guide.mdx index 953576973f..598716c842 100644 --- a/docs/app/references/migration-guide.mdx +++ b/docs/app/references/migration-guide.mdx @@ -8,6 +8,347 @@ sidebar_label: 'Migration Guide' # Migration Guide +## Migrating to Cypress 14.0 + +This guide details the code changes needed to migrate to Cypress +version 14. +[See the full changelog for version v14.0](/app/references/changelog#14-0-0). + +### Node.js 18+ support + +Cypress comes bundled with its own +[Node.js version](https://github.com/cypress-io/cypress/blob/develop/.node-version). +However, installing the `cypress` npm package uses the Node.js version installed +on your system. + +[See Node's release schedule](https://github.com/nodejs/Release). Node.js +version 16 and 21 will no longer be supported when installing Cypress. The minimum Node.js +version supported to install Cypress is Node.js 18+. + +### Unsupported Linux Distributions + +Prebuilt binaries for Linux are no longer compatible with Linux distributions based on glibc `<2.28`. +This support is in line with Node.js's support for Linux in 18+. + +If you're using a Linux distribution based on glibc `<2.28`, for example, Ubuntu 14-18, RHEL 7, CentOS 7, Amazon Linux 2, you'll need to +update your system to a newer version to install Cypress 14+. + +### Updated Browser Support + +Starting in Cypress 14, Cypress will officially support [the latest 3 major versions of Chrome, Firefox, and Edge](/app/references/launching-browsers#Browser-versions-supported). + +Older browser versions may still work with Cypress, but we recommend keeping your browsers up to date to ensure compatibility with Cypress. + +### Changes to `cy.origin()` + +To account for Chrome's [impending deprecation](https://developer.chrome.com/blog/document-domain-setter-deprecation) of setting `document.domain`, and to support sites that use [origin-keyed agent clusters](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin-Agent-Cluster), +Cypress no longer injects `document.domain` into `text/html` content by default. + +Because of this, tests that visit more than one origin (defined as a composite of the URL _scheme_, _hostname_, and _port_) must now use `cy.origin()`. +Without `cy.origin()`, interacting with a second origin in the same test will cause the test to fail, even if the two origins +are in the same superdomain. This means you must now use `cy.origin()` in more situations than before. + +{/* prettier-ignore-start */} + **Failing Test** +```js +cy.visit('https://www.cypress.io') +cy.visit('https://docs.cypress.io') +// Cypress will not be able to interact with the page, causing the test to fail +cy.get('[role="banner"]').should('be.visible') +``` + + **Fixed Test** + +```js +cy.visit('https://www.cypress.io') +cy.visit('https://docs.cypress.io') +cy.origin('https://docs.cypress.io', () => { + cy.get('[role="banner"]').should('be.visible') +}) +``` +{/* prettier-ignore-end */} + +:::info + +To ease this transition, Cypress v14.0 introduced the ["injectDocumentDomain" configuration option](/app/references/configuration#injectDocumentDomain). When this option +is set to true, `cy.origin()` will not be required to navigate between origins, as long as the superdomain matches. + + If `injectDocumentDomain` is set to `true`, +Cypress will warn that this option is deprecated. + + `injectDocumentDomain` will be removed in Cypress +15. + + Setting `injectDocumentDomain` to `true` may +cause certain sites to stop working in Cypress. Please read the [configuration notes](/app/references/configuration#injectDocumentDomain) +before use. + + If your test suites require `experimentalWebKitSupport`, +`injectDocumentDomain` must be set to `true`. + + Chrome may remove support for `document.domain` +at any time; if this configuration option is enabled, Cypress may cease to work in +Chrome at any time. If this occurs, Chrome will raise an issue in its developer tools +indicating that the deprecated `document.domain` is in use. To resolve this issue, +set the `injectDocumentDomain` option to `false` and issue any newly necessary `cy.origin()` +commands.{' '} + +::: + +### Deprecation of `resourceType` on `cy.intercept` + +The `resourceType` option on [`cy.intercept`](/api/commands/intercept) has been deprecated in Cypress 14.0.0. We anticipate the types of the `resourceType` to change in the future or be completely removed +from the API. + +Our intention is to replace essential functionality dependent on the `resourceType` within Cypress in a future version (like [hiding network logs that are not fetch/xhr](/api/commands/intercept#Disabling-logs-for-a-request)). If you're using `resourceType` in your tests, please leave feedback on which `resourceType` values are important to you in this [GitHub issue](https://github.com/cypress-io/cypress/issues/30447). + +### CT Just in Time Compile changes + +In Cypress 13.14.0, we released an experimental flag, `experimentalJustInTimeCompile`, +to enable Just in Time (JIT) compilation for Component Testing with `vite` and `webpack`. The response from this change was positive and we've made a few changes in response: + +- JIT compilation is the default behavior for component tests as a [`justInTimeCompile`](/app/references/configuration#component) component configuration option. +- JIT compilation no longer applies with `vite`, since there is no benefit to enabling this with `vite`. + +This option will only compile resources directly related to your spec, compiling them 'just-in-time' before spec execution. This should result in improved memory management and performance for component tests in `cypress open` and `cypress run` modes, especially for large test suites. + +#### Disable JIT Compilation + +If you would like to disable JIT compilation, you can do so by setting [`justInTimeCompile`](/app/references/configuration#component) to `false` in your component configuration. + +:::cypress-config-example + +```js +{ + component: { + justInTimeCompile: false + } +} +``` + +::: + +For users with the existing `experimentalJustInTimeCompile` flag set, you can remove this flag from your configuration. + +### React `<18` CT no longer supported + +With [LTS ending](https://github.com/reactjs/react.dev/issues/1745#issuecomment-466767389) for React 16 and 17 several years ago, the minimum required React version for component testing is now `18.0.0`. + +Now that the minimum version of React supported for Component Testing is `18.0.0`, Cypress is able to merge the `cypress/react18` test harness into the main `cypress/react` test harness. Because of this, the `@cypress/react18` harness is deprecated and no longer shipped with the binary. Support has been moved to `cypress/react`. + +To migrate, change the test harness from `cypress/react18` to `cypress/react`. + +Before{' '} + +```ts +import { mount } from `cypress/react18` +``` + +After + +```ts +import { mount } from `cypress/react` +``` + +#### To continue using React below v18 + +If you haven't been able to migrate away from an older React version and still need that test harness, it can be installed independently via the [`@cypress/react`](https://www.npmjs.com/package/@cypress/react) `8.x.x` package from `npm`. + +Note that this test harness version is deprecated and no longer supported by Cypress. This version is intended to serve as a temporary workaround to migrate your project to React v18+. + +```sh +npm install --save-dev @cypress/react@8 +``` + +Inside your support file (ex: `./cypress/support/component.(js|ts)`), or wherever your mount function is imported, make the following update to add `@`. + +Before{' '} + +```ts +import { mount } from `cypress/react` +``` + +After + +```ts +import { mount } from `@cypress/react` +``` + +### Angular `<17.2.0` CT no longer supported + +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. + +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`. + +Before{' '} + +```ts +import { mount } from `cypress/angular-signals` +``` + +After + +```ts +import { mount } from `cypress/angular` +``` + +#### To continue using Angular below v17.2.0 + +If you haven't been able to migrate away from an older Angular version and still need that test harness, it can be installed independently via the [`@cypress/angular`](https://www.npmjs.com/package/@cypress/angular) `2.x.x` package from `npm`. + +Note that this test harness version is deprecated and no longer supported by Cypress. This version is intended to serve as a temporary workaround to migrate your project to Angular v17.2.0+. + +```sh +npm install --save-dev @cypress/angular@2 +``` + +Inside your support file (ex: `./cypress/support/component.(js|ts)`), or wherever your mount function is imported, make the following update to add `@`. + +Before{' '} + +```ts +import { mount } from `cypress/angular` +``` + +After + +```ts +import { mount } from `@cypress/angular` +``` + +### Vue 2 CT no longer supported + +[Vue 2 reached end-of-life on December 31st, 2023](https://v2.vuejs.org/eol/). With Cypress 14, Cypress no longer ships the Vue 2 component testing harness with the Cypress binary. + +#### To continue using Vue 2 + +If you haven't been able to migrate away from Vue 2 and still need that test harness, it can be installed independently via the [@cypress/vue2](https://www.npmjs.com/package/@cypress/vue2) package. + +Note that this test harness is deprecated and no longer supported by Cypress. This package is intended to serve as a temporary workaround to migrate your project to Vue 3. The Cypress launchpad will warn against Component testing mismatched dependencies, but this will not stop you from running your component tests. + +```sh +npm install --save-dev @cypress/vue2 +``` + +Inside your support file (ex: `./cypress/support/component.(js|ts)`), or wherever your mount function is imported, make the following update to add `@`. + +Before{' '} + +```ts +import { mount } from `cypress/vue2` +``` + +After + +```ts +import { mount } from `@cypress/vue2` +``` + +### Create React App CT no longer supported + +[create-react-app](https://create-react-app.dev/) is no longer actively maintained or supported (see [CRA issue #13393](https://github.com/facebook/create-react-app/issues/13393)). Your component tests will now need a bundler to run. If still using [create-react-app](https://create-react-app.dev/), you'll either need to: + +- [Eject](https://create-react-app.dev/docs/available-scripts/#npm-run-eject) the configuration to bundle with webpack. +- Leverage [vite](https://vite.dev/guide/) to bundle your component tests (quick setup with [create-vite](https://github.com/vitejs/vite/tree/main/packages/create-vite)). + +After selecting a bundler, change the `framework` option in your Cypress config from `create-react-app` to `react`. If ejecting the `create-react-app`, change your cypress config to look something like this: + +```js +process.env.NODE_ENV = 'development' +const { defineConfig } = require('cypress') +const webpackConfig = require('./config/webpack.config.js') + +module.exports = defineConfig({ + component: { + devServer: { + framework: 'react', + bundler: 'webpack', + webpackConfig: webpackConfig('development'), + }, + }, +}) +``` + +### `@vue/cli-service` CT no longer supported + +`@vue/cli-service` is in [maintenance mode](https://cli.vuejs.org/guide/cli-service.html) and is no longer maintained by the Vue core team. Your component tests will now need a bundler to run. If still using [Vue CLI](https://cli.vuejs.org/), you will either need to: + +- Migrate to webpack ([see example](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/vue3-webpack-ts)). +- Leverage [vite](https://vite.dev/guide/). The Vue team recommends migrating to using `create-vue` to scaffold a [Vite](https://vite.dev/)-based project. + +After selecting a bundler, change the `framework` option in your Cypress config from `"vue-cli"` to `"vue"`. Your Cypress configuration should change as outlined below. + +Before + +:::cypress-config-example + +``` +{ + component: { + devServer: { + framework: 'vue-cli', + bundler: 'webpack', + }, + } +} +``` + +::: + +After + +:::cypress-config-example + +``` +{ + component: { + devServer: { + framework: 'vue', + bundler: 'vite', // or 'webpack' + }, + } +} +``` + +::: + +### Svelte 3 & 4 CT no longer supported + +With Cypress 14, Cypress no longer ships the Svelte 3 and 4 component testing harness with the Cypress binary. + +However, if you have not been able to upgrade Svelte and still need the Cypress Svelte 3 and 4 test harness, it can be installed independently via version 2.x.x of the [@cypress/svelte](https://www.npmjs.com/package/@cypress/svelte) package. + +```sh +npm install --save-dev @cypress/svelte@2 +``` + +Note that this version of the test harness is deprecated and no longer actively supported by Cypress and is intended to serve as a temporary work around until you are able to migrate your project to Svelte 5+. The Cypress launchpad will also warn against Component testing mismatched dependencies, but this will not stop you from running your component tests. + +To update, inside your support file (ex: `./cypress/support/component.(js|ts)`) or wherever your mount function is imported, change + +```ts +import { mount } from `cypress/svelte` +``` + +to + +```ts +import { mount } from `@cypress/svelte` +``` + +Your code should now look like this: + +```ts +import MySvelteComponent from './MySvelteComponent' +import { mount } from `@cypress/svelte` + +it('renders', () => { + cy.mount(MySvelteComponent) +}) +``` + ## Migrating to Cypress 13.0 This guide details the changes and how to change your code to migrate to Cypress diff --git a/docs/partials/_document-domain-workaround.mdx b/docs/partials/_document-domain-workaround.mdx index bafb00c672..92953ccb0c 100644 --- a/docs/partials/_document-domain-workaround.mdx +++ b/docs/partials/_document-domain-workaround.mdx @@ -1,12 +1,24 @@ :::caution - **Disabling document.domain Injection** + **Re-Enabling document.domain Injection** -In some cases, `document.domain` injection may cause issues. As of Cypress -[v12.4.0](/app/references/changelog#12-4-0), disabling `document.domain` -injection is available with the `experimentalSkipDomainInjection` option. Please -read about this -[experiment](/app/references/experiments#Experimental-Skip-Domain-Injection) -for more information +As of Cypress [v14.0.0](/app/references/changelog#14-0-0), [`document.domain`](https://developer.mozilla.org/en-US/docs/Web/API/Document/domain) +will no longer be injected into `text/html` pages by default. -::: +This means you must now use `cy.origin()` when navigating between different _origins_ +in the same test. Previously, `cy.origin()` was only necessary when navigating between +different [superdomains](/app/guides/cross-origin-testing#Parts-of-a-URL) in the same test. + +By setting the `injectDocumentDomain` configuration option to `true`, Cypress will +attempt to inject `document.domain` into `text/html` pages. + +A superdomain is comprised of the trailing two elements of the hostname, delimited by +a `.` (period). Given `https://www.cypress.io`, the superdomain is determined to be +`cypress.io`. When this option is enabled, `cy.origin()` is not necessary when navigating +between `https://www.cypress.io` and `https://docs.cypress.io`, but is necessary +when navigating between `https://www.cypress.io` and `https://www.auth0.com`. + +- This will cause issues with certain sites, especially those that use + [origin-keyed agent cluster](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin-Agent-Cluster)s. +- This option is deprecated, and will be removed in Cypress 15. + ::: diff --git a/docs/partials/_import-mount-functions.mdx b/docs/partials/_import-mount-functions.mdx index bbed6eddc4..08883318e1 100644 --- a/docs/partials/_import-mount-functions.mdx +++ b/docs/partials/_import-mount-functions.mdx @@ -15,10 +15,6 @@ module supports standard JSX syntax for mounting components. ::: ```js -// React 18 -import { mount } from 'cypress/react18' - -// React 16, 17 import { mount } from 'cypress/react' ``` @@ -39,11 +35,7 @@ in your actual browser. ::: ```js -// For Vue 3 import { mount } from 'cypress/vue' - -// For Vue 2 -import { mount } from 'cypress/vue2' ``` diff --git a/src/components/badge/style.module.css b/src/components/badge/style.module.css index a5acb2194d..078396b46d 100644 --- a/src/components/badge/style.module.css +++ b/src/components/badge/style.module.css @@ -27,6 +27,10 @@ h1 > .badge { color: var(--ifm-color-red-600); } +.caution { + background-color: #e6a700; +} + .info { background-color: var(--ifm-color-teal-100); color: var(--ifm-color-teal-600); diff --git a/src/data/plugins.json b/src/data/plugins.json index a5f37aeed1..aed12c19b2 100644 --- a/src/data/plugins.json +++ b/src/data/plugins.json @@ -780,13 +780,6 @@ "keywords": ["component", "vue", "vue.js"], "badge": "official" }, - { - "name": "Cypress Vue2", - "description": "Test Vue 2 components using Cypress Test Runner. This package is bundled with the cypress package and should not need to be installed separately. See the Vue Component Testing Docs for mounting Vue components.", - "link": "https://github.com/cypress-io/cypress/tree/develop/npm/vue2", - "keywords": ["component", "vue", "vue.js"], - "badge": "official" - }, { "name": "cypress-angular-unit-test", "description": "Test Angular component using Cypress Test Runner.", diff --git a/static/img/app/component-testing/create-your-first-spec-cfc.png b/static/img/app/component-testing/create-your-first-spec-cfc.png index f3bceda952..75cd70ed29 100644 Binary files a/static/img/app/component-testing/create-your-first-spec-cfc.png and b/static/img/app/component-testing/create-your-first-spec-cfc.png differ diff --git a/static/img/app/component-testing/dependency-detection-react.jpg b/static/img/app/component-testing/dependency-detection-react.jpg index 0af984bb27..402b8d2f96 100644 Binary files a/static/img/app/component-testing/dependency-detection-react.jpg and b/static/img/app/component-testing/dependency-detection-react.jpg differ diff --git a/static/img/app/component-testing/select-browser.jpg b/static/img/app/component-testing/select-browser.jpg index 5075f754c5..b51cf4428b 100644 Binary files a/static/img/app/component-testing/select-browser.jpg and b/static/img/app/component-testing/select-browser.jpg differ diff --git a/static/img/app/component-testing/select-browser.png b/static/img/app/component-testing/select-browser.png index 472d92f5c9..b51cf4428b 100644 Binary files a/static/img/app/component-testing/select-browser.png and b/static/img/app/component-testing/select-browser.png differ