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 7dc61bd75a..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 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/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/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