From 610348c72e2e19d144e12e3f44b04b68ed1e15dd Mon Sep 17 00:00:00 2001 From: Bill Glesias Date: Thu, 15 Jun 2023 15:16:51 -0400 Subject: [PATCH 01/26] BREAKING: update documentation by setting default video: false for v13.0.0 (#5300) * BREAKING: update documentation by setting default video: false * Update docs/guides/overview/why-cypress.mdx Co-authored-by: Emily Rohrbough * Update docs/guides/end-to-end-testing/migration/protractor-to-cypress.mdx Co-authored-by: Emily Rohrbough * Update docs/guides/continuous-integration/introduction.mdx Co-authored-by: Emily Rohrbough * Update docs/guides/guides/screenshots-and-videos.mdx Co-authored-by: Emily Rohrbough * chore: re-order video bits * Update docs/guides/end-to-end-testing/migration/protractor-to-cypress.mdx * chore: linting --------- Co-authored-by: Emily Rohrbough --- docs/api/commands/screenshot.mdx | 4 +-- .../continuous-integration/introduction.mdx | 4 ++- .../migration/protractor-to-cypress.mdx | 4 +-- docs/guides/guides/screenshots-and-videos.mdx | 25 ++++++++++++------- docs/guides/overview/why-cypress.mdx | 6 ++--- docs/guides/references/configuration.mdx | 2 +- 6 files changed, 27 insertions(+), 18 deletions(-) diff --git a/docs/api/commands/screenshot.mdx b/docs/api/commands/screenshot.mdx index f66af2e9fa..ea5f071bc5 100644 --- a/docs/api/commands/screenshot.mdx +++ b/docs/api/commands/screenshot.mdx @@ -278,8 +278,8 @@ Another potential problem to be aware of is that our own Command Log is using React under the hood and only rendering asynchronously during an animation frame. It is possible you will see screenshots taken before our Command Log is done rendering. This means you may not see the **error displayed** in the -screenshot. But this is also why we take a video - to show you the complete -failure. +screenshot. But this is also why we allow taking a video - to show you the +complete failure. We make our best effort to synchronize taking a screenshot with our renderer, but the current state of your application under test could have changed in the diff --git a/docs/guides/continuous-integration/introduction.mdx b/docs/guides/continuous-integration/introduction.mdx index 29f301e495..56f6246d8e 100644 --- a/docs/guides/continuous-integration/introduction.mdx +++ b/docs/guides/continuous-integration/introduction.mdx @@ -170,7 +170,8 @@ insight into what happened when your tests ran. - Get the entire stack trace of failed tests. - View screenshots taken when tests fail and when using [`cy.screenshot()`](/api/commands/screenshot). -- Watch a video of your entire test run or a clip at the point of test failure. +- Watch a video of your entire test run or a clip at the point of test failure + when the `video` configuration is enabled. - See which machines ran each test when [parallelized](/guides/guides/parallelization). @@ -376,6 +377,7 @@ values in the Cypress configuration. **_Typical use cases would be modifying things like:_** - `CYPRESS_BASE_URL` +- `CYPRESS_VIDEO` - `CYPRESS_VIDEO_COMPRESSION` - `CYPRESS_REPORTER` - `CYPRESS_INSTALL_BINARY` diff --git a/docs/guides/end-to-end-testing/migration/protractor-to-cypress.mdx b/docs/guides/end-to-end-testing/migration/protractor-to-cypress.mdx index eb8fa534a0..b94bffeba7 100644 --- a/docs/guides/end-to-end-testing/migration/protractor-to-cypress.mdx +++ b/docs/guides/end-to-end-testing/migration/protractor-to-cypress.mdx @@ -157,8 +157,8 @@ the failure. Cypress assists with debugging in headless mode, by automatically taking a screenshot of the app UI and command log at the exact point of test failure. To -help see everything that happened prior to test failure, Cypress provides a -video recording (as an MP4 file) of a full test spec run by default. +see everything that happened prior to test failure, enable the `video` +configuration option to record (as an MP4 file) the full test spec run. ### Test Retries diff --git a/docs/guides/guides/screenshots-and-videos.mdx b/docs/guides/guides/screenshots-and-videos.mdx index 23d54b11e2..2ac09ee7b2 100644 --- a/docs/guides/guides/screenshots-and-videos.mdx +++ b/docs/guides/guides/screenshots-and-videos.mdx @@ -43,21 +43,28 @@ to clear your screenshots folder before a run, you can set ## Videos -Cypress records a video for each spec file when running tests during -`cypress run`. Videos are _not_ automatically recorded during `cypress open`. - -Video recording can be turned off entirely by setting -[`video`](/guides/references/configuration#Videos) to `false` from within your +Video recording is disabled by default, but can be turned on by setting +[`video`](/guides/references/configuration#Videos) to `true` from within your configuration. +If enabled, Cypress records a video for each spec file when running tests during +`cypress run`. Videos are _not_ recorded during `cypress open`. + +:::cypress-config-example + +```ts +{ + video: true +} +``` + Videos are stored in the [`videosFolder`](/guides/references/configuration#Videos) which is set to `cypress/videos` by default. -After `cypress run` completes, Cypress automatically compresses the video in -order to save on file size. By default it compresses to a `32 CRF`, but this is -configurable with the -[`videoCompression`](/guides/references/configuration#Videos) property. +After `cypress run` completes, Cypress compresses the video in order to save on +file size. By default it compresses to a `32 CRF`, but this is configurable with +the [`videoCompression`](/guides/references/configuration#Videos) property. When using the `--record` flag while running your tests, videos are processed, compressed, and uploaded to [Cypress Cloud](/guides/cloud/introduction) after diff --git a/docs/guides/overview/why-cypress.mdx b/docs/guides/overview/why-cypress.mdx index 80b2ae9115..9568188d92 100644 --- a/docs/guides/overview/why-cypress.mdx +++ b/docs/guides/overview/why-cypress.mdx @@ -117,9 +117,9 @@ do that no other testing framework can: - **Consistent Results:** Our architecture doesn't use Selenium or WebDriver. Say hello to fast, consistent and reliable tests that are flake-free. - **Screenshots and Videos:** View screenshots taken automatically on failure, - or videos of your entire test suite when run from the CLI. Record to - [Cypress Cloud](/guides/cloud/introduction) to store them with your test - results for zero-configuration debugging. + or videos, if enabled, of your entire test suite when run from the CLI. Record + to [Cypress Cloud](/guides/cloud/introduction) to store them with your test + results. - **Cross Browser Testing:** Run tests within Firefox and Chrome-family browsers (including Edge and Electron) locally and [optimally in a Continuous Integration pipeline](/guides/guides/cross-browser-testing). diff --git a/docs/guides/references/configuration.mdx b/docs/guides/references/configuration.mdx index c2ce5aa4a3..38c4e47d34 100644 --- a/docs/guides/references/configuration.mdx +++ b/docs/guides/references/configuration.mdx @@ -126,7 +126,7 @@ For more options regarding screenshots, view the | `trashAssetsBeforeRuns` | `true` | Whether Cypress will trash assets within the `downloadsFolder`, `screenshotsFolder`, and `videosFolder` before tests run with `cypress run`. | | `videoCompression` | `32` | The quality setting for the video compression, in Constant Rate Factor (CRF). The value can be `false` to disable compression or a value between `0` and `51`, where a lower value results in better quality (at the expense of a higher file size). | | `videosFolder` | `cypress/videos` | Where Cypress will automatically save the video of the test run when tests run with `cypress run`. | -| `video` | `true` | Whether Cypress will capture a video of the tests run with `cypress run`. | +| `video` | `false` | Whether Cypress will capture a video of the tests run with `cypress run`. | | `videoUploadOnPasses` | `true` | Whether Cypress will process, compress, and upload videos to [Cypress Cloud](/guides/cloud/introduction) even when all tests in a spec file are passing. This only applies when recording your runs to Cypress Cloud. Turn this off if you'd like to only upload the spec file's video when there are failing tests. | ### Downloads From 48c2a95790e35b81921fda0e835f9f3f14af59f7 Mon Sep 17 00:00:00 2001 From: Bill Glesias Date: Tue, 20 Jun 2023 15:10:43 -0400 Subject: [PATCH 02/26] breaking: update documentation by setting videoCompression: false (#5301) * BREAKING: update documentation by setting default video: false * BREAKING: update documentation by setting videoCompression: false * Update docs/guides/guides/screenshots-and-videos.mdx Co-authored-by: Chris Breiding * apply suggestion from code review * chore: attempt to rework the video encoding section * Update docs/guides/guides/screenshots-and-videos.mdx Co-authored-by: Emily Rohrbough * chore: address comments in code review * chore: update video encoding guide to flow a bit more evenly --------- Co-authored-by: Chris Breiding Co-authored-by: Emily Rohrbough --- docs/guides/guides/screenshots-and-videos.mdx | 52 +++++++++++-------- docs/guides/references/configuration.mdx | 2 +- 2 files changed, 31 insertions(+), 23 deletions(-) diff --git a/docs/guides/guides/screenshots-and-videos.mdx b/docs/guides/guides/screenshots-and-videos.mdx index 2ac09ee7b2..8ead51a3c7 100644 --- a/docs/guides/guides/screenshots-and-videos.mdx +++ b/docs/guides/guides/screenshots-and-videos.mdx @@ -58,14 +58,12 @@ If enabled, Cypress records a video for each spec file when running tests during } ``` +:::cypress-config-example + Videos are stored in the [`videosFolder`](/guides/references/configuration#Videos) which is set to `cypress/videos` by default. -After `cypress run` completes, Cypress compresses the video in order to save on -file size. By default it compresses to a `32 CRF`, but this is configurable with -the [`videoCompression`](/guides/references/configuration#Videos) property. - When using the `--record` flag while running your tests, videos are processed, compressed, and uploaded to [Cypress Cloud](/guides/cloud/introduction) after every spec file runs, successful or not. To change this behavior to only process @@ -79,46 +77,56 @@ clear your videos folder before a run, you can set ### Video encoding -If your spec files have a long run duration, you might notice a time gap between -a finished spec and a new spec starting during `cypress run`. During this time, -Cypress is encoding the captured video and possibly uploading it to Cypress -Cloud. +After a video is recorded, Cypress encodes the video to a commonly digestable +format. Part of this encoding process includes video compression. -If the machine is encoding the video slowly (which is often the case for virtual -machines that use less CPU cores), the encoding might take a long time. In this -case, you can modify the -[`videoCompression`](/guides/references/configuration#Videos) configuration to -make the encoding a little bit faster. Here are some common scenarios: +Compression is disabled by default, meaning this step will be skipped +completely, so the file size of the video will be larger, but the encoding +process is faster. Setting +[`videoCompression`](/guides/references/configuration#Videos) to `true` will +coerce the video compression value to 32 Constant Rate Factor (CRF), which takes +longer to process, but results in a smaller video. -**Change compression value** +**Enabling compression** :::cypress-config-example ```ts { - videoCompression: 15 + videoCompression: true } ``` :::cypress-config-example -A lower `videoCompression` value will spend less time compressing and result in -a bigger video file size. +If your spec files have a long run duration and +[`videoCompression`](/guides/references/configuration#Videos) is enabled, you +might notice a time gap between a finished spec and a new spec starting during +`cypress run`. During this time, Cypress is encoding the captured video and +possibly uploading it to Cypress Cloud. -**Disable compression** +**Change compression value from 32** :::cypress-config-example ```ts { - videoCompression: false + videoCompression: 15 } ``` -::: +:::cypress-config-example + +In addition to enabling or disabling video compress, you can specify the CRF +value used to compress the video. Here is some common scenario: -The compression step will be skipped completely, so the video will be large, but -the processing should be faster. +- If the machine is encoding the video slowly (which is often the case for + virtual machines that use less CPU cores), try increasing the CRF value. + +- If your videos are extremely low quality, try decreasing the CRF value. + +A lower `videoCompression` value will spend less time compressing and result in +a bigger video file size and higher quality video. :::info diff --git a/docs/guides/references/configuration.mdx b/docs/guides/references/configuration.mdx index 545f500d42..1e4d769fcf 100644 --- a/docs/guides/references/configuration.mdx +++ b/docs/guides/references/configuration.mdx @@ -124,7 +124,7 @@ For more options regarding screenshots, view the | Option | Default | Description | | ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `trashAssetsBeforeRuns` | `true` | Whether Cypress will trash assets within the `downloadsFolder`, `screenshotsFolder`, and `videosFolder` before tests run with `cypress run`. | -| `videoCompression` | `32` | The quality setting for the video compression, in Constant Rate Factor (CRF). The value can be `false` to disable compression or a value between `0` and `51`, where a lower value results in better quality (at the expense of a higher file size). | +| `videoCompression` | `false` | The quality setting for the video compression, in Constant Rate Factor (CRF). The value can be `false` to disable compression or a value between `0` and `51`, where a lower value results in better quality (at the expense of a higher file size). | | `videosFolder` | `cypress/videos` | Where Cypress will automatically save the video of the test run when tests run with `cypress run`. | | `video` | `false` | Whether Cypress will capture a video of the tests run with `cypress run`. | | `videoUploadOnPasses` | `true` | Whether Cypress will process, compress, and upload videos to [Cypress Cloud](/guides/cloud/introduction) even when all tests in a spec file are passing. This only applies when recording your runs to Cypress Cloud. Turn this off if you'd like to only upload the spec file's video when there are failing tests. | From 8f1fc89f43353bd15ee25260c6ada03929a215cf Mon Sep 17 00:00:00 2001 From: Bill Glesias Date: Tue, 20 Jun 2023 15:39:49 -0400 Subject: [PATCH 03/26] BREAKING: remove the videoUploadOnPasses configuration option (#5306) * BREAKING: remove the videoUploadOnPasses configuration option * chore: add history entry of removed videoUploadOnPasses config option --- docs/guides/guides/module-api.mdx | 1 - docs/guides/guides/screenshots-and-videos.mdx | 12 ++++++------ docs/guides/references/configuration.mdx | 2 +- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/guides/guides/module-api.mdx b/docs/guides/guides/module-api.mdx index 612e9b1a6f..1df60cc025 100644 --- a/docs/guides/guides/module-api.mdx +++ b/docs/guides/guides/module-api.mdx @@ -188,7 +188,6 @@ tests results. A typical run could return something like this: }], "reporter": "spec", "reporterStats": {...}, - "shouldUploadVideo": true, "spec": {...}, "stats": { "suites": 1, diff --git a/docs/guides/guides/screenshots-and-videos.mdx b/docs/guides/guides/screenshots-and-videos.mdx index 8ead51a3c7..3cf2f8729e 100644 --- a/docs/guides/guides/screenshots-and-videos.mdx +++ b/docs/guides/guides/screenshots-and-videos.mdx @@ -67,9 +67,9 @@ Videos are stored in the When using the `--record` flag while running your tests, videos are processed, compressed, and uploaded to [Cypress Cloud](/guides/cloud/introduction) after every spec file runs, successful or not. To change this behavior to only process -videos in the case that tests fail, set the -[`videoUploadOnPasses`](/guides/references/configuration#Videos) configuration -option to `false`. +videos in the case that tests fail, see how to +[delete videos for specs without failing or retried tests](/guides/guides/screenshots-and-videos#Delete-videos-for-specs-without-failing-or-retried-tests). +Deleting the video will cause the video to not be uploaded to Cypress Cloud. Cypress clears any existing videos before a `cypress run`. If you do not want to clear your videos folder before a run, you can set @@ -143,9 +143,9 @@ to Cypress Cloud. Deleting videos after the run can save resource space on the machine as well as skip the time used to process, compress, and upload the video to [Cypress Cloud](/guides/cloud/introduction). -To only process videos in the case that a test fails, you can set the -[`videoUploadOnPasses`](/guides/references/configuration#Videos) configuration -option to `false`. +To only process videos in the case that a test fails, you can +[delete videos for specs without failing or retried tests](/guides/guides/screenshots-and-videos#Delete-videos-for-specs-without-failing-or-retried-tests), +which will not upload the video of passed runs to Cypress Cloud. For more fine grained control, you can use Cypress's [`after:spec`](/api/plugins/after-spec-api) event listener that fires after each diff --git a/docs/guides/references/configuration.mdx b/docs/guides/references/configuration.mdx index 1e4d769fcf..7f94dc0136 100644 --- a/docs/guides/references/configuration.mdx +++ b/docs/guides/references/configuration.mdx @@ -127,7 +127,6 @@ For more options regarding screenshots, view the | `videoCompression` | `false` | The quality setting for the video compression, in Constant Rate Factor (CRF). The value can be `false` to disable compression or a value between `0` and `51`, where a lower value results in better quality (at the expense of a higher file size). | | `videosFolder` | `cypress/videos` | Where Cypress will automatically save the video of the test run when tests run with `cypress run`. | | `video` | `false` | Whether Cypress will capture a video of the tests run with `cypress run`. | -| `videoUploadOnPasses` | `true` | Whether Cypress will process, compress, and upload videos to [Cypress Cloud](/guides/cloud/introduction) even when all tests in a spec file are passing. This only applies when recording your runs to Cypress Cloud. Turn this off if you'd like to only upload the spec file's video when there are failing tests. | ### Downloads @@ -741,6 +740,7 @@ DEBUG=cypress:cli,cypress:server:specs | Version | Changes | | --------------------------------------------- | ------------------------------------------------------------------------------------- | +| [13.0.0](/guides/references/changelog#13-0-0) | Removed `videoUploadOnPasses` option. | | [11.0.0](/guides/references/changelog#11-0-0) | Removed `e2e.experimentalSessionAndOrigin` option. | | [10.4.0](/guides/references/changelog#10-4-0) | Added `e2e.testIsolation` option. | | [10.0.0](/guides/references/changelog#10-0-0) | Reworked page to support new `cypress.config.js` and deprecated `cypress.json` files. | From 674419f3e84b9850df0f3fa3480c2579134f5d89 Mon Sep 17 00:00:00 2001 From: Matt Henkes Date: Tue, 20 Jun 2023 14:43:05 -0500 Subject: [PATCH 04/26] .readFile() is now a query (#5017) (#5316) * .readFile() is now a query * Add section on new .readFile() superpowers * Fix page slug for readFile * Prettier run Co-authored-by: Blue F --- docs/api/{commands => queries}/readfile.mdx | 16 +++++- docs/guides/references/migration-guide.mdx | 62 +++++++++++++++++++++ 2 files changed, 76 insertions(+), 2 deletions(-) rename docs/api/{commands => queries}/readfile.mdx (91%) diff --git a/docs/api/commands/readfile.mdx b/docs/api/queries/readfile.mdx similarity index 91% rename from docs/api/commands/readfile.mdx rename to docs/api/queries/readfile.mdx index 78fca46229..d574069d94 100644 --- a/docs/api/commands/readfile.mdx +++ b/docs/api/queries/readfile.mdx @@ -1,5 +1,6 @@ --- title: readFile +slug: /api/commands/readfile --- Read a file and yield its contents. @@ -62,8 +63,8 @@ Pass in an options object to change the default behavior of `cy.readFile()`. ### Yields [](/guides/core-concepts/introduction-to-cypress#Subject-Management) - `cy.readFile()` yields the contents of the file. -- The file will not be read from disk again if the results are stored in an - alias. +- The file will be read from disk again if any upcoming command (such as an + assertion) in the chain fails. ## Examples @@ -195,6 +196,15 @@ assertions. cy.readFile('some/nested/path/story.txt').should('eq', 'Once upon a time...') ``` +Starting in Cypress 13, `cy.readFile()` is a query, and will continue to read +the file until all chained commands of any type pass, not just assertions. + +```javascript +// will retry until the json file has a `users[123].name` field, and +// the assertion passes +cy.readFile('users.json').its('users.123.name').should('eq', 'John Doe') +``` + ## Rules ### Requirements [](/guides/core-concepts/introduction-to-cypress#Chains-of-Commands) @@ -247,6 +257,7 @@ outputs the following: | Version | Changes | | --------------------------------------------- | ----------------------------------------- | +| [13.0.0](/guides/references/changelog#13-0-0) | `cy.readFile()` became a query | | [9.0.0](/guides/references/changelog#9-0-0) | Changed `null` encoding to read as Buffer | | [0.17.2](/guides/references/changelog#0-17-2) | Improved error messaging | | [0.17.1](/guides/references/changelog#0-17-1) | `cy.readFile()` command added | @@ -255,5 +266,6 @@ outputs the following: - [`cy.exec()`](/api/commands/exec) - [`cy.fixture()`](/api/commands/fixture) for a similar command with caching + that does not retry - [`cy.task()`](/api/commands/task) - [`cy.writeFile()`](/api/commands/writefile) diff --git a/docs/guides/references/migration-guide.mdx b/docs/guides/references/migration-guide.mdx index bc1e524255..9513679ff8 100644 --- a/docs/guides/references/migration-guide.mdx +++ b/docs/guides/references/migration-guide.mdx @@ -2,6 +2,68 @@ title: Migration Guide --- +## Migrating to Cypress 13.0 + +This guide details the changes and how to change your code to migrate to Cypress +version 13.0. +[See the full changelog for version 12.0](/guides/references/changelog#12-0-0). + +### `cy.readFile()` is now a query command + +In Cypress 13, the [`.readFile()`](/api/commands/as) command is now a query. +Tests written using it should continue to operate exactly as before; no changes +are necessary. + +This means that `readFile()` will re-read the file from disk if any upcoming +command in the same chain fails. Assertions no longer have to be directly +attached. + +```js +cy.readFile(`users.json`).its('users.123.fullName').should('eq', 'John Doe') +``` + +Beginning with Cypress 13, the above test will re-read the file until the file +exists, it has the requested property, and it passes the assertion. + +In previous versions of Cypress, the above command would retry until the file +existed, but would _not_ re-read it from disk if the file didn't have the +requested property or the contents didn't match. + +#### `.readFile()` can no longer be overwritten with `Cypress.Commands.overwrite()` + +However, queries cannot be overwritten using `Cypress.Commands.overwrite()`. If +you were previously overwriting `cy.readFile()`, you will need to put your +custom version under a new name, and update your tests to use it. For example, +you might update this test: + +```js +Cypress.Commands.override('readFile', (originalFn, fileName, options) => { + originalFn(fileName, options).then((file) => { + // Do some processing + return updatedFile + }) +}) + +it('reads a file', () => { + cy.readFile('foo.json') +}) +``` + +to something like this: + +```js +Cypress.Commands.create('readFileWithExtras', (fileName, options) => { + cy.readFile(fileName, options).then((file) => { + // Do some processing + return updatedFile + }) +}) + +it('reads a file', () => { + cy.readFileWithExtras('foo.json') +}) +``` + ## Migrating to Cypress 12.0 This guide details the changes and how to change your code to migrate to Cypress From 7d782033fb0293c79d7a6735c45f9939e31a2b2f Mon Sep 17 00:00:00 2001 From: Blue F Date: Wed, 12 Jul 2023 08:10:00 -0700 Subject: [PATCH 05/26] Update guides for Cy 13, where assertions are now commands (#5081) * .readFile() is now a query (#5017) * .readFile() is now a query * Add section on new .readFile() superpowers * Fix page slug for readFile * Prettier run * Update guides to better support users in Cy 13, where assertions are now commands * Review updates * Apply suggestions from code review Co-authored-by: Emily Rohrbough * Partial review feedback (more to come) * Review updates * Prettier run * fix: update retry ability guide and migration guide now that should() and and() will not be queries in v13. see https://github.com/cypress-io/cypress/pull/25738 * chore: correct number of queries in example * revert: images changes due to should() and and() being queries, which is no longer applicable due to https://github.com/cypress-io/cypress/pull/25738 * chore: lint guides --------- Co-authored-by: Emily Rohrbough Co-authored-by: Bill Glesias --- .../interacting-with-elements.mdx | 2 +- .../core-concepts/introduction-to-cypress.mdx | 146 +++++++----------- docs/guides/core-concepts/retry-ability.mdx | 123 ++++++++------- .../writing-your-first-end-to-end-test.mdx | 4 +- docs/guides/references/best-practices.mdx | 4 +- docs/guides/references/migration-guide.mdx | 47 ++---- package-lock.json | 2 +- 7 files changed, 138 insertions(+), 190 deletions(-) diff --git a/docs/guides/core-concepts/interacting-with-elements.mdx b/docs/guides/core-concepts/interacting-with-elements.mdx index d827b1d860..26adf39962 100644 --- a/docs/guides/core-concepts/interacting-with-elements.mdx +++ b/docs/guides/core-concepts/interacting-with-elements.mdx @@ -40,7 +40,7 @@ Cypress will watch the DOM - re-running the queries that yielded the current subject - until an element passes all of these checks for the duration of the [`defaultCommandTimeout`](/guides/references/configuration#Timeouts) (described in depth in the -[Default Assertions](/guides/core-concepts/introduction-to-cypress#Default-Assertions) +[Implicit Assertions](/guides/core-concepts/introduction-to-cypress#Implicit-Assertions) core concept guide). **_Checks and Actions Performed_** diff --git a/docs/guides/core-concepts/introduction-to-cypress.mdx b/docs/guides/core-concepts/introduction-to-cypress.mdx index c8ee72a0f3..39b38cf4b9 100644 --- a/docs/guides/core-concepts/introduction-to-cypress.mdx +++ b/docs/guides/core-concepts/introduction-to-cypress.mdx @@ -302,7 +302,7 @@ just in case". ::: Later in this guide we'll go into much more detail about -[Default Assertions](#Default-Assertions) and [Timeouts](#Timeouts). +[Implicit Assertions](#Implicit-Assertions) and [Timeouts](#Timeouts). ## Chains of Commands @@ -912,11 +912,10 @@ randomly fail. This would lead to flaky, inconsistent results. :::info -While Cypress is built using Promises that come from -[Bluebird](http://bluebirdjs.com/), these are not what we expose as commands and -assertions on `cy`. If you'd like to learn more about handling asynchronous -Cypress Commands please read our -[Core Concept Guide](/guides/core-concepts/variables-and-aliases). +While Cypress does have a [`.then()`](/api/commands/then) command, Cypress +commands are not Promises and cannot be `await`ed. If you'd like to learn more +about handling asynchronous Cypress Commands please read our +[Variables and Aliases Guide](/guides/core-concepts/variables-and-aliases). ::: @@ -958,24 +957,22 @@ model after a real user working step by step. #### You cannot add a `.catch` error handler to a failed command In Cypress there is no built in error recovery from a failed command. A command -and its assertions all _eventually_ pass, or if one fails, all remaining -commands are not executed, and the test fails. +_eventually_ passes, or if it fails, all remaining commands are not executed, +and the test as a whole fails. You might be wondering: > How do I create conditional control flow, using if/else? So that if an element > does (or doesn't) exist, I choose what to do? -The problem with this question is that this type of conditional control flow -ends up being non-deterministic. This means different test runs may behave -differently, which makes them less deterministic and consistent. In general, -there are only a handful of very specific situations where you _can_ create -control flow using Cypress commands. +Cypress does not support this type of conditional control flow because it leads +to non-deterministic tests - different runs may behave differently, which makes +them less consistent and useful for verifying your application's correctness. In +general, there are only a handful of very specific situations where you can or +should create control flow using Cypress commands. With that said, as long as you are aware of the potential pitfalls with control -flow, it is possible to do this in Cypress! - -You can read all about how to do +flow, it is possible to do this in Cypress! You can read all about how to do [conditional testing](/guides/core-concepts/conditional-testing) here. ## Assertions @@ -989,25 +986,10 @@ Assertions describe the **desired** state of your **elements**, your ::: -What makes Cypress unique from other testing tools is that commands -**automatically retry** their assertions. In fact, they will look "downstream" -at what you're expressing and modify their behavior to make your assertions -pass. - -You should think of assertions as **guards**. - -Use your **guards** to describe what your application should look like, and -Cypress will automatically **block, wait, and retry** until it reaches that -state. - -:::tip - -Core Concept - -Each command documents its behavior with assertions - such as how it retries or -waits for assertions to pass. - -::: +What makes Cypress unique from other testing tools is that assertions +**automatically retry**. Think of them as **guards** - assertions describe what +your application should look like, and Cypress will automatically **block, wait, +and retry** until it reaches that state. ### Asserting in English @@ -1015,7 +997,7 @@ Let's look at how you'd describe an assertion in English: :::note -After clicking on this `