diff --git a/docs/api/cypress-api/element-selector-api.mdx b/docs/api/cypress-api/element-selector-api.mdx
new file mode 100644
index 0000000000..d2838d60c3
--- /dev/null
+++ b/docs/api/cypress-api/element-selector-api.mdx
@@ -0,0 +1,161 @@
+---
+title: 'Cypress.ElementSelector | Cypress Documentation'
+description: 'Customize how Cypress chooses selectors in Studio and Selector Playground by setting your preferred selector strategy.'
+sidebar_label: ElementSelector
+sidebar_position: 105
+---
+
+
+
+# Cypress.ElementSelector
+
+The ElementSelector API lets you define how Cypress selects elements in tools like [Cypress Studio](/app/guides/cypress-studio) and the [Selector Playground](/app/core-concepts/open-mode#Selector-Playground) (which will be replaced by Cypress Studio once it is no longer experimental).
+
+By setting your own selector strategy, you can control which attributes Cypress prioritizes (like `data-*`, `id`, or `aria-label`) when generating selectors. This helps you enforce consistency, improve test readability, and make generated tests more resilient to changes in your HTML.
+
+Cypress uses a strategy to generate selectors that are not only based on your preferred selectors, but also guaranteed to be **unique** within the document.
+
+This means Cypress will **attempt to follow your configured `selectorPriority`**, but may skip lower-priority options or combine multiple selectors if a single attribute isn't unique enough.
+
+## Syntax
+
+```javascript
+Cypress.ElementSelector.defaults(options)
+```
+
+### Arguments
+
+ **options _(Object)_**
+
+An object containing any or all of the following options:
+
+| Option | Accepts | Description |
+| ------------------ | ------------------ | ---------------------------------------------------------------------- |
+| `selectorPriority` | `Array of strings` | Determines the order of attributes Cypress uses to generate selectors. |
+
+:::info
+
+##### API Stability
+
+The `selectorPriority` API is under active development and may change in future versions as we refine the best way to generate selectors within our products. Stay updated with our [changelog](/app/references/changelog) for any breaking changes.
+
+:::
+
+Accepted values for `selectorPriority` are:
+
+- `attribute:${string}` - for specific attributes like `attribute:aria-label`, `attribute:lang`, etc.
+- `attributes` - general fallback for any other attributes
+- `class`
+- `data-${string}` - for specific data attributes like `data-cy`, `data-testid`, etc.
+- `id`
+- `name`
+- `nth-child`
+- `tag`
+
+
+
+Consider the following HTML:
+
+```html
+
+```
+
+With the default selector priority, Cypress prioritizes `id`, so the selector would be `#submit-btn`.
+
+ **$el _(Object)_**
+
+The [jQuery element](http://api.jquery.com/Types/#jQuery) for which you want to retrieve a selector.
+
+## Examples
+
+### Set custom selector priority
+
+You can customize how Cypress generates selectors by defining a priority order for which attributes to prefer. This affects the selectors you see in tools like [Cypress Studio](/app/guides/cypress-studio) and the [Selector Playground](/app/core-concepts/open-mode#Selector-Playground) (which will be replaced by Cypress Studio once it is no longer experimental).
+
+For example, this config tells Cypress to prefer semantic and accessibility attributes before falling back to styling details like class names.
+
+```javascript
+Cypress.ElementSelector.defaults({
+ selectorPriority: [
+ 'attribute:role',
+ 'attribute:aria-label',
+ 'name',
+ 'class',
+ 'attributes',
+ ],
+})
+```
+
+### Prioritize accessible attributes
+
+Accessibility-first apps often use ARIA roles and labels. You can configure Cypress to prioritize these when generating selectors:
+
+```js
+Cypress.ElementSelector.defaults({
+ selectorPriority: ['attribute:aria-label', 'attribute:role', 'id', 'class'],
+})
+```
+
+This helps produce more readable and resilient selectors, especially for accessibility-first applications.
+
+### Prioritize language-agnostic selectors (for i18n)
+
+In multilingual applications, selectors based on text or labels may change between locales. Prefer stable, language-agnostic attributes like `data-*`, `role`, and `aria-labelledby`.
+
+```js
+Cypress.ElementSelector.defaults({
+ selectorPriority: [
+ 'data-cy',
+ 'attribute:role',
+ 'attribute:aria-labelledby',
+ 'name',
+ 'id',
+ 'class',
+ 'attributes',
+ ],
+})
+```
+
+This ensures selectors are resilient to translation changes in text or labels.
+
+### Avoid dynamic or auto-generated selectors
+
+Many frameworks produce dynamic ids or class names such as:
+
+```html
+
+```
+
+You can configure Cypress to skip attributes that are dynamically generated.
+
+```js
+Cypress.ElementSelector.defaults({
+ selectorPriority: [
+ 'data-cy',
+ 'attribute:role',
+ 'attribute:aria-label',
+ 'name',
+ 'attributes', // fallback
+ // deliberately omit 'id' and 'class'
+ ],
+})
+```
+
+## History
+
+| Version | Changes |
+| ------------------------------------------ | ------------------------------------------------------------------ |
+| [15.0.0](/app/references/changelog#15-0-0) | Renamed `Cypress.SelectorPlayground` to `Cypress.ElementSelector`. |
+
+## See also
+
+- [Cypress Studio](/app/guides/cypress-studio)
+- [Selector Playground](/app/core-concepts/open-mode#Selector-Playground)
diff --git a/docs/api/cypress-api/selector-playground-api.mdx b/docs/api/cypress-api/selector-playground-api.mdx
deleted file mode 100644
index b2b700a060..0000000000
--- a/docs/api/cypress-api/selector-playground-api.mdx
+++ /dev/null
@@ -1,100 +0,0 @@
----
-title: 'Cypress.SelectorPlayground | Cypress Documentation'
-description: 'The Selector Playground exposes APIs that enable you to change the default selector strategy and override the selectors that are returned per element.'
-sidebar_label: SelectorPlayground
----
-
-
-
-# Cypress.SelectorPlayground
-
-The [Selector Playground](/app/core-concepts/open-mode#Selector-Playground)
-exposes APIs that enable you to:
-
-- Change the default selector strategy
-- Override the selectors that are returned per element
-
-## Syntax
-
-```javascript
-Cypress.SelectorPlayground.defaults(options)
-Cypress.SelectorPlayground.getSelector($el)
-```
-
-### Arguments
-
- **options _(Object)_**
-
-An object containing any or all of the following options:
-
-| Option | Accepts | Description |
-| ------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `selectorPriority` | `Array of strings` | Determines the order of preference for which selector is chosen for the element. |
-| `onElement` | `function` | A function called with the element that should return a unique selector string for the element. If a falsey value is returned, the default selector function is used. |
-
-
-
- **$el _(Object)_**
-
-The [jQuery element](http://api.jquery.com/Types/#jQuery) that you want to get
-the selector value for.
-
-## Examples
-
-### Selector Priority
-
-Set the selector priority to favor IDs, then classes, then attributes.
-
-```javascript
-Cypress.SelectorPlayground.defaults({
- selectorPriority: ['id', 'class', 'attributes'],
-})
-```
-
-### onElement Callback
-
-Set a custom function for determining the selector for an element. Falls back to
-default behavior if returning a falsey value.
-
-```javascript
-Cypress.SelectorPlayground.defaults({
- onElement: ($el) => {
- const customId = $el.attr('my-custom-attr')
-
- if (customId) {
- return `[my-custom-attr=${customId}]`
- }
- },
-})
-```
-
-### Get Selector
-
-Returns you the selector value for a given element as determined by the selector
-strategy.
-
-For example, consider this HTML fragment.
-
-```html
-
-```
-
-With the default selector strategy, the selector value will be `'#bingo'`
-because IDs have priority over classes.
-
-```js
-const $el = Cypress.$('button')
-const selector = Cypress.SelectorPlayground.getSelector($el) // '#bingo'
-```
-
-With a custom selector strategy that favours classes, the selector value will be
-`'.number3'`.
-
-```js
-Cypress.SelectorPlayground.defaults({
- selectorPriority: ['class', 'id'],
-})
-
-const $el = Cypress.$('button')
-const selector = Cypress.SelectorPlayground.getSelector($el) // '.number3'
-```
diff --git a/docs/api/table-of-contents.mdx b/docs/api/table-of-contents.mdx
index 01c2a7f43f..3eb8becefb 100644
--- a/docs/api/table-of-contents.mdx
+++ b/docs/api/table-of-contents.mdx
@@ -190,29 +190,29 @@ The _key_ difference between Cypress APIs and Cypress commands is that Cypress
APIs execute the moment they are invoked and are **not** enqueued to run at a
later time.
-| Property | Usage |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| [`Cypress.arch`](/api/cypress-api/arch) | CPU architecture name of the underlying OS, as returned from Node's `os.arch()`. |
-| [`Cypress.browser`](/api/cypress-api/browser) | Information about the current browser, such as browser family and version. |
-| [`Cypress.Commands`](/api/cypress-api/custom-commands) | Create new custom commands and extend or override existing ones. |
-| [`Cypress.config()`](/api/cypress-api/config) | Get and set Cypress configuration from inside your tests. |
-| [`Cypress.Cookies.debug()`](/api/cypress-api/cookies) | Generate console logs whenever a cookie is modified. |
-| [`Cypress.currentRetry`](/api/cypress-api/currentretry) | A number representing the current test retry count. |
-| [`Cypress.currentTest`](/api/cypress-api/currenttest) | An object with information about the currently executing test. |
-| [`Cypress.log`](/api/cypress-api/cypress-log) | This is the internal API for controlling what gets printed to the Command Log. Useful when writing your own custom commands. |
-| [`Cypress.dom`](/api/cypress-api/dom) | A collection of DOM related helper methods. |
-| [`Cypress.env`](/api/cypress-api/env) | Get environment variables from inside your tests. |
-| [`Cypress.isBrowser()`](/api/cypress-api/isbrowser) | Checks if the current browser matches the given name or filter. |
-| [`Cypress.isCy()`](/api/cypress-api/iscy) | checks if a variable is a valid instance of cy or a cy chainable. |
-| [`Cypress.Keyboard.defaults()`](/api/cypress-api/keyboard-api) | Set default values for how the `.type()` command is executed. |
-| [`Cypress.platform`](/api/cypress-api/platform) | The underlaying OS name, as returned by Node's `os.platform()`. |
-| [`Cypress.require`](/api/cypress-api/require) | Enables utilizing dependencies within the [cy.origin()](/api/commands/origin) callback function. |
-| [`Cypress.Screenshot.defaults()`](/api/cypress-api/screenshot-api) | Set defaults for screenshots captured by the `.screenshot()` command and the automatic screenshots taken during test failures. |
-| [`Cypress.SelectorPlayground`](/api/cypress-api/selector-playground-api) | Configure options used by the [Selector Playground](/app/core-concepts/open-mode#Selector-Playground). |
-| [`Cypress.session`](/api/cypress-api/session) | A collection of helper methods related to the `.session()` command. |
-| [`Cypress.spec`](/api/cypress-api/spec) | An object with information about the currently executing spec file. |
-| [`Cypress.testingType`](/api/cypress-api/testing-type) | The current testing type, eg. `"e2e"` or `"component". |
-| [`Cypress.version`](/api/cypress-api/version) | The current Cypress version. |
+| Property | Usage |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`Cypress.arch`](/api/cypress-api/arch) | CPU architecture name of the underlying OS, as returned from Node's `os.arch()`. |
+| [`Cypress.browser`](/api/cypress-api/browser) | Information about the current browser, such as browser family and version. |
+| [`Cypress.Commands`](/api/cypress-api/custom-commands) | Create new custom commands and extend or override existing ones. |
+| [`Cypress.config()`](/api/cypress-api/config) | Get and set Cypress configuration from inside your tests. |
+| [`Cypress.Cookies.debug()`](/api/cypress-api/cookies) | Generate console logs whenever a cookie is modified. |
+| [`Cypress.currentRetry`](/api/cypress-api/currentretry) | A number representing the current test retry count. |
+| [`Cypress.currentTest`](/api/cypress-api/currenttest) | An object with information about the currently executing test. |
+| [`Cypress.log`](/api/cypress-api/cypress-log) | This is the internal API for controlling what gets printed to the Command Log. Useful when writing your own custom commands. |
+| [`Cypress.dom`](/api/cypress-api/dom) | A collection of DOM related helper methods. |
+| [`Cypress.ElementSelector`](/api/cypress-api/element-selector-api) | Configure selector priority used by [Cypress Studio](/app/guides/cypress-studio) and [Selector Playground](/app/core-concepts/open-mode#Selector-Playground). |
+| [`Cypress.env`](/api/cypress-api/env) | Get environment variables from inside your tests. |
+| [`Cypress.isBrowser()`](/api/cypress-api/isbrowser) | Checks if the current browser matches the given name or filter. |
+| [`Cypress.isCy()`](/api/cypress-api/iscy) | checks if a variable is a valid instance of cy or a cy chainable. |
+| [`Cypress.Keyboard.defaults()`](/api/cypress-api/keyboard-api) | Set default values for how the `.type()` command is executed. |
+| [`Cypress.platform`](/api/cypress-api/platform) | The underlaying OS name, as returned by Node's `os.platform()`. |
+| [`Cypress.require`](/api/cypress-api/require) | Enables utilizing dependencies within the [cy.origin()](/api/commands/origin) callback function. |
+| [`Cypress.Screenshot.defaults()`](/api/cypress-api/screenshot-api) | Set defaults for screenshots captured by the `.screenshot()` command and the automatic screenshots taken during test failures. |
+| [`Cypress.session`](/api/cypress-api/session) | A collection of helper methods related to the `.session()` command. |
+| [`Cypress.spec`](/api/cypress-api/spec) | An object with information about the currently executing spec file. |
+| [`Cypress.testingType`](/api/cypress-api/testing-type) | The current testing type, eg. `"e2e"` or `"component". |
+| [`Cypress.version`](/api/cypress-api/version) | The current Cypress version. |
## Utilities
diff --git a/docs/app/component-testing/angular/overview.mdx b/docs/app/component-testing/angular/overview.mdx
index 29d0bb6a48..6c8761cd90 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 17.2.0+.
+Cypress Component Testing supports Angular `^18.0.0` and `^19.0.0`.
## Tutorial
diff --git a/docs/app/component-testing/get-started.mdx b/docs/app/component-testing/get-started.mdx
index 143d9bc5e3..fe19ba73ea 100644
--- a/docs/app/component-testing/get-started.mdx
+++ b/docs/app/component-testing/get-started.mdx
@@ -42,13 +42,13 @@ following development servers and frameworks:
| Framework | UI Library | Bundler |
| ------------------------------------------------------------------------------------------------------------------ | ------------- | ----------- |
-| [React with Vite](/app/component-testing/react/overview#React-with-Vite) | React 18-19 | Vite 4-6 |
+| [React with Vite](/app/component-testing/react/overview#React-with-Vite) | React 18-19 | Vite 5-7 |
| [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 Vite](/app/component-testing/vue/overview#Vue-with-Vite) | Vue 3 | Vite 5-7 |
| [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 |
+| [Angular](/app/component-testing/angular/overview#Framework-Configuration) | Angular 18-19 | Webpack 5 |
+| [Svelte with Vite](/app/component-testing/svelte/overview#Svelte-with-Vite) Alpha | Svelte 5 | Vite 5-7 |
| [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.
diff --git a/docs/app/component-testing/react/overview.mdx b/docs/app/component-testing/react/overview.mdx
index 2531e91fcc..31f66c7f64 100644
--- a/docs/app/component-testing/react/overview.mdx
+++ b/docs/app/component-testing/react/overview.mdx
@@ -70,7 +70,7 @@ are for reference purposes.
### React with Vite
-Cypress Component Testing works with React apps that use Vite 4+ as the bundler.
+Cypress Component Testing works with React apps that use Vite 5+ as the bundler.
#### Vite Configuration
diff --git a/docs/app/core-concepts/interacting-with-elements.mdx b/docs/app/core-concepts/interacting-with-elements.mdx
index d3abc729d6..c098f088ee 100644
--- a/docs/app/core-concepts/interacting-with-elements.mdx
+++ b/docs/app/core-concepts/interacting-with-elements.mdx
@@ -242,7 +242,10 @@ the command in the [Command Log](/app/core-concepts/open-mode#Command-Log).
Additionally we'll display a red "hitbox" - which is a dot indicating the
coordinates of the event.
-
+
## Debugging
diff --git a/docs/app/core-concepts/introduction-to-cypress.mdx b/docs/app/core-concepts/introduction-to-cypress.mdx
index 907db405b8..76f4886f81 100644
--- a/docs/app/core-concepts/introduction-to-cypress.mdx
+++ b/docs/app/core-concepts/introduction-to-cypress.mdx
@@ -728,14 +728,7 @@ later in this guide.
#### Avoid loops
Using JavaScript loop commands like `while` can have unexpected effects. Let's
-say our application shows a random number on load.
-
-
-
-We want the test to stop when it finds the number 7. If any other number is
+say our application shows a random number on load. We want the test to stop when it finds the number 7. If any other number is
displayed the test reloads the page and checks again.
**Note:** you can find this application and the correct test in our
@@ -743,7 +736,7 @@ displayed the test reloads the page and checks again.
**Incorrect test**
-The test written below WILL NOT work and most likely will crash your browser.
+The test written below **WILL NOT work** and most likely will crash your browser.
```js
let found7 = false
@@ -813,10 +806,6 @@ The test runs and correctly finishes.
alt="Test reloads the page until the number 7 appears"
/>
-You can see a short video going through this example at
-
-
-
### Commands Run Serially
After a test function is finished running, Cypress goes to work executing the
@@ -843,6 +832,8 @@ it('hides the thing when it is clicked', () => {
The test above would cause an execution in this order:
+:::note
+
1. Visit the URL (or mount the component).
2. Find an element by its selector.
3. Assert that the element is visible.
@@ -850,12 +841,16 @@ The test above would cause an execution in this order:
5. Find an element by its selector.
6. Assert that the element is no longer visible.
+:::
+
These actions will always happen serially (one after the other), never in
parallel (at the same time). Why?
To illustrate this, let's revisit that list of actions and expose some of the
hidden **✨ magic ✨** Cypress does for us at each step:
+:::note
+
1. Visit the URL ✨ **and wait for the page load event to fire after all
external resources have loaded** ✨ (or mount the component ✨ **and wait for
the component to finish mounting** ✨)
@@ -870,6 +865,8 @@ hidden **✨ magic ✨** Cypress does for us at each step:
6. Assert that the element is no longer visible ✨ **and retry until the
assertion passes** ✨
+:::
+
As you can see, Cypress does a lot of extra work to ensure the state of the
application matches what our commands expect about it. Each command may resolve
quickly (so fast you won't see them in a pending state) but others may take
diff --git a/docs/app/core-concepts/open-mode.mdx b/docs/app/core-concepts/open-mode.mdx
index 0ce1003cf7..60822db423 100644
--- a/docs/app/core-concepts/open-mode.mdx
+++ b/docs/app/core-concepts/open-mode.mdx
@@ -223,6 +223,7 @@ experience in [Test Replay](/cloud/features/test-replay) for runs recorded in CI
## Command Log
@@ -282,11 +283,6 @@ Also note that as we hover over the [`contains`](/api/commands/contains)
command, Cypress reverts back to the URL that was present when the snapshot was
taken.
-
-
### Pinning snapshots
Each command, when clicked on, displays extra information in the dev tools
@@ -421,6 +417,8 @@ DOM is completely available for debugging.
alt="Application Under Test"
/>
+#### Viewport Size and Scale
+
The AUT also displays in the size and orientation specified in your tests. You
can change the size or orientation with the
[`cy.viewport()`](/api/commands/viewport) command or in your
@@ -432,33 +430,23 @@ The current size and scale of the AUT is displayed in the top right corner of
the window.
The image below shows that our application is displaying at `1000px` width,
-`660px` height and scaled to `100%`.
+`660px` height and scaled to `90%`.
-:::info
+#### Errors
The right-hand side may also be used to display syntax errors in your spec file
that prevent the tests from running.
-:::
-
-:::caution
-
-Internally, the AUT renders within an iframe. This can sometimes cause
-unexpected behaviors
-[explained here.](/api/commands/window#Cypress-uses-2-different-windows)
-
-:::
-
### Component Under Test
In
@@ -531,6 +519,13 @@ that prevent the tests from running.
## Selector Playground
+:::caution
+
+##### Deprecation Notice
+
+The Selector Playground will be replaced by [Cypress Studio](/app/guides/cypress-studio) once it is no longer experimental. Cypress Studio provides the same functionality for constructing Cypress commands using unique selectors, along with additional recording capabilities.
+:::
+
The Selector Playground is an interactive feature that helps you:
- Determine a unique selector for an element.
@@ -550,19 +545,16 @@ interactions.
title="Selector Playground demo"
/>
-### Uniqueness
+### How are selectors determined?
-Cypress will automatically calculate a **unique selector** to use targeted
+Cypress will automatically calculate a **unique selector** to use for a targeted
element by running through a series of selector strategies.
-:::info
-
-Cypress allows you to control how a selector is determined. Use the [Cypress.SelectorPlayground](/api/cypress-api/selector-playground-api)
-API to control the selectors you want returned.
-
-:::
+Cypress allows you to control how a selector is determined. Use the
+[`Cypress.ElementSelector`](/api/cypress-api/element-selector-api) API to control
+the selectors you want prioritized.
### Best practices
diff --git a/docs/app/core-concepts/retry-ability.mdx b/docs/app/core-concepts/retry-ability.mdx
index 231d9c57b3..5f9cfb0b3a 100644
--- a/docs/app/core-concepts/retry-ability.mdx
+++ b/docs/app/core-concepts/retry-ability.mdx
@@ -426,8 +426,6 @@ Below is an example where the number value is set after a delay:
```
-
-
### Incorrectly waiting for values
You may want to write a test like below, to test that the number is between 1
diff --git a/docs/app/core-concepts/writing-and-organizing-tests.mdx b/docs/app/core-concepts/writing-and-organizing-tests.mdx
index 510cc4426a..ab2154fe2c 100644
--- a/docs/app/core-concepts/writing-and-organizing-tests.mdx
+++ b/docs/app/core-concepts/writing-and-organizing-tests.mdx
@@ -803,7 +803,7 @@ Passed tests have successfully completed all their hooks and commands without
failing any assertions. The test screenshot below shows a passed test:
@@ -817,7 +817,7 @@ Good news - the failed hook or test has found a problem. Could be much worse -
it could be a user hitting this bug!
@@ -861,7 +861,7 @@ All four tests above are marked _pending_ when Cypress finishes running the spec
file.
@@ -875,38 +875,7 @@ skipped due to some run-time error. For example, imagine a group of tests
sharing the same `beforeEach` hook - where you visit the page in the
`beforeEach` hook.
-```js
-///
-
-describe('TodoMVC', () => {
- beforeEach(() => {
- cy.visit('/')
- })
-
- it('hides footer initially', () => {
- cy.get('[data-testid="filters"]').should('not.exist')
- })
-
- it('adds 2 todos', () => {
- cy.get('[data-testid="new-todo"]').as('new').type('learn testing{enter}')
-
- cy.get('@new').type('be cool{enter}')
-
- cy.get('[data-testid="todo-list"] li').should('have.length', 2)
- })
-})
-```
-
-If the `beforeEach` hook completes and both tests finish, two tests are passing.
-
-
-
-But what happens if a command inside the `beforeEach` hook fails? For example,
-let's pretend we want to visit a non-existent page `/does-not-exist` instead of
-the `/`. If we change our `beforeEach` to fail:
+If a command inside the `beforeEach` hook fails - for example, if we want to visit a non-existent page `/does-not-exist` instead of the `/` - and we change our `beforeEach` to fail:
```js
beforeEach(() => {
@@ -921,7 +890,7 @@ the same way! So Cypress _skips_ the remaining tests in that block, because they
would also fail due to the `beforeEach` hook failure.
@@ -929,7 +898,7 @@ If we collapse the test commands, we can see the empty box marking the skipped
test "adds 2 todos".
diff --git a/docs/app/end-to-end-testing/testing-your-app.mdx b/docs/app/end-to-end-testing/testing-your-app.mdx
index bcc233a515..a4aed2ab3d 100644
--- a/docs/app/end-to-end-testing/testing-your-app.mdx
+++ b/docs/app/end-to-end-testing/testing-your-app.mdx
@@ -103,7 +103,6 @@ Once that file is created, you should see it in the list of spec files.
Now you'll need to add in the following code in your test file to visit your
diff --git a/docs/app/end-to-end-testing/writing-your-first-end-to-end-test.mdx b/docs/app/end-to-end-testing/writing-your-first-end-to-end-test.mdx
index 4385c11223..78284b7714 100644
--- a/docs/app/end-to-end-testing/writing-your-first-end-to-end-test.mdx
+++ b/docs/app/end-to-end-testing/writing-your-first-end-to-end-test.mdx
@@ -119,8 +119,15 @@ describe('My First Test', () => {
Once you save again, you'll see Cypress display the failing test in red since
`true` does not equal `false`.
-Cypress also displays the stack trace and the code frame where the assertion
-failed (when available). You can click on the blue file link to open the file
+Cypress displays a detailed error view that includes the stack trace and the exact code frame where the assertion failed. This helps you quickly identify and fix the issue.
+
+:::info
+
+If you don't see the code frame or stack trace, you may need to [enable sourcemaps](/app/guides/debugging#Source-maps) for better debugging information.
+
+:::
+
+You can click on the blue file link to open the file
where the error occurred in
[your preferred file opener](/app/tooling/IDE-integration#File-Opener-Preference).
To read more about the error's display, read about
@@ -159,15 +166,6 @@ already have some familiarity and knowledge of. If not, that's okay too.
:::
-:::tip
-
-Using ESlint?
-
-Check out our
-[Cypress ESLint plugin](https://github.com/cypress-io/eslint-plugin-cypress).
-
-:::
-
## Write a _real_ test
**A solid test generally covers 3 phases:**
@@ -242,7 +240,6 @@ Let's add it to our test and see what happens:
describe('My First Test', () => {
it('finds the content "type"', () => {
cy.visit('https://example.cypress.io')
-
cy.contains('type')
})
})
@@ -278,15 +275,11 @@ describe('My First Test', () => {
alt="Test failing to not find content 'hype'"
/>
-:::caution
+:::info
Error Messages
-We've taken care at Cypress to write hundreds of custom error messages that
-attempt to clearly explain what went wrong. In this case, Cypress **timed out
-retrying** to find the content `hype` within the entire page. To read more about
-the error's display, read about
-[Debugging Errors](/app/guides/debugging#Errors).
+Cypress provides detailed, human-readable error messages that explain exactly what went wrong. In this case, Cypress **timed out retrying** to find the content `hype` within the entire page. These descriptive error messages help you quickly understand and fix issues in your tests. For more information about how Cypress displays errors, see [Debugging Errors](/app/guides/debugging#Errors).
:::
@@ -393,22 +386,11 @@ describe('My First Test', () => {
})
```
-:::caution
-
-We normally don't suggest selecting and finding elements by their class names,
-but we do so here since we are querying an external site, and sometimes that is
-all we have to work with.
-
-For more information on our guidance on selector best practices, see our guide
-on it [here](/app/core-concepts/best-practices#Selecting-Elements).
-
-:::
-
And there you have it: a short test in Cypress that visits a page, finds and
clicks a link, verifies the URL and then verifies the behavior of an element on
the new page. If we read it out loud, it might sound like:
-:::note
+:::info
1. _Visit: `https://example.cypress.io`_
2. _Find the element with content: `type`_
@@ -423,7 +405,7 @@ the new page. If we read it out loud, it might sound like:
Or in the _Given_, _When_, _Then_ syntax:
-:::note
+:::info
1. _**Given** a user visits `https://example.cypress.io`_
2. _**When** they click the link labeled `type`_
@@ -539,8 +521,3 @@ which discusses strategies when this is necessary.
practical demonstrations of Cypress testing practices, configuration, and
strategies in a real-world project.
- Search Cypress's documentation to quickly find what you need.
-
-
diff --git a/docs/app/get-started/install-cypress.mdx b/docs/app/get-started/install-cypress.mdx
index d1f6c805a3..6fd861cfeb 100644
--- a/docs/app/get-started/install-cypress.mdx
+++ b/docs/app/get-started/install-cypress.mdx
@@ -116,11 +116,10 @@ Cypress supports running under these operating systems:
Cypress requires [Node.js](https://nodejs.org/) in order to install. We support the versions listed below:
-- **Node.js** 18.x, 20.x, 22.x and above
+- **Node.js** 20.x, 22.x, 24.x and above
Cypress generally aligns with
[Node's release schedule](https://github.com/nodejs/Release).
-Accordingly, use of Node.js 18 and 23 with Cypress is deprecated and support is planned for removal in a future release of Cypress.
#### Installing Node.js
@@ -149,7 +148,7 @@ Cypress is [installed](#Install) using one of the following supported package ma
| Package Manager | Version | Installation instructions |
| ------------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------- |
-| [npm](https://docs.npmjs.com/) | `8.6.0` and above | [Downloading and installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) |
+| [npm](https://docs.npmjs.com/) | `10.1.0` and above | [Downloading and installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) |
| [Yarn 1 (Classic)](https://classic.yarnpkg.com/) | `1.22.22` and above | [Yarn 1 (Classic) Installation](https://classic.yarnpkg.com/en/docs/install) |
| [Yarn (Modern aka berry)](https://yarnpkg.com/) | `4.x` and above | [Yarn Installation](https://yarnpkg.com/getting-started/install) |
| [pnpm](https://pnpm.io/) | `8.x` and above | [pnpm Installation](https://pnpm.io/installation) |
@@ -274,5 +273,4 @@ It is recommended to have `unzip` installed. This avoids the Cypress binary inst
## Next Steps
-[Open the app](/app/get-started/open-the-app) and take it for a test
-drive!
+[Open the app](/app/get-started/open-the-app) and take it for a test drive!
diff --git a/docs/app/guides/cypress-studio.mdx b/docs/app/guides/cypress-studio.mdx
index 2966a3512f..6e73ce3b63 100644
--- a/docs/app/guides/cypress-studio.mdx
+++ b/docs/app/guides/cypress-studio.mdx
@@ -13,11 +13,18 @@ e2eSpecific: true
##### What you'll learn
-- How to use Cypress Studio by recording interactions and generate tests
-- How to add new tests and extend existing tests with Cypress Studio
+- How to generate Cypress tests by interacting with your app
+- How to add assertions through the browser UI
+- How to extend or edit tests using Cypress Studio
:::
+## Overview
+
+Cypress Studio makes test creation faster and easier. With Studio, you can record user interactions in the browser and instantly generate Cypress test code. Add assertions with a right-click and fine-tune your tests inline.
+
+It is ideal for bootstrapping new tests or extending existing ones without writing every `.get()`, `.click()`, or `.type()` command by hand.
+
:::caution
**Experimental**
@@ -40,303 +47,57 @@ attribute to your Cypress configuration.
:::
-## Limitations
-
-- Cypress Studio is currently only available for writing E2E tests, and doesn't
- yet work with Component Testing.
-- Cypress Studio does not support writing tests that use domains of [multiple
- origins](/app/guides/cross-origin-testing).
-- Cypress Studio can not interact with elements within a ShadowDom directly, though it can still run tests that do.
-
-## Overview
-
-Cypress Studio provides a visual way to generate tests within Cypress, by
-_recording interactions_ against the application under test.
-
-The [`.click()`](/api/commands/click), [`.type()`](/api/commands/type),
-[`.check()`](/api/commands/check), [`.uncheck()`](/api/commands/uncheck), and
-[`.select()`](/api/commands/select) Cypress commands are supported and will
-generate test code when interacting with the DOM inside of the Cypress Studio.
-
-You can also generate assertions by right clicking on an element that you would
-like to assert on.
-
-The Cypress
-[Real World App (RWA)](https://github.com/cypress-io/cypress-realworld-app) is
-an open source project implementing a payment application to demonstrate
-real-world usage of Cypress testing methods, patterns, and workflows. It will be
-used to demonstrate the functionality of Cypress Studio below.
-
-### Extending a Test
-
-You can extend any preexisting test or start by creating a new test with the
-following test scaffolding.
-
-:::info
-
-Clone the and refer to
-the
-[cypress/tests/demo/cypress-studio.cy.ts](https://github.com/cypress-io/cypress-realworld-app/blob/develop/cypress/tests/demo/cypress-studio.spec.ts)
-file.
-
-:::
-
-```js
-// Code from Real World App (RWA)
-describe('Cypress Studio Demo', () => {
- beforeEach(() => {
- // Seed database with test data
- cy.task('db:seed')
-
- // Login test user
- cy.database('find', 'users').then((user) => {
- cy.login(user.username, 's3cret', true)
- })
- })
-
- it('create new transaction', () => {
- // Extend test with Cypress Studio
- })
-})
-```
-
-#### Step 1 - Run the spec
-
-We'll use Cypress Studio to perform a "New Transaction" user journey. First,
-launch Cypress and select **End To End testing**, then choose a browser to run specs
-in.
-
-Once the browser is open, run the spec created in the previous step.
-
-
-
-#### Step 2 - Launch Cypress Studio
-
-Once the tests complete their run, hover over a test in the [Command Log](/app/core-concepts/open-mode#Command-Log) to
-reveal an **Add Commands to Test** button.
-
-Clicking on **Add Commands to Test** will launch the Cypress Studio.
-
-:::info
-
-Cypress will automatically execute all hooks and currently present test code,
-and then the test can be extended from that point on (e.g. We are logged into
-the application inside the `beforeEach` block).
-
-:::
-
-
-
-Next, Cypress will execute the test in isolation and pause after the last
-command in the test.
-
-Now, we can begin updating the test to create a new transaction between users.
-
-
-
-#### Step 3 - Interact with the Application
-
-To record actions, begin interacting with the application. Here we will click on
-the **New** button on the right side of the header and as a result we will see our
-click recorded in the Command Log.
+## How Cypress Studio works
-
+When Studio is enabled, you can:
-Next, we can start typing in the name of a user that we want to pay.
+- Generate test steps by interacting with your app in the Cypress browser
+- Add assertions by right-clicking DOM elements
+- Save or edit tests without leaving Cypress
-
+Supported action commands include: [`.click()`](/api/commands/click), [`.type()`](/api/commands/type), [`.check()`](/api/commands/check), [`.uncheck()`](/api/commands/uncheck), [`.select()`](/api/commands/select)
-Once we see the name come up in the results, we want to add an assertion to
-ensure that our search function works correctly. **Right click** on the user's
-name to bring up a menu from which we can add an assertion to check that the
-element contains the correct text (the user's name).
+Click the Studio panel button in the top right of the Cypress browser to open the Studio panel. You can also open the Studio panel by clicking **Edit in Studio** or **New test** in the Command Log.
-
+
-We can then click on that user in order to progress to the next screen. We'll
-complete the transaction form by clicking on and typing in the amount and
-description inputs.
+## Recording new tests
-
+You can record a new test with Cypress Studio inside any describe or context block.
-Now it's time to complete the transaction. You might have noticed that the "Pay"
-button was disabled before we typed into the inputs. To make sure that our form
-validation works properly, let's add an assertion to make sure the "Pay" button
-is enabled.
+1. Click **New Test** under the desired block
+2. Add a name for the test
+3. Enter the URL of the page you want to test (if not on the current page)
+4. Interact with your app (click, type, select elements)
+5. Right-click elements to add assertions
+6. Click **Save** to save the changes to your spec file
-
+## Extending existing tests
-Finally, we will click the "Pay" button and get presented with a confirmation
-page of our new transaction.
+You can also extend and update existing tests using Cypress Studio.
-
+1. Run the spec in Cypress
+2. Hover over the test in the Command Log
+3. Click **Edit in Studio** to open Cypress Studio
+4. Interact with your app to record actions
+5. Right-click to add assertions
+6. Click **Save** to save the changes to your spec file
-To discard the interactions, click the **Cancel** button to exit Cypress Studio.
-If satisfied with the interactions with the application, click **Save Commands**
-and the test code will be saved to your spec file. Alternatively you can choose
-the **copy** button in order to copy the generated commands to your clipboard.
+### How are selectors determined?
-#### Generated Test Code
+Cypress will automatically calculate a **unique selector** to use for a targeted
+element by running through a series of selector strategies.
-Viewing our test code, we can see that the test is updated after clicking **Save
-Commands** with the actions we recorded in Cypress Studio.
+
-```js
-// Code from Real World App (RWA)
-describe('Cypress Studio Demo', () => {
- beforeEach(() => {
- // Seed database with test data
- cy.task('db:seed')
-
- // Login test user
- cy.database('find', 'users').then((user) => {
- cy.login(user.username, 's3cret', true)
- })
- })
-
- it('create new transaction', () => {
- /* ==== Generated with Cypress Studio ==== */
- cy.get('[data-test=nav-top-new-transaction]').click()
- cy.get('[data-test=user-list-search-input]').clear()
- cy.get('[data-test=user-list-search-input]').type('dev')
- cy.get(
- '[data-test=user-list-item-tsHF6_D5oQ] > .MuiListItemText-root > .MuiListItemText-primary'
- ).should('have.text', 'Devon Becker')
- cy.get('[data-test=user-list-item-tsHF6_D5oQ]').click()
- cy.get('#amount').clear()
- cy.get('#amount').type('$25')
- cy.get('#transaction-create-description-input').clear()
- cy.get('#transaction-create-description-input').type('Sushi dinner')
- cy.get('[data-test=transaction-create-submit-payment]').should('be.enabled')
- cy.get('[data-test=transaction-create-submit-payment]').click()
- /* ==== End Cypress Studio ==== */
- })
-})
-```
-
-The selectors are generated according to the
-[`Cypress.SelectorPlayground` selector priority](/api/cypress-api/selector-playground-api#Default-Selector-Priority).
-
-### Adding a New Test
-
-You can add a new test to any existing `describe` or `context` block, by
-clicking **Add New Test** on our defined `describe` block.
-
-
-
-We are launched into Cypress Studio and can begin interacting with our
-application to generate the test.
-
-For this test, we will add a new bank account. Our interactions are as follows:
-
-1. Click "Bank Accounts" in left hand navigation
-
-2. Click the "Create" button on Bank Accounts page
-
-3. Fill out the bank account information
-
-4. Click the "Save" button
-
-
-To discard the interactions, click the **Cancel** button to exit Cypress Studio.
-
-If satisfied with the interactions with the application, click **Save Commands**
-and prompt will ask for the name of the test. Click **Save Test** and the test
-will be saved to the file.
-
-
-
-Once saved, the file will be run again in Cypress.
-
-
-
-Finally, viewing our test code, we can see that the test is updated after
-clicking **Save Commands** with the actions we recorded in Cypress Studio.
-
-```js
-// Code from Real World App (RWA)
-import { User } from 'models'
-
-describe('Cypress Studio Demo', () => {
- beforeEach(() => {
- cy.task('db:seed')
-
- cy.database('find', 'users').then((user: User) => {
- cy.login(user.username, 's3cret', true)
- })
- })
-
- it('create new transaction', () => {
- // Extend test with Cypress Studio
- })
-
- /* === Test Created with Cypress Studio === */
- it('create bank account', function () {
- /* ==== Generated with Cypress Studio ==== */
- cy.get('[data-test=sidenav-bankaccounts]').click()
- cy.get('[data-test=bankaccount-new] > .MuiButton-label').click()
- cy.get('#bankaccount-bankName-input').click()
- cy.get('#bankaccount-bankName-input').type('Test Bank Account')
- cy.get('#bankaccount-routingNumber-input').click()
- cy.get('#bankaccount-routingNumber-input').type('987654321')
- cy.get('#bankaccount-accountNumber-input').click()
- cy.get('#bankaccount-accountNumber-input').type('123456789')
- cy.get('[data-test=bankaccount-submit] > .MuiButton-label').click()
- /* ==== End Cypress Studio ==== */
- })
-})
-```
-
-:::info
+Cypress allows you to control how a selector is determined. Use the
+[`Cypress.ElementSelector`](/api/cypress-api/element-selector-api) API to control
+the selectors you want prioritized.
-Clone the and refer to
-the
-[cypress/tests/demo/cypress-studio.cy.ts](https://github.com/cypress-io/cypress-realworld-app/blob/develop/cypress/tests/demo/cypress-studio.spec.ts)
-file.
+## Limitations
-:::
+- Cypress Studio is currently only available for writing E2E tests, and doesn't
+ yet work with Component Testing.
+- Cypress Studio does not support writing tests that use domains of [multiple
+ origins](/app/guides/cross-origin-testing).
+- Cypress Studio can not interact with elements within a ShadowDom directly, though it can still run tests that do.
diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx
index e7a3e25611..324eb47b2e 100644
--- a/docs/app/references/changelog.mdx
+++ b/docs/app/references/changelog.mdx
@@ -8,6 +8,10 @@ sidebar_label: Changelog
# Changelog
+## 15.0.0
+
+_Released 7/29/2025 (PENDING)_
+
## 14.5.3
_Released 7/25/2025_
@@ -1861,7 +1865,7 @@ _Released 1/24/2023_
configured to exclude files with those extensions. Addresses
[#24495](https://github.com/cypress-io/cypress/issues/24495).
- Added support for the `data-qa` selector in the
- [Selector Playground](/api/cypress-api/selector-playground-api) in addition to
+ Selector Playground in addition to
`data-cy`, `data-test` and `data-testid`. Addresses
[#25305](https://github.com/cypress-io/cypress/issues/25305).
@@ -10916,14 +10920,14 @@ _Released 3/1/2018_
has been updated to automatically prefer `data-cy`, `data-test` or
`data-testid` attributes when providing the unique selector for an element.
Additionally it now exposes a
- [public API](/api/cypress-api/selector-playground-api) that you can use to
+ public API that you can use to
control how it determines which selector to use. Fixes
[#1135](https://github.com/cypress-io/cypress/issues/1135).
**Documentation Changes:**
- [Added `Selector Playground Guide`](/app/core-concepts/open-mode#Selector-Playground)
-- [Added `Selector Playground API`](/api/cypress-api/selector-playground-api)
+- Added `Selector Playground API`
- [Updated `Best Practices`](/app/core-concepts/best-practices)
- [Updated `FAQ`](/app/faq)
- [Updated `Introduction to Cypress`](/app/core-concepts/introduction-to-cypress)
diff --git a/docs/app/references/launching-browsers.mdx b/docs/app/references/launching-browsers.mdx
index 94c8e48711..0b4e9f7e95 100644
--- a/docs/app/references/launching-browsers.mdx
+++ b/docs/app/references/launching-browsers.mdx
@@ -216,22 +216,6 @@ Download the Mozilla geckodriver from the
:::
-##### Webdriver BiDi and CDP Deprecation
-
-:::info
-
-Since Firefox 129, Chrome DevTools Protocol (CDP) has been [deprecated in Firefox](https://fxdx.dev/deprecating-cdp-support-in-firefox-embracing-the-future-with-webdriver-bidi/).
-In Firefox 135 and above, Cypress defaults to automating the Firefox browser with WebDriver BiDi.
-Cypress will no longer support CDP within Firefox in the future and is planned for removal in Cypress 15.
-
-If CDP still needs to be used, you can force enablement via the `FORCE_FIREFOX_CDP=1` environment variable, regardless of Firefox version. For example:
-
-```bash
-FORCE_FIREFOX_CDP=1 npx cypress run --browser firefox
-```
-
-:::
-
### WebKit (Experimental)
Cypress has [experimental](/app/references/experiments) support for WebKit,
diff --git a/docs/app/references/migration-guide.mdx b/docs/app/references/migration-guide.mdx
index 6fdca31c66..c4751e9dc9 100644
--- a/docs/app/references/migration-guide.mdx
+++ b/docs/app/references/migration-guide.mdx
@@ -8,6 +8,177 @@ sidebar_label: 'Migration Guide'
# Migration Guide
+## Migrating to Cypress 15.0
+
+This guide details the code changes needed to migrate to Cypress
+version 15.
+[See the full changelog for version v15.0](/app/references/changelog#15-0-0).
+
+### Node.js 20, 22 and 24+ support
+
+Cypress requires [Node.js](https://nodejs.org/en) in order to install the Cypress binary and the supported versions are now Node.js 20, 22, 24 and above.
+Node.js versions 18 and 23 are no longer supported.
+[See Node's release schedule](https://github.com/nodejs/Release).
+
+### Unsupported Linux Distributions
+
+Prebuilt binaries for Linux are no longer compatible with Linux distributions based on glibc `<2.31`.
+This support is in line with Node.js's support for Linux in 20+.
+
+If you're using a Linux distribution based on glibc `<2.31`, you'll need to
+update your system to a newer version to install Cypress 15+.
+To display which version of glibc your Linux system is running, execute `ldd --version`.
+
+### Webpack `4` is no longer supported
+
+Cypress is no longer supporting Webpack `4` as it is no longer maintained by the core Webpack team and Webpack `5` has been available since Q4 2020. This includes dropping Webpack `4` support for:
+
+- `@cypress/webpack-dev-server` for component testing. This use case is most common and will require an update to Webpack `5`.
+ - `@cypress/webpack-dev-server` also no longer supports [Webpack Dev Server v4](https://github.com/webpack/webpack-dev-server/tree/v4.15.2). We shipped [Webpack Dev Server v5](https://github.com/webpack/webpack-dev-server/tree/v5.2.1) as the default in Cypress 14 with `webpack-dev-server@4` being an option.
+- `@cypress/webpack-preprocessor` for end-to-end testing. Cypress, by default, uses the [Webpack Batteries Included Preprocessor](https://github.com/cypress-io/cypress/blob/@cypress/webpack-batteries-included-preprocessor-v3.0.7/npm/webpack-batteries-included-preprocessor/README.md) to process your files for end-to-end testing, which has used Webpack 5 since Cypress 13. Unless you are already using `@cypress/webpack-preprocessor` as a standalone package, this change likely does not apply.
+
+#### To continue using Webpack `4`
+
+##### Component Testing
+
+If you haven't been able to migrate away from Webpack `4` or Webpack Dev Server `4` and still need to be able to run your component tests with Webpack `4` or Webpack Dev Server `4`, you can install the following packages independently:
+
+```sh
+npm install --save-dev @cypress/webpack-dev-server@4
+```
+
+and configure the dev server within your `cypress.config.js` or `cypress.config.ts` file:
+
+```js
+import { devServer } from '@cypress/webpack-dev-server'
+import { defineConfig } from 'cypress'
+
+export default defineConfig({
+ component: {
+ devServer(devServerConfig) {
+ return devServer({
+ ...devServerConfig,
+ framework: 'react',
+ webpackConfig: require('./webpack.config.js'),
+ })
+ },
+ },
+})
+```
+
+Note that this package version is deprecated and no longer supported by Cypress and is intended as a workaround until you can migrate to Webpack `5`. More information on how to configure the dev server `v4 `can be found in the [Cypress Webpack Dev Server documentation](https://github.com/cypress-io/cypress/blob/@cypress/webpack-dev-server-v4.0.2/npm/webpack-dev-server/README.md) and [Custom Dev Server documentation](/app/component-testing/component-framework-configuration#Custom-Dev-Server).
+
+##### End-to-End Testing
+
+If you haven't been able to migrate away from Webpack `4`, need custom end-to-end spec file preprocessing, are already using `@cypress/webpack-preprocessor` as a standalone package, and still need to be able to run your end-to-end tests with Webpack `4`, you can install the following package independently:
+
+```sh
+npm install --save-dev @cypress/webpack-preprocessor@6
+```
+
+and configure the preprocessor within your `cypress.config.js` or `cypress.config.ts` file:
+
+```js
+import { defineConfig } from 'cypress'
+import webpackPreprocessor from '@cypress/webpack-preprocessor'
+
+export default defineConfig({
+ e2e: {
+ setupNodeEvents(on, config) {
+ on('file:preprocessor', webpackPreprocessor())
+ },
+ },
+})
+```
+
+As stated earlier, this is likely unnecessary unless you are already using `@cypress/webpack-preprocessor` as a standalone package. Cypress by default uses the [Webpack Batteries Included Preprocessor](https://github.com/cypress-io/cypress/blob/@cypress/webpack-batteries-included-preprocessor-v3.0.7/npm/webpack-batteries-included-preprocessor/README.md) to process your spec files for end-to-end testing.
+
+Note that this package version is deprecated and no longer supported by Cypress and is intended as a workaround until you can migrate to Webpack `5`. More information on how to configure the preprocessor can be found in the [Preprocessors API documentation](/api/node-events/preprocessors-api#Usage) and [Webpack Preprocessor documentation](https://github.com/cypress-io/cypress/blob/@cypress/webpack-preprocessor-v6.0.4/npm/webpack-preprocessor/README.md).
+
+### `@cypress/webpack-batteries-included-preprocessor` no longer shims all built-ins provided by `webpack` v4
+
+The default file preprocessor, `@cypress/webpack-batteries-included-preprocessor`, no longer shims all built-ins that were previously provided by webpack v4. This is mainly to reduce security vulnerabilities and bundle size within the end-to-end file preprocessor.
+
+However, `@cypress/webpack-batteries-included-preprocessor` still ships with _some_ built-ins, such as `buffer`, `path`, `process`, `os`, and `stream`. If other built-ins are required, install `@cypress/webpack-batteries-included-preprocessor` independently and follow the webpack documentation described in [webpack's resolve.fallback](https://webpack.js.org/configuration/resolve/#resolvefallback) to configure the built-ins you need.
+
+For example, the following code shows how to provide the `querystring` built-in to the preprocessor:
+
+```javascript
+const webpackPreprocessor = require('@cypress/webpack-batteries-included-preprocessor')
+
+function getWebpackOptions() {
+ const options = webpackPreprocessor.getFullWebpackOptions()
+
+ // add built-ins as needed
+ // NOTE: for this example, querystring-es3 needs to be installed as a dependency
+ options.resolve.fallback.querystring = require.resolve('querystring-es3')
+ return options
+}
+
+module.exports = (on) => {
+ on(
+ 'file:preprocessor',
+ webpackPreprocessor({
+ webpackOptions: getWebpackOptions(),
+ })
+ )
+}
+```
+
+### Angular `17` CT no longer supported
+
+With [LTS end](https://angular.dev/reference/releases#actively-supported-versions) for Angular 17, the minimum required Angular version for component testing is now `18.0.0`.
+
+#### To continue using Angular below 18.0.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) `3.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 v18.0.0+.
+
+```sh
+npm install --save-dev @cypress/angular@3
+```
+
+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`
+```
+
+### Selector Playground API changes
+
+The `Cypress.SelectorPlayground` API has been renamed to
+[`Cypress.ElementSelector`](/api/cypress-api/element-selector-api). Additionally, the `onElement` function has been removed as an option to the `defaults` method.
+
+This change was made in order to reflect its use in features beyond just the Selector Playground - like Cypress Studio.
+
+The following code shows how to migrate from the `Cypress.SelectorPlayground` API to the
+[`Cypress.ElementSelector`](/api/cypress-api/element-selector-api) API.
+
+Before{' '}
+
+```ts
+Cypress.SelectorPlayground.defaults({
+ selectorPriority: ['class', 'id'],
+})
+```
+
+After
+
+```ts
+Cypress.ElementSelector.defaults({
+ selectorPriority: ['class', 'id'],
+})
+```
+
## Migrating to Cypress 14.0
This guide details the code changes needed to migrate to Cypress
diff --git a/docs/app/tooling/typescript-support.mdx b/docs/app/tooling/typescript-support.mdx
index 87ad0a22c2..89bf5ae148 100644
--- a/docs/app/tooling/typescript-support.mdx
+++ b/docs/app/tooling/typescript-support.mdx
@@ -29,7 +29,7 @@ tests in TypeScript.
### Install TypeScript
-To use TypeScript with Cypress, you will need TypeScript 4.0+. If you do not
+To use TypeScript with Cypress, you will need TypeScript 5.0+. If you do not
already have TypeScript installed as a part of your framework, you will need to
install it:
@@ -61,8 +61,8 @@ with the following configuration:
```json title="tsconfig.json"
{
"compilerOptions": {
- "target": "es5",
- "lib": ["es5", "dom"],
+ "target": "es6",
+ "lib": ["es6", "dom"],
"sourceMap": true,
"types": ["cypress", "node"]
},
@@ -94,23 +94,9 @@ If that does not work, try restarting the IDE.
### Processing your Cypress configuration and plugins
-Cypress needs to be able to transpile your Cypress configuration and plugins written in TypeScript in order to make them executable within Cypress's Node.js runtime. To do this, Cypress will attempt to read the user's TypeScript and project configuration to apply the correct TypeScript loader to Cypress's Node.js runtime.
+Under the hood, Cypress uses [tsx](https://tsx.is/) to parse and run the `cypress.config.ts` file.
-If your project is an `ESM` package (short for [ECMAScript Module](https://nodejs.org/api/esm.html#modules-ecmascript-modules)), Cypress attempts to apply the [ts-node/esm](https://github.com/TypeStrong/ts-node?tab=readme-ov-file#esm) Node.js loader to resolve the Cypress configuration and plugins. `ESM` is determined by Cypress if you have the `type: "module"` key-value pair present inside your project's `package.json`.
-
-Otherwise, regular [ts-node](https://github.com/TypeStrong/ts-node?tab=readme-ov-file#node-flags-and-other-tools) is required into Cypress's Node.js runtime.
-Since Node.js by itself can only interpret CommonJS files, Cypress attempts to make your TypeScript configuration compatible with Cypress' Node.js runtime.
-To do this, Cypress overrides the following configuration values found inside your project's `tsconfig.json`:
-
-```json
-{
- "module": "commonjs",
- "moduleResolution": "node",
- "preserveValueImports": false
-}
-```
-
-This does not have an impact on your project or its TypeScript configuration settings. This override only happens within the context of the Cypress runtime.
+This allows Cypress to run your TypeScript configuration inside the Cypress runtime without being bound to limitations of Node or other loaders.
## Extending TypeScript Support
@@ -380,12 +366,13 @@ root `tsconfig.json` file.
## History
-| Version | Changes |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------ |
-| [13.0.0](/app/references/changelog#13-0-0) | Raised minimum required TypeScript version from 3.4+ to 4.0+ |
-| [10.0.0](/app/references/changelog#10-0-0) | Update guide to cover TypeScript setup for component testing |
-| [5.0.0](/app/references/changelog#5-0-0) | Raised minimum required TypeScript version from 2.9+ to 3.4+ |
-| [4.4.0](/app/references/changelog#4-4-0) | Added support for TypeScript without needing your own transpilation through preprocessors. |
+| Version | Changes |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| [15.0.0](/app/references/changelog#15-0-0) | Raised minimum required TypeScript version from 4.0+ to 5.0+ and replaced `ts-node` with `tsx` to parse and run the `cypress.config.ts` file. |
+| [13.0.0](/app/references/changelog#13-0-0) | Raised minimum required TypeScript version from 3.4+ to 4.0+ |
+| [10.0.0](/app/references/changelog#10-0-0) | Update guide to cover TypeScript setup for component testing |
+| [5.0.0](/app/references/changelog#5-0-0) | Raised minimum required TypeScript version from 2.9+ to 3.4+ |
+| [4.4.0](/app/references/changelog#4-4-0) | Added support for TypeScript without needing your own transpilation through preprocessors. |
## See also
diff --git a/docs/partials/_default-selector-priority.mdx b/docs/partials/_default-selector-priority.mdx
index 5940fe01ab..71e8eed843 100644
--- a/docs/partials/_default-selector-priority.mdx
+++ b/docs/partials/_default-selector-priority.mdx
@@ -4,8 +4,9 @@
2. `data-test`
3. `data-testid`
4. `data-qa`
-5. `id`
-6. `class`
-7. `tag`
-8. `attributes`
-9. `nth-child`
+5. `name`
+6. `id`
+7. `class`
+8. `tag`
+9. `attributes`
+10. `nth-child`
diff --git a/static/img/app/core-concepts/cypress-click-coordinates-hitbox.png b/static/img/app/core-concepts/cypress-click-coordinates-hitbox.png
new file mode 100644
index 0000000000..82bdf2e7f0
Binary files /dev/null and b/static/img/app/core-concepts/cypress-click-coordinates-hitbox.png differ
diff --git a/static/img/app/core-concepts/cypress-failed-and-skipped-tests.png b/static/img/app/core-concepts/cypress-failed-and-skipped-tests.png
new file mode 100644
index 0000000000..f12568331f
Binary files /dev/null and b/static/img/app/core-concepts/cypress-failed-and-skipped-tests.png differ
diff --git a/static/img/app/core-concepts/cypress-failing-test.png b/static/img/app/core-concepts/cypress-failing-test.png
new file mode 100644
index 0000000000..7aeea3c815
Binary files /dev/null and b/static/img/app/core-concepts/cypress-failing-test.png differ
diff --git a/static/img/app/core-concepts/cypress-passing-test.png b/static/img/app/core-concepts/cypress-passing-test.png
new file mode 100644
index 0000000000..65582048c3
Binary files /dev/null and b/static/img/app/core-concepts/cypress-passing-test.png differ
diff --git a/static/img/app/core-concepts/cypress-pending-tests.png b/static/img/app/core-concepts/cypress-pending-tests.png
new file mode 100644
index 0000000000..5b6218644d
Binary files /dev/null and b/static/img/app/core-concepts/cypress-pending-tests.png differ
diff --git a/static/img/app/core-concepts/cypress-skipped-test.png b/static/img/app/core-concepts/cypress-skipped-test.png
new file mode 100644
index 0000000000..dd49f6a57e
Binary files /dev/null and b/static/img/app/core-concepts/cypress-skipped-test.png differ
diff --git a/static/img/app/core-concepts/hitbox.png b/static/img/app/core-concepts/hitbox.png
deleted file mode 100644
index 371340c726..0000000000
Binary files a/static/img/app/core-concepts/hitbox.png and /dev/null differ
diff --git a/static/img/app/core-concepts/open-mode/application-under-test.png b/static/img/app/core-concepts/open-mode/application-under-test.png
index 49eddc5779..ecaf371e3b 100644
Binary files a/static/img/app/core-concepts/open-mode/application-under-test.png and b/static/img/app/core-concepts/open-mode/application-under-test.png differ
diff --git a/static/img/app/core-concepts/open-mode/aut-error-e2e.png b/static/img/app/core-concepts/open-mode/aut-error-e2e.png
index 4245c3da53..2d94958f0b 100644
Binary files a/static/img/app/core-concepts/open-mode/aut-error-e2e.png and b/static/img/app/core-concepts/open-mode/aut-error-e2e.png differ
diff --git a/static/img/app/core-concepts/open-mode/command-log.png b/static/img/app/core-concepts/open-mode/command-log.png
index 1d1426f622..07ff73220b 100644
Binary files a/static/img/app/core-concepts/open-mode/command-log.png and b/static/img/app/core-concepts/open-mode/command-log.png differ
diff --git a/static/img/app/core-concepts/open-mode/viewport-scaling.png b/static/img/app/core-concepts/open-mode/viewport-scaling.png
index ff358c28d8..07eba0edb5 100644
Binary files a/static/img/app/core-concepts/open-mode/viewport-scaling.png and b/static/img/app/core-concepts/open-mode/viewport-scaling.png differ
diff --git a/static/img/app/core-concepts/reload-page.gif b/static/img/app/core-concepts/reload-page.gif
deleted file mode 100644
index 3ba5789b92..0000000000
Binary files a/static/img/app/core-concepts/reload-page.gif and /dev/null differ
diff --git a/static/img/app/core-concepts/todo-mvc-2-tests-passing.png b/static/img/app/core-concepts/todo-mvc-2-tests-passing.png
deleted file mode 100644
index 1cc7779e03..0000000000
Binary files a/static/img/app/core-concepts/todo-mvc-2-tests-passing.png and /dev/null differ
diff --git a/static/img/app/core-concepts/todo-mvc-failed-and-skipped-tests.png b/static/img/app/core-concepts/todo-mvc-failed-and-skipped-tests.png
deleted file mode 100644
index 5294575f94..0000000000
Binary files a/static/img/app/core-concepts/todo-mvc-failed-and-skipped-tests.png and /dev/null differ
diff --git a/static/img/app/core-concepts/todo-mvc-failing-test.png b/static/img/app/core-concepts/todo-mvc-failing-test.png
deleted file mode 100644
index b2593443c0..0000000000
Binary files a/static/img/app/core-concepts/todo-mvc-failing-test.png and /dev/null differ
diff --git a/static/img/app/core-concepts/todo-mvc-passing-test.png b/static/img/app/core-concepts/todo-mvc-passing-test.png
deleted file mode 100644
index 036ae0cafb..0000000000
Binary files a/static/img/app/core-concepts/todo-mvc-passing-test.png and /dev/null differ
diff --git a/static/img/app/core-concepts/todo-mvc-pending-tests.png b/static/img/app/core-concepts/todo-mvc-pending-tests.png
deleted file mode 100644
index 6696566edc..0000000000
Binary files a/static/img/app/core-concepts/todo-mvc-pending-tests.png and /dev/null differ
diff --git a/static/img/app/core-concepts/todo-mvc-skipped-test.png b/static/img/app/core-concepts/todo-mvc-skipped-test.png
deleted file mode 100644
index 5549dc9e0f..0000000000
Binary files a/static/img/app/core-concepts/todo-mvc-skipped-test.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/add-test-1.png b/static/img/app/cypress-studio/add-test-1.png
deleted file mode 100644
index 23fd14bafd..0000000000
Binary files a/static/img/app/cypress-studio/add-test-1.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/add-test-2.png b/static/img/app/cypress-studio/add-test-2.png
deleted file mode 100644
index 3af5c01433..0000000000
Binary files a/static/img/app/cypress-studio/add-test-2.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/add-test-create.png b/static/img/app/cypress-studio/add-test-create.png
deleted file mode 100644
index 7c21ca2184..0000000000
Binary files a/static/img/app/cypress-studio/add-test-create.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/add-test-final.png b/static/img/app/cypress-studio/add-test-final.png
deleted file mode 100644
index 9a7fbcc5ea..0000000000
Binary files a/static/img/app/cypress-studio/add-test-final.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/add-test-form-complete.png b/static/img/app/cypress-studio/add-test-form-complete.png
deleted file mode 100644
index e3e4827c48..0000000000
Binary files a/static/img/app/cypress-studio/add-test-form-complete.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/add-test-form-save.png b/static/img/app/cypress-studio/add-test-form-save.png
deleted file mode 100644
index 27887b0d8e..0000000000
Binary files a/static/img/app/cypress-studio/add-test-form-save.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/add-test-save-test.png b/static/img/app/cypress-studio/add-test-save-test.png
deleted file mode 100644
index 1f2895d3f4..0000000000
Binary files a/static/img/app/cypress-studio/add-test-save-test.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/cypress-studio-beta-button.png b/static/img/app/cypress-studio/cypress-studio-beta-button.png
new file mode 100644
index 0000000000..fb073b4302
Binary files /dev/null and b/static/img/app/cypress-studio/cypress-studio-beta-button.png differ
diff --git a/static/img/app/cypress-studio/extend-activate-studio.png b/static/img/app/cypress-studio/extend-activate-studio.png
deleted file mode 100644
index 62565f9085..0000000000
Binary files a/static/img/app/cypress-studio/extend-activate-studio.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/extend-assert-button-enabled.png b/static/img/app/cypress-studio/extend-assert-button-enabled.png
deleted file mode 100644
index 9302784227..0000000000
Binary files a/static/img/app/cypress-studio/extend-assert-button-enabled.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/extend-assert-user-name.png b/static/img/app/cypress-studio/extend-assert-user-name.png
deleted file mode 100644
index 930a301344..0000000000
Binary files a/static/img/app/cypress-studio/extend-assert-user-name.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/extend-click-new-transaction.png b/static/img/app/cypress-studio/extend-click-new-transaction.png
deleted file mode 100644
index ec970bb639..0000000000
Binary files a/static/img/app/cypress-studio/extend-click-new-transaction.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/extend-ready.png b/static/img/app/cypress-studio/extend-ready.png
deleted file mode 100644
index 1df2ed8542..0000000000
Binary files a/static/img/app/cypress-studio/extend-ready.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/extend-save-test.png b/static/img/app/cypress-studio/extend-save-test.png
deleted file mode 100644
index b3e1330fd3..0000000000
Binary files a/static/img/app/cypress-studio/extend-save-test.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/extend-type-transaction-form.png b/static/img/app/cypress-studio/extend-type-transaction-form.png
deleted file mode 100644
index 116634caeb..0000000000
Binary files a/static/img/app/cypress-studio/extend-type-transaction-form.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/extend-type-user-name.png b/static/img/app/cypress-studio/extend-type-user-name.png
deleted file mode 100644
index e89c010bcf..0000000000
Binary files a/static/img/app/cypress-studio/extend-type-user-name.png and /dev/null differ
diff --git a/static/img/app/cypress-studio/run-spec-1.png b/static/img/app/cypress-studio/run-spec-1.png
deleted file mode 100644
index fc4b03c444..0000000000
Binary files a/static/img/app/cypress-studio/run-spec-1.png and /dev/null differ
diff --git a/static/img/app/end-to-end-testing/writing-your-first-end-to-end-test/new-spec-test-run.png b/static/img/app/end-to-end-testing/writing-your-first-end-to-end-test/new-spec-test-run.png
index e2926bcaa5..d9a5de35dc 100644
Binary files a/static/img/app/end-to-end-testing/writing-your-first-end-to-end-test/new-spec-test-run.png and b/static/img/app/end-to-end-testing/writing-your-first-end-to-end-test/new-spec-test-run.png differ
diff --git a/static/img/app/get-started/e2e/first-test-failing-contains.png b/static/img/app/get-started/e2e/first-test-failing-contains.png
index 534beb782c..b039f950be 100644
Binary files a/static/img/app/get-started/e2e/first-test-failing-contains.png and b/static/img/app/get-started/e2e/first-test-failing-contains.png differ
diff --git a/static/img/app/get-started/e2e/first-test-failing.png b/static/img/app/get-started/e2e/first-test-failing.png
index f2d893b86e..e3e1cdeb36 100644
Binary files a/static/img/app/get-started/e2e/first-test-failing.png and b/static/img/app/get-started/e2e/first-test-failing.png differ
diff --git a/static/img/app/get-started/e2e/first-test.png b/static/img/app/get-started/e2e/first-test.png
index 9079eeb2ba..b01a517f93 100644
Binary files a/static/img/app/get-started/e2e/first-test.png and b/static/img/app/get-started/e2e/first-test.png differ
diff --git a/static/img/app/get-started/e2e/search-box.png b/static/img/app/get-started/e2e/search-box.png
deleted file mode 100644
index 73edb89e48..0000000000
Binary files a/static/img/app/get-started/e2e/search-box.png and /dev/null differ
diff --git a/static/img/app/get-started/e2e/testing-your-app-home-page-spec.png b/static/img/app/get-started/e2e/testing-your-app-home-page-spec.png
index e5c69e7054..b2d35bbadb 100644
Binary files a/static/img/app/get-started/e2e/testing-your-app-home-page-spec.png and b/static/img/app/get-started/e2e/testing-your-app-home-page-spec.png differ
diff --git a/static/img/app/get-started/e2e/testing-your-app-visit-fail.png b/static/img/app/get-started/e2e/testing-your-app-visit-fail.png
index af02945f81..dcacd04ffb 100644
Binary files a/static/img/app/get-started/e2e/testing-your-app-visit-fail.png and b/static/img/app/get-started/e2e/testing-your-app-visit-fail.png differ