diff --git a/docs/api/cypress-api/element-selector-api.mdx b/docs/api/cypress-api/element-selector-api.mdx index d2838d60c3..ba67621808 100644 --- a/docs/api/cypress-api/element-selector-api.mdx +++ b/docs/api/cypress-api/element-selector-api.mdx @@ -1,6 +1,6 @@ --- title: 'Cypress.ElementSelector | Cypress Documentation' -description: 'Customize how Cypress chooses selectors in Studio and Selector Playground by setting your preferred selector strategy.' +description: 'Customize how Cypress chooses selectors in Studio and cy.prompt() by setting your preferred selector strategy.' sidebar_label: ElementSelector sidebar_position: 105 --- @@ -9,7 +9,7 @@ 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). +The ElementSelector API lets you define how Cypress selects elements in tools like [Cypress Studio](/app/guides/cypress-studio) and [cy.prompt()](/api/commands/prompt). 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. @@ -72,7 +72,7 @@ The [jQuery element](http://api.jquery.com/Types/#jQuery) for which you want to ### 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). +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 [cy.prompt()](/api/commands/prompt) For example, this config tells Cypress to prefer semantic and accessibility attributes before falling back to styling details like class names. @@ -158,4 +158,4 @@ Cypress.ElementSelector.defaults({ ## See also - [Cypress Studio](/app/guides/cypress-studio) -- [Selector Playground](/app/core-concepts/open-mode#Selector-Playground) +- [cy.prompt()](/api/commands/prompt) diff --git a/docs/api/table-of-contents.mdx b/docs/api/table-of-contents.mdx index 8e5f8b8681..4e09f569b2 100644 --- a/docs/api/table-of-contents.mdx +++ b/docs/api/table-of-contents.mdx @@ -191,29 +191,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.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. | +| 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 [cy.prompt()](/api/commands/prompt). | +| [`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/core-concepts/best-practices.mdx b/docs/app/core-concepts/best-practices.mdx index 27b9f3e0f2..4b73c30b9e 100644 --- a/docs/app/core-concepts/best-practices.mdx +++ b/docs/app/core-concepts/best-practices.mdx @@ -144,21 +144,6 @@ meaning it's not coupled to the **behavior** or **styling** of an element. Additionally, it makes it clear to everyone that this element is used directly by test code. -:::info - -Did you know? - -The [Selector Playground](/app/core-concepts/open-mode#Selector-Playground) -automatically follows these best practices. - -When determining a unique selector, it will automatically prefer elements with: - -- `data-cy` -- `data-test` -- `data-testid` - -::: - #### Real World Example The uses two useful diff --git a/docs/app/core-concepts/open-mode.mdx b/docs/app/core-concepts/open-mode.mdx index 60822db423..6420d32b28 100644 --- a/docs/app/core-concepts/open-mode.mdx +++ b/docs/app/core-concepts/open-mode.mdx @@ -1,6 +1,6 @@ --- title: Open Mode -description: The different sections of the Cypress app in open mode, the information surfaced in the app's Command Log, how to use the Selector Playground to find unique selectors, and debugging tools available in the app in open mode. +description: Learn how Cypress open mode works, including the Test Runner, Command Log, Cypress Studio for recording interactions and inline edits, and tools for debugging tests in the Cypress app. sidebar_position: 60 --- @@ -14,14 +14,13 @@ sidebar_position: 60 - The different sections of the Cypress app in open mode - The information surfaced in the app's Command Log -- How to use the Selector Playground to find unique selectors +- How to hide HTTP requests in the Command Log +- How to use Cypress Studio to record interactions and edit tests inline - Debugging tools available in the app in open mode ::: -The Cypress App has powerful features for creating, configuring, -browsing, and most importantly running your tests once you [open the app](/app/get-started/open-the-app). -Open mode is the heart of the Cypress testing experience. +The Cypress app includes an interactive workflow called open mode. In Cypress open mode you can run specs, watch the Command Log update in real time, and inspect the application or component under test. You can [open the app](/app/get-started/open-the-app), use Cypress Studio to record interactions and edit tests inline, and debug with time travel snapshots and console output. Open mode is best for local development, while recorded runs in Cypress Cloud provide history and analytics when needed. ### Launchpad @@ -30,13 +29,10 @@ Open mode is the heart of the Cypress testing experience. alt="The Launchpad" /> -The Launchpad is your portal to Cypress, helping with onboarding, choosing a -testing type and launching a browser. +The Launchpad helps you choose a testing type, pick a browser, and open your project. It also guides first time setup when needed so you can start running specs with the right configuration. -Once you get comfortable with Cypress you might find you don't need the -Launchpad any more. In this case -[you can run `cypress open` with the `--browser` and `--component` or `--e2e` options](/app/references/command-line#cypress-open) -to go straight to the Specs page. +If you prefer to skip the Launchpad, run +[`cypress open`](/app/references/command-line#cypress-open) with `--browser` and either `--component` or `--e2e` to go directly to the Specs page. ### Specs @@ -45,43 +41,21 @@ to go straight to the Specs page. alt="Specs" /> -On choosing your browser in the Launchpad, you'll be presented with a list of -your specs, their names, locations, and information about your latest recorded -runs. Here you can launch specs by clicking them, create new blank or example -specs, or search specs by name (handy for large test suites). +After you pick a browser, the Specs page lists your spec files with name, path, and recent run details. Click a spec to run it, create a new spec, or search by name. -We've made the following spec data available directly on the Specs page: +The Specs page shows: #### Last updated -This column tells you when the code of this spec was last updated, using local -file data from git or your own filesystem. It surfaces the change history of -your tests, so you can quickly find the most relevant specs as you're browsing -your project. - -This column will vary from machine to machine, as it reflects the state of the -code as stored on that computer. +Shows when the spec file last changed on your machine, based on git or filesystem data. Values can differ across machines. #### Latest runs -This column shows the last time the spec was run, and the last four returned -statuses. Results are scoped to your current git branch if available, falling -back to the default branch if not, then finally all branches. - -With this intelligence you can monitor, run, and fix tests locally within CI -workflows, and then further dig into your results by clicking through to Cypress -Cloud. - -The runs data is sourced from Cypress Cloud so it -will be the same everywhere. +Shows the last time the spec ran and the last four statuses. Results are scoped to your current git branch when available, then the default branch, then all branches. Data comes from Cypress Cloud. #### Average duration -This column indicates the time taken to run the entire spec file, averaged over -the last four runs, so that you can quickly identify and take action to improve -the performance of your long-running tests. - -Again, this analysis comes from Cypress Cloud. +Shows the average time to run the spec, calculated from the last four runs. Useful for spotting slow specs. Data comes from Cypress Cloud. #### Flake annotation @@ -94,124 +68,70 @@ can pass and fail across multiple retry attempts without any code changes. ::: -Specs with flaky tests are flagged with an indicator beside the spec name. This -means you can easily discern which areas of your application might result in an -unreliable user experience. - -The flake indicator will display if any tests in the given spec have been flaky -in your latest runs (limited to 4). Hovering over the indicator will show a -tooltip with the following analytics, based off the last **50** runs: - -- Rate (flaky runs divided by total runs) -- Severity (flaky rate at a glance) -- Last flaky (how many runs ago) - -Clicking on the flake indicator will take you to the spec's -[Flaky Test Analytics in Cypress Cloud](https://cloud.cypress.io/projects/7s5okt/analytics/flaky-tests). +Specs with flaky tests show an indicator next to the name. Hover to see rate, severity, and last flaky across the last 50 runs. Click to open Flaky Test Analytics in Cypress Cloud. #### Running Specs -To run a spec, simply click the row with the spec you would like to run. You -will be taken to the [Test Runner](#Test-Runner) and the spec will execute. You -can narrow down the list of specs by typing into the search bar (1). +Click a spec to open the [Test Runner](#Test-Runner) and run it. Use the search bar to filter by name. -It is also possible to run multiple specs sequentially using the -[`experimentalRunAllSpecs`](/app/references/experiments#End-to-End-Testing) -(2). +You can run multiple specs sequentially using [`experimentalRunAllSpecs`](/app/references/experiments#End-to-End-Testing). :::caution Experimental Run All Specs -`experimentalRunAllSpecs` currently works with End to End Testing. - -Running multiple specs sequentially is currently an -[experimental feature](/app/references/configuration#Experiments) and it may -change in the future. There are some known limitations outlined in this -[GitHub Discussion](https://github.com/cypress-io/cypress/discussions/21628). - -Running a large number of specs sequentially can consume more resources. +`experimentalRunAllSpecs` works with End to End Testing. The feature is experimental and may change. Review known limitations in the linked [GitHub Discussion](https://github.com/cypress-io/cypress/discussions/21628). Running many specs in sequence can consume more resources. ::: ### Runs -When you configure the open source Cypress app to record tests to -[Cypress Cloud](/cloud/get-started/introduction), you'll see data from your latest -[recorded runs](/cloud/features/recorded-runs#Latest-Runs) directly in the Cypress app. This increased visibility into your -test history allows you to debug your tests faster and more effectively, all -within your local workflow. +When your project records to [Cypress Cloud](/cloud/get-started/introduction), the app shows your latest [recorded runs](/cloud/features/recorded-runs#Latest-Runs) directly in open mode. This gives branch scoped results in context while you debug locally. -If you're not sure whether you're logged in, you can always check using the -profile control in the top right of the window. +- **Authentication:** Sign in to Cypress Cloud using the profile in the top right. +- **Branch scoping:** Cypress reads your current git branch to scope results. It first shows runs from that branch. If no runs are found, it falls back to the default branch, then to all branches. +- **Git information:** To scope runs correctly, the app needs git metadata. Ensure git is available and that you send git information to Cypress Cloud. In some environments, such as `docker` or `docker-compose`, pass git information with [custom environment variables](/app/continuous-integration/overview#Git-information). +- **Run titles:** Each run title comes from the git commit message. Click a run to open it in Cypress Cloud. -Cypress uses Git to show runs for your branch. Ensure that version control is -properly configured and that you are sending Git information to Cypress Cloud. Under some -environment setups (e.g. `docker`/`docker-compose`), you may have to pass git -information using -[custom environment variables](/app/continuous-integration/overview#Git-information). -If no runs are found for your current branch, all runs for your project are -shown as a fallback. - -The title of each run is taken from the -[git commit message](https://www.educative.io/edpresso/git-commit-message-simply-explained) -for that change, and clicking on it will take you to the corresponding run page -in Cypress Cloud. - ### Debug -The Debug page allows you to easily debug failed CI test runs from within the -Cypress app. From this page, you can review, rerun, and debug failed CI test -runs that are recorded to [Cypress Cloud](/cloud/get-started/introduction) - all -without leaving the Cypress app. +The Debug page in the Cypress app helps you investigate failed CI test runs recorded to [Cypress Cloud](/cloud/get-started/introduction) without leaving the app. You can review failures, rerun only the failed tests, and open [Test Replay](/cloud/features/test-replay) along with screenshots, videos, and logs. - + -This feature eliminates the tedious process of switching between Cypress, your -local editor, and CI output, in order to fix failed tests. It does this by -enabling you to use the app to run only the tests that -failed in your last recorded test run, as well as review the -[Test Replay](/cloud/features/test-replay) and other artifacts like screenshots, -videos, and logs from your tests. +#### What the Debug page shows -#### What does the Debug page show? +- Latest completed [recorded run](/cloud/features/recorded-runs#Latest-Runs) that matches the `HEAD` commit of your working directory +- If none is found, the most recent run on your current branch, then the default branch +- The first 100 failed tests, each with a link to view the full run in Cypress Cloud and open Test Replay -The Debug page shows the latest completed -[test run](/cloud/features/recorded-runs#Latest-Runs) that matches the `HEAD` commit -(the commit currently checked out in the working directory) of your local -project. Users can see and switch to relevant runs within the Debug page. If no -run is found for your current commit, then Cypress shows the most recent run in -your branch's history up until the current commit. The first **100** failed -tests are listed, with a link to Cypress Cloud to review the full run. +#### Requirements -To use this feature, you must ensure that git is properly configured for your -project and that you are sending git information to Cypress Cloud. Under some -environment setups (e.g. `docker`/`docker-compose`), you may have to pass git -information using -[custom environment variables](/app/continuous-integration/overview#Git-information). +- **Authentication:** Sign in to Cypress Cloud using the profile in the top right. +- **Git information:**Provide git metadata so the app can match your `HEAD` commit and branch. In environments like `docker` or `docker-compose`, pass git information with [custom environment variables](/app/continuous-integration/overview#Git-information) -### Cloud Run Notifications +### Cloud run notifications -You can receive notifications in the Cypress app for recorded runs directly from -Cypress Cloud. Learn more about [Cloud Run Notifications](/cloud/features/recorded-runs#Notifications). +Get notifications in the Cypress app for recorded runs from [Cypress Cloud](/cloud/get-started/introduction). Notifications appear in open mode when you are signed in and your project records to Cloud. Click a notification to open the run in Cypress Cloud. Learn more in [Cloud run notifications](/cloud/features/recorded-runs#Notifications). ## Test Runner -At the core of the app is the Test Runner itself. Cypress runs tests -interactively, allowing you to see commands as they execute while also viewing -the Application or Component Under Test, and exploring its DOM. +The Cypress Test Runner is where you run and debug specs in open mode. It executes commands step by step, renders the Application or Component Under Test, and streams details to the Command Log so you can see what happened and why. Use the Test Runner to reproduce failures, inspect the DOM, and iterate quickly during development. :::tip @@ -222,28 +142,23 @@ experience in [Test Replay](/cloud/features/test-replay) for runs recorded in CI ## Command Log -The left-hand side of the Test Runner is a visual representation of your test -suite. Each test block is properly nested and each test, when clicked, displays -every Cypress command executed within the test's block as well as any commands -executed in relevant `before`, `beforeEach`, `afterEach`, and `after` hooks. +The Cypress Command Log (left panel) lists every command and hook in order for each test in the spec file. Click a test to expand its commands, including commands from `before`, `beforeEach`, `afterEach`, and `after` hooks. Each entry is interactive and links to a snapshot and console details so you can see what happened and why. ### Open files in your IDE -There are some places in the Command Log that display a link to the relevant -file where the code is located. Clicking on this link will open the file in your -[preferred file opener](/app/tooling/IDE-integration#File-Opener-Preference). +Links in the Command Log often point to the source file where a command is defined. Click a link to open the file in your [preferred file opener](/app/tooling/IDE-integration#File-Opener-Preference). -Cypress automatically travels back in time to a snapshot of when a hovered-over -command resolved. Additionally, since [`cy.contains()`](/api/commands/contains) -finds DOM elements on the page, Cypress also highlights the element and scrolls -it into view (to the top of the page). +When you hover over a command, Cypress restores the snapshot from when that command resolved. Because [`cy.contains()`](/api/commands/contains) finds a DOM element, Cypress highlights the element and scrolls it into view. -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. +While you hover over [`cy.contains()`](/api/commands/contains), Cypress also restores the URL that was present when the snapshot was taken. ### Pinning snapshots -Each command, when clicked on, displays extra information in the dev tools -console. Clicking also **pins** the Application or Component Under Test -(right-hand side) to its previous state, or **snapshot**, when the command -executed. +Click any command to pin its snapshot. Pinning locks the Application or Component Under Test to the state it had when that command executed and opens extra details in the console. -In the following example, clicking on the `CLICK` command highlights it in -purple, and does three other things worth noting: +In this example, clicking the `CLICK` command highlights it and shows: -#### 1. Pinned snapshots +#### 1. Pinned snapshot -We have now **pinned** this snapshot. Hovering over other commands will not -revert to them. This gives us a chance to manually inspect the DOM of our -application under test at the time the snapshot was taken. +The snapshot is pinned. Hovering other commands does not change the preview, which lets you inspect the DOM at that moment in time. #### 2. Event hitbox -Since [`.click()`](/api/commands/click) is an action command, that means we also -see a red hitbox at the coordinates the event took place. - -#### 3. Snapshot menu panel +Action commands like [`.click()`](/api/commands/click) show a red hitbox at the event coordinates. -There is also a new menu panel. Some commands (like action commands) will take -multiple snapshots: **before** and **after**. We can now cycle through these. +#### 3. Snapshot menu -The **before** snapshot is taken prior to the click event firing. The **after** -snapshot is taken immediately after the click event. Although this click event -caused our browser to load a new page, it's not an instantaneous transition. -Depending on how fast your page loaded, you may still see the same page, or a -blank screen as the page is unloading and in transition. - -When a command causes an immediate visual change in our application, cycling -between before and after will update our snapshot. We can see this in action by -clicking the `TYPE` command in the Command Log. Now, clicking **before** will -show us the input in a default state, showing the placeholder text. Click -**after** will show us what the input looks like when the `TYPE` command has -completed. +Some commands capture multiple snapshots, for example action commands capture both before and after. Use the snapshot menu to switch between them. This is useful when an action triggers a visible change, such as typing into an input. ### Page events -In addition to showing all the commands that were called, the command log also -shows important events from your application or component when they occur. -Notice these look different (they are gray and without a number). +The Command Log also records application events. These entries appear in gray without a number. -**Cypress logs out page events for:** +**Cypress logs page events for:** -- Network XHR Requests +- Network XHR and fetch requests - URL hash changes -- Page Loads -- Form Submissions +- Page loads +- Form submissions + +### Hide HTTP Requests + +When you do not need to inspect network calls, you can hide HTTP requests in the Command Log to reduce noise. Use the Hide HTTP Requests control in the Command Log header to collapse entries for XHR and fetch requests. This makes it easier to focus on the commands that interact with the page. + +Hiding HTTP requests does not change how your tests run. It only affects what is displayed in the Command Log. Requests still execute and remain available to assertions and tooling like [`cy.intercept()`](/api/commands/intercept). ### Instrument panel -For certain commands like [`cy.intercept()`](/api/commands/intercept), -[`cy.stub()`](/api/commands/stub), and [`cy.spy()`](/api/commands/spy), an extra -instrument panel is displayed above the test to give more information about the -state of your tests. +When you use [`cy.intercept()`](/api/commands/intercept), [`cy.stub()`](/api/commands/stub), or [`cy.spy()`](/api/commands/spy), the instrument panel appears above the test. It summarizes routes, stubs, and spies so you can quickly inspect network traffic and function calls while you debug. #### Routes @@ -414,46 +301,35 @@ DOM is completely available for debugging. #### 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 -[Cypress configuration](/app/references/configuration#Viewport). If the AUT -does not fit within the current browser window, it is scaled appropriately to -fit within the window. +The application preview honors the size and orientation defined in your tests. Control the viewport with [`cy.viewport()`](/api/commands/viewport) or set defaults in your [Cypress configuration](/app/references/configuration#Viewport). If the preview does not fit in the browser window, Cypress scales it to fit. 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 `90%`. +The image below shows an application at `1000px` by `660px`, scaled to `90%`. #### Errors -The right-hand side may also be used to display syntax errors in your spec file -that prevent the tests from running. +Cypress surfaces syntax errors in your spec file directly in the preview so you can fix them when tests run. This helps catch typos and missing imports early. ### Component Under Test -In -[Component testing](/app/core-concepts/testing-types#What-is-Component-Testing), -the right-hand side of the Test Runner is used to display the Component Under -Test (CUT): the component that was mounted using the -[`cy.mount()`](/api/commands/mount) command. +In [component testing](/app/core-concepts/testing-types#What-is-Component-Testing), the right side of the Test Runner renders the component under test (CUT). Mount the component with [`cy.mount()`](/api/commands/mount) and interact with it in a real browser to validate behavior and accessibility. In the following example, we have the following test in our spec file: @@ -480,182 +356,67 @@ it('should have password input of type password', () => { -In the corresponding Component Preview below, you can see the `LoginForm` -component is being displayed in the right-hand side. Not only is the component -visible, but it is fully interactable. You can open your developer tools to -inspect elements as you would in your normal application. The DOM is completely -available for debugging. +In the preview below, the `LoginForm` component is rendered on the right. The component is fully interactive. Open developer tools to inspect elements as you would in your application. The DOM is available for debugging. -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 -[Cypress configuration](/app/references/configuration#Viewport). If the AUT -does not fit within the current browser window, it is scaled appropriately to -fit within the window. - -The current size and scale of the AUT is displayed in the top right corner of -the window. +The component preview uses the size and orientation defined by your test. Adjust it with [`cy.viewport()`](/api/commands/viewport) or configure defaults in [Cypress configuration](/app/references/configuration#Viewport). If the preview does not fit in the window, Cypress scales it. The current size and scale appear in the top right. -The image below shows that our application is displaying at `500px` width, -`500px` height and scaled to `100%`. +The image below shows the preview at `800px` by `850px`, scaled to `70%`. -The right-hand side may also be used to display syntax errors in your spec file -that prevent the tests from running. +Cypress also surfaces syntax errors in component specs in the preview so you can correct issues when the test executes. -## Selector Playground +## Cypress Studio -:::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. -::: +[Cypress Studio](/app/guides/cypress-studio) is part of open mode. Use Studio to record interactions and generate Cypress commands, then edit tests inline without leaving the app. Changes are saved to your spec file so your tests stay in code. -The Selector Playground is an interactive feature that helps you: - -- Determine a unique selector for an element. -- See what elements match a given selector. -- See what element matches a string of text. - -:::tip - -Need a low code approach to create tests? Use -[Cypress Studio](/app/guides/cypress-studio) to record your browser -interactions. - -::: +To learn how to start Studio, record actions, add assertions, and edit tests, see the [Cypress Studio guide](/app/guides/cypress-studio). -### How are selectors determined? - -Cypress will automatically calculate a **unique selector** to use for a targeted -element by running through a series of selector strategies. - - - -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 - -You may find yourself struggling to write good selectors because: - -- Your application or component uses dynamic ID's and class names -- Your tests break whenever there are CSS or content changes - -To help with these common challenges, the Selector Playground automatically -prefers certain `data-*` attributes when determining a unique selector. - -Please read our -[Best Practices guide](/app/core-concepts/best-practices#Selecting-Elements) on -helping you target elements and prevent tests from breaking on CSS or JS -changes. - -### Finding selectors - -To open the Selector Playground, click the button -next to the URL at the top of the Test Runner. Hover over elements in your app -to preview a unique selector for that element in the tooltip. - - - -Click on the element and its selector will appear at the top. From there, you -can copy it to your clipboard ( ) or print it to the -console ( ). - - - -### Running experiments - -The box at the top that displays the selector is also a text input. - -#### Editing a selector - -When you edit the selector, it will show you how many elements match and -highlight those elements in your app. - - - -#### Switching to contains - -You can also experiment with what [`cy.contains()`](/api/commands/contains) -would yield given a string of text. Click on `cy.get` and switch to -`cy.contains`. - -Type in text to see which element it matches. Note that -[`cy.contains()`](/api/commands/contains) only yields the first element that -matches the text, even if multiple elements on the page contain the text. - - - -#### Disabling highlights - -If you would like to interact with your app while the Selector Playground is -open, the element highlighting might get in the way. Toggling the highlighting -off will allow you to interact with your app more easily. +## Keyboard shortcuts - +Cypress keyboard shortcuts help you work faster in open mode. -## Keyboard shortcuts +**Keyboard shortcuts in open mode** -There are keyboard shortcuts to quickly perform common actions from within -Cypress. +| Key | Action | +| ----------------------------------------- | --------------------------- | +| `r` | Rerun tests | +| `s` | Stop tests | +| `f` | Bring focus to specs window | +| `⌘+s` (macOS) / `Ctrl+s` (Windows, Linux) | Save Studio changes | -| Key | Action | -| --- | ----------------------------- | -| `r` | Rerun tests | -| `s` | Stop tests | -| `f` | Bring focus to 'specs' window | +Note: The save shortcut works when the Studio panel is open and there are unsaved changes. ## Debugging -In addition to the features already mentioned, Cypress comes with a host of -debugging tools to help you understand a test. You can: +Use Cypress debugging tools in open mode to trace failures, inspect state, and fix flake faster. You can: -- See detailed information about [errors](#Errors) that occur. -- Receive additional [console output](#Console-output) about each command. -- [Pause commands](#Special-commands) and step through them iteratively. - {/* - Visualize when hidden or multiple elements are found. */} +- Review detailed [errors](#Errors) with stack traces and helpful context +- View structured [console output](#Console-output) for each command +- Use [special commands](#Special-commands) to pause and step through tests ### Errors @@ -663,37 +424,32 @@ debugging tools to help you understand a test. You can: ### Console output -Besides commands being interactive, they also output additional debugging -information to your console. +Each Command Log entry emits structured details to the browser console. Open DevTools and click a Command Log entry to see `consoleProps`, including inputs and outputs for that command. -Open up your Dev Tools and click on the `GET` for the `.action-email` class -selector. +For example, click the `GET` for the `.action-email` selector in the Command Log with Developer Tools open. -**We can see Cypress output additional information in the console:** +You will see Cypress print additional information: -- Command (that was issued) -- Yielded (what was returned by this command) -- Elements (the number of elements found) -- Selector (the argument we used) +- Command issued +- Yielded value +- Elements found +- Selector used -We can even expand what was returned and inspect each individual element or even -right click and inspect them in the Elements panel! +Expand the output to inspect individual elements. You can right click an element and jump to it in the Elements panel. ### Special commands -In addition to having a helpful UI, there are also special commands dedicated to -the task of debugging, for example: +Use these commands to control execution while you debug: - [cy.pause()](/api/commands/pause) - [cy.debug()](/api/commands/debug) -In the following example, we've added a [cy.pause()](/api/commands/pause) -command to this test: +In the example below, a [cy.pause()](/api/commands/pause) call pauses execution so you can step through the remaining commands. ```js describe('My First Test', () => { @@ -715,8 +471,7 @@ describe('My First Test', () => { }) ``` -Now, when the test runs, Cypress provides us a UI (similar to debugger) to step -forward through each command in the test. +When the test runs, Cypress shows step controls so you can advance one command at a time and inspect state between steps. diff --git a/docs/app/guides/migration/protractor-to-cypress.mdx b/docs/app/guides/migration/protractor-to-cypress.mdx index 8da2f8e2ba..c2aae3cfde 100644 --- a/docs/app/guides/migration/protractor-to-cypress.mdx +++ b/docs/app/guides/migration/protractor-to-cypress.mdx @@ -103,8 +103,7 @@ manually explore its behavior while it is under the state of a desired test scenario. Cypress also helps you to write your tests by making it as easy as possible to -find the right CSS selectors for the DOM elements in your application with its -[Selector Playground](/app/core-concepts/open-mode#Selector-Playground) and [Cypress Studio](/app/guides/cypress-studio). +find the right CSS selectors for the DOM elements in your application with [Cypress Studio](/app/guides/cypress-studio). These tools help you cut down on time spent finding the right selectors so you can focus on what's important: writing tests that verify your app's logic. @@ -434,26 +433,6 @@ You can learn more about ::: -#### Selector Playground - -For those who are big fans of -[Protractor's Element Explorer functionality](https://www.protractortest.org/#/debugging#enabled-control-flow), -Cypress also provides you with a -[Selector Playground](/app/core-concepts/open-mode#Selector-Playground) -that allows you to: - -- Determine a unique selector for an element -- See what elements match a given selector -- See what element matches a string of text - -The Selector Playground can be useful when you need to find a specific selector -to use in your Cypress tests. - - - ### How to Interact with DOM Elements Before: Protractor diff --git a/docs/app/guides/migration/selenium-to-cypress.mdx b/docs/app/guides/migration/selenium-to-cypress.mdx index 5ca15dad2f..f97ab2aa0b 100644 --- a/docs/app/guides/migration/selenium-to-cypress.mdx +++ b/docs/app/guides/migration/selenium-to-cypress.mdx @@ -78,8 +78,7 @@ assistance, making it a highly supported testing framework. ### 5. Ease of Use -Compared to Selenium, Cypress offers a more intuitive and user-friendly experience. Features like the [selector -playground](/app/core-concepts/open-mode#Selector-Playground) and +Compared to Selenium, Cypress offers a more intuitive and user-friendly experience. Features like [Cypress Studio](/app/guides/cypress-studio) simplify test writing and debugging, allowing users to focus on creating effective tests without the need for constant navigation between the test server and browser. This streamlined approach enhances productivity and accelerates the testing process. diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx index 832d4e7568..740ed2ba80 100644 --- a/docs/app/references/changelog.mdx +++ b/docs/app/references/changelog.mdx @@ -11115,7 +11115,7 @@ _Released 3/1/2018_ **Features:** - The - [Selector Playground](/app/core-concepts/open-mode#Selector-Playground) + Selector Playground 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 @@ -11125,7 +11125,7 @@ _Released 3/1/2018_ **Documentation Changes:** -- [Added `Selector Playground Guide`](/app/core-concepts/open-mode#Selector-Playground) +- Added `Selector Playground Guide` - Added `Selector Playground API` - [Updated `Best Practices`](/app/core-concepts/best-practices) - [Updated `FAQ`](/app/faq) diff --git a/static/img/app/core-concepts/open-mode/keyboard-shortcuts.png b/static/img/app/core-concepts/open-mode/keyboard-shortcuts.png index df64ca6f74..574a4d3342 100644 Binary files a/static/img/app/core-concepts/open-mode/keyboard-shortcuts.png and b/static/img/app/core-concepts/open-mode/keyboard-shortcuts.png differ diff --git a/static/img/app/core-concepts/open-mode/viewport-scaling-ct.png b/static/img/app/core-concepts/open-mode/viewport-scaling-ct.png index 3fa80da8c2..0b7d64fe1f 100644 Binary files a/static/img/app/core-concepts/open-mode/viewport-scaling-ct.png and b/static/img/app/core-concepts/open-mode/viewport-scaling-ct.png differ diff --git a/static/img/snippets/first-test-debugging.mp4 b/static/img/snippets/first-test-debugging.mp4 new file mode 100644 index 0000000000..266ea1ea03 Binary files /dev/null and b/static/img/snippets/first-test-debugging.mp4 differ