BREAKING: 13.0 Docs

.circleci/config.yml

@@ -6,11 +6,11 @@ orbs:
 executors:
   node-executor:
     docker:
-      - image: cimg/node:16.15.1
+      - image: cimg/node:18.15.0
   with-chrome-and-firefox:
     resource_class: medium+
     docker:
-      - image: 'cypress/browsers:node16.13.2-chrome97-ff96'
+      - image: 'cypress/browsers:node18.12.0-chrome106-ff106'
 
 commands:
   docs-build:

docs/api/plugins/after-spec-api.mdx

@@ -79,7 +79,6 @@ on('after:spec', (spec, results) => {
   //     {
   //       title: ['login', 'logs user in'],
   //       state: 'passed',
-  //       body: 'function () {}',
   //       // ...more properties...
   //     }
   //   ],

docs/api/commands/readfile.mdx → 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 [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management) {#Yields}
 
 - `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 `v13`, `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 [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Chains-of-Commands) {#Requirements}
@@ -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)

docs/faq/questions/cloud-faq.mdx

@@ -27,21 +27,34 @@ You can read more [here](/guides/cloud/introduction).
 
 ### <Icon name="angle-right" /> What does Cypress record?
 
-We capture the following:
+Cypress captures the following:
 
-- Standard Output
-- Test Failures
+When you run Cypress via `cypress run` passing the `--record` flag the following
+data is sent to the Cloud for every run:
+
+- Standard output in the terminal
+- Test results
+- Test definitions
+- Cypress configuration (minus Cypress environment variables)
 - Screenshots
-- Video
+- Videos
+- OS environment variables related to CI and git information
+
+You have the option to
+[delete videos or screenshots](/guides/guides/screenshots-and-videos#Control-which-videos-to-keep-and-upload-to-Cypress-Cloud)
+before being sent to the Cloud so those are not captured.
 
-We have already begun the implementation for capturing even more things from
-your run such as:
+When [Test Replay](#Test-Replay) capturing is enabled, the additional data outlined
+below will be sent to the Cloud. You can
+[disable capturing](/guides/cloud/debugging/test-replay#Opt-out-of-Test-Replay) this data.
 
-- Commands
-- Network Traffic
-- Browser Console Logs
+- The rendered DOM and CSS styles for the application under test
+- Cypress commands and events represented in the Command Log
+- Network traffic within your application under test
+- Browser console logs
 
-These will be added in subsequent releases.
+Cypress Cloud does not capture anything related to the code of your application
+under test or the code within any associated repositories that are associated with your project.
 
 ### <Icon name="angle-right" /> How is this different than CI?
 
@@ -74,7 +87,7 @@ the number of tests you record each month in your organization.
 
 Tests are recorded when [cypress run](/guides/guides/command-line#cypress-run)
 is called with the `--record` flag while supplying the record `--key`. This
-means your [test run data](/guides/cloud/recorded-runs#Latest-Runs) is being
+means your [test run data](/guides/cloud/debugging/recorded-runs#Latest-Runs) is being
 "recorded" to Cypress Cloud.
 
 We consider each time the `it()` function is called to be a single test. So you
@@ -151,7 +164,7 @@ any test results.
 ### <Icon name="angle-right" /> What is the projectId for?
 
 The `projectId` is a 6 character string that helps identify your project once
-you've [set up your tests to record](/guides/cloud/recorded-runs#Latest-Runs).
+you've [set up your tests to record](/guides/cloud/debugging/recorded-runs#Latest-Runs).
 It's generated by Cypress and typically is found in your
 [Cypress configuration](/guides/references/configuration).
 
@@ -172,7 +185,7 @@ section of the [Cypress Cloud](/guides/cloud/introduction) docs.
 ### <Icon name="angle-right" /> What is a Record Key?
 
 A _Record Key_ is a GUID that's generated automatically by Cypress once you've
-[set up your tests to record](/guides/cloud/recorded-runs#Latest-Runs). It helps
+[set up your tests to record](/guides/cloud/debugging/recorded-runs#Latest-Runs). It helps
 identify your project and authenticate that your project is even _allowed_ to
 record tests.
 
@@ -191,14 +204,14 @@ section of the [Cypress Cloud](/guides/cloud/introduction) docs.
 ### <Icon name="angle-right" /> How do I record my tests?
 
 1. First [set up the project to record](/guides/cloud/getting-started#Setup).
-2. Then [record your runs](/guides/cloud/recorded-runs#Latest-Runs).
+2. Then [record your runs](/guides/cloud/debugging/recorded-runs#Latest-Runs).
 
 After recording your tests, you will see them in
 [Cypress Cloud](https://on.cypress.io/cloud) and in the Cypress App [Runs](/guides/core-concepts/cypress-app#Runs) tab.
 
 ### <Icon name="angle-right" /> Can I delete a run from Cypress Cloud?
 
-You can [archive a run](/guides/cloud/recorded-runs#Archive-run) so that it does
+You can [archive a run](/guides/cloud/debugging/recorded-runs#Archive-run) so that it does
 not display in the runs list or in analytics.
 
 **Note:** Archiving the recorded runs has no effect on the amount of tests
@@ -267,6 +280,7 @@ Cloud.
 - `https://assets.cypress.io` - **Asset CDN** (Org logos, icons, videos,
   screenshots, etc.)
 - `https://authenticate.cypress.io` - **Authentication API**
+- `https://capture.cypress.io` - **Cypress Test Replay**
 - `https://cloud.cypress.io` - **Cypress Cloud**
 - `https://docs.cypress.io` - **Cypress documentation**
 - `https://download.cypress.io` - **CDN download of Cypress binary**
@@ -311,3 +325,78 @@ You can delete your Cypress account from
 [your Cypress Cloud profile](https://cloud.cypress.io/profile). Deleting your
 account cannot be undone! By deleting your Cypress account, all associated data
 in your account will be permanently deleted.
+
+## Test Replay
+
+### <Icon name="angle-right" /> What is Test Replay?
+
+[Test Replay](/guides/cloud/debugging/test-replay) enables you and your team to troubleshoot and debug failed tests faster. After updating to Cypress `v13`, the new feature will automatically record all browser events and allow you to “replay” what your application under test looked like.
+
+Wind back the clock to any point in an application's test execution and directly interact with tests as they happened in CI. Debug complex problems as if you were there when they first happened. You can:
+
+- **Inspect the DOM** at the exact time of a test failure to debug tests quickly
+- **View important debugging dimensions** such as network requests, console logs, and more
+- **Save time recreating errors in CI locally** - replay tests as they happened in CI
+
+<DocsImage
+  src="/img/guides/cloud/test-replay/test-replay-ui.png"
+  alt="Test Replay Demo"
+  width="80%"
+/>
+
+### <Icon name="angle-right" /> What types of testing can I debug with Test Replay?
+
+Anything you can do with Cypress - E2E, Component, API, etc.
+
+### <Icon name="angle-right" /> How is Cypress Test Replay different from other "replay" services?
+
+There is an important distinction between _session_ replay services (LogRocket, FullStory, DataDog, etc) and Cypress Test Replay. In session replay, user actions are captured as the application is used and delivered back in a replay-able format, usually video or stitched DOM snapshots. These are valuable tools for gathering product insight such as user behavior, per session.
+
+Cypress Test Replay captures every detail of your test runs as they happen in CI. Remember, these tests are running in a headless manner on a virtual machine with no UI being rendered. Sometimes tests will error or fail indicating an issue in your application. Since Cypress Cloud is monitoring the health of your CI test suite, each Test Replay offers a chance to step back in time to analyze and leverage [time travel debugging](/guides/core-concepts/cypress-app#Time-traveling), network requests, console logs, JavaScript errors, and element rendering to address problems directly. This is incredibly valuable for developer and team productivity. No more hours wasted recreating CI issues on your local machine!
+
+### <Icon name="angle-right" /> Does the replay reflect the real time it took for the test to run?
+
+Yes! The test is captured in Cypress Cloud as it executed in your CI run. That means the replay will show things like [slow typing](/api/cypress-api/keyboard-api#Slow-down-typing-by-increasing-the-keystroke-delay) or any [`cy.wait()`](/api/commands/wait) included in your test.
+
+### <Icon name="angle-right" /> Are there performance implications when using Test Replay?
+
+Expect an even performance exchange with Test Replay vs. video. There is more activity to capture and replay tests but without the overhead of recording, compressing, and storing video assets. `video` capture is set to `false` by default starting in Cypress `v13`. See the full [v13 changelog](/guides/references/changelog#13-0-0).
+
+### <Icon name="angle-right" /> Is every aspect of my stack included in Test Replay?
+
+Our aim is to create an impactful debugging experience that covers the most ground for users. We will continue to expand and can see a need to support (to name a few):
+
+- Web sockets
+- Canvas elements
+- Shadow DOM
+- Server side events
+
+### <Icon name="angle-right" /> Can I use Test Replay for tests recorded in different browsers?
+
+Test Replay leverages [Chrome DevTools Protocol(CDP)](https://chromedevtools.github.io/devtools-protocol/), so currently supports Chromium-based browsers (Chrome, Edge, and Electron) only.
+
+Test Replay would be disabled, with a message that it's only available on Chromium, for tests run in Firefox or Webkit (Safari). You can still record and capture test [artifacts](/guides/cloud/debugging/recorded-runs#Artifacts) (screenshots, videos and CI logs) via other browsers in separate [run groups](/guides/cloud/smart-orchestration/parallelization#Grouping-test-runs).
+
+### <Icon name="angle-right" /> Can I replay tests from historical Cypress Cloud runs?
+
+Test Replay is available for tests recorded using Cypress `v13` and up. Tests recorded prior to this will not have Test Replay enabled in Cypress Cloud. You will still have any artifacts collected during the pre `v13` test runs.
+
+### <Icon name="angle-right" /> Can I enable or disable Test Replay for specific, individual tests, or is it a global setting? Can I configure my settings so that Test Replay is only enabled for failing test retries?
+
+At this time, users can only opt-out of Test Replay via [project-level settings](/guides/cloud/debugging/test-replay#Opt-out-of-Test-Replay) in Cypress Cloud. There is no local option for opting out at this time.
+
+### <Icon name="angle-right" /> Can I share my test replays?
+
+Yes! You can share Test Replays to any team members who have access to view your Cypress Cloud runs like QA, marketing, design, etc. Open the replay, copy the url from the browser address bar and pass it along.
+
+### <Icon name="angle-right" /> Will Test Replay write any assets to the file system?
+
+Yes, but it is stored in a temporary directory and deleted after the run. There is nothing to `.gitignore`.
+
+### <Icon name="angle-right" /> Is the network tab feature available exclusively in Test Replay?
+
+All of the data within Test Replay's Developer Tools in Cypress Cloud (including network events) are already available to you when running tests locally in the Cypress app via your browser's built-in developer tools (e.g. Chrome DevTools). When reviewing a test run that occurred in CI, you can review the network events within Test Replay in Cypress Cloud.
+
+### <Icon name="angle-right" /> Can I `console.log()` data in the console view of the Developer Tools panel?
+
+Yes. This displays console logs from within the application under test or your spec files. You may need to use `JSON.stringify(Object)` to display deeply nested data.