Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion docs/app/core-concepts/interacting-with-elements.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<DocsImage src="/img/app/core-concepts/hitbox.png" alt="Hitbox" />
<DocsImage
src="/img/app/core-concepts/cypress-click-coordinates-hitbox.png"
alt="Cypress App highlighting the click command with the red hitbox highlighted over the element"
/>

## Debugging

Expand Down
23 changes: 10 additions & 13 deletions docs/app/core-concepts/introduction-to-cypress.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -728,22 +728,15 @@ 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.

<DocsImage
src="/img/app/core-concepts/reload-page.gif"
alt="Manually reloading the browser page until the number 7 appears"
/>

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
[Recipes](https://github.com/cypress-io/cypress-example-recipes#testing-the-dom).

<Icon name="exclamation-triangle" color="red" /> **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
Expand Down Expand Up @@ -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

<Icon name="play-circle" url="https://www.youtube.com/watch?v=5Z8BaPNDfvA" />

### Commands Run Serially

After a test function is finished running, Cypress goes to work executing the
Expand All @@ -843,19 +832,25 @@ 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.
4. Perform a click action on that element.
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** ✨)
Expand All @@ -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
Expand Down
22 changes: 5 additions & 17 deletions docs/app/core-concepts/open-mode.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,7 @@ experience in [Test Replay](/cloud/features/test-replay) for runs recorded in CI
<DocsImage
src="/img/app/core-concepts/open-mode/test-runner.png"
alt="The Test Runner"
noBorder={true}
/>

## Command Log
Expand Down Expand Up @@ -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.

<DocsImage
src="/img/app/core-concepts/open-mode/first-test-url-revert.png"
alt="The url address bar shows https://example.cypress.io/"
/>

### Pinning snapshots

Each command, when clicked on, displays extra information in the dev tools
Expand Down Expand Up @@ -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
Expand All @@ -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%`.

<DocsImage
src="/img/app/core-concepts/open-mode/viewport-scaling.png"
alt="Viewport Scaling"
/>

:::info
#### Errors

The right-hand side may also be used to display syntax errors in your spec file
that prevent the tests from running.

:::

<DocsImage
src="/img/app/core-concepts/open-mode/aut-error-e2e.png"
alt="Errors"
/>

:::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 <ComponentOnlyBadge />

In
Expand Down
2 changes: 0 additions & 2 deletions docs/app/core-concepts/retry-ability.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -426,8 +426,6 @@ Below is an example where the number value is set after a delay:
</script>
```

<DocsImage src="/img/app/retry-ability/random-number.gif" alt="Random number" />

### <Icon name="exclamation-triangle" color="red" /> Incorrectly waiting for values

You may want to write a test like below, to test that the number is between 1
Expand Down
43 changes: 6 additions & 37 deletions docs/app/core-concepts/writing-and-organizing-tests.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:

<DocsImage
src="/img/app/core-concepts/todo-mvc-passing-test.png"
src="/img/app/core-concepts/cypress-passing-test.png"
alt="Cypress with a single passed test"
/>

Expand All @@ -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!

<DocsImage
src="/img/app/core-concepts/todo-mvc-failing-test.png"
src="/img/app/core-concepts/cypress-failing-test.png"
alt="Cypress with a single failed test"
/>

Expand Down Expand Up @@ -861,7 +861,7 @@ All four tests above are marked _pending_ when Cypress finishes running the spec
file.

<DocsImage
src="/img/app/core-concepts/todo-mvc-pending-tests.png"
src="/img/app/core-concepts/cypress-pending-tests.png"
alt="Cypress with four pending test"
/>

Expand All @@ -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
/// <reference types="cypress" />

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.

<DocsImage
src="/img/app/core-concepts/todo-mvc-2-tests-passing.png"
alt="Cypress showing two passing tests"
/>

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(() => {
Expand All @@ -921,15 +890,15 @@ the same way! So Cypress _skips_ the remaining tests in that block, because they
would also fail due to the `beforeEach` hook failure.

<DocsImage
src="/img/app/core-concepts/todo-mvc-failed-and-skipped-tests.png"
src="/img/app/core-concepts/cypress-failed-and-skipped-tests.png"
alt="Cypress showing one failed and one skipped test"
/>

If we collapse the test commands, we can see the empty box marking the skipped
test "adds 2 todos".

<DocsImage
src="/img/app/core-concepts/todo-mvc-skipped-test.png"
src="/img/app/core-concepts/cypress-skipped-test.png"
alt="Cypress showing one skipped test"
/>

Expand Down
1 change: 0 additions & 1 deletion docs/app/end-to-end-testing/testing-your-app.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,6 @@ Once that file is created, you should see it in the list of spec files.
<DocsImage
src="/img/app/get-started/e2e/testing-your-app-home-page-spec.png"
alt="List of files including home_page.cy.js"
width="75%"
/>

Now you'll need to add in the following code in your test file to visit your
Expand Down
49 changes: 13 additions & 36 deletions docs/app/end-to-end-testing/writing-your-first-end-to-end-test.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -159,15 +166,6 @@ already have some familiarity and knowledge of. If not, that's okay too.

:::

:::tip

<strong>Using ESlint?</strong>

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:**
Expand Down Expand Up @@ -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')
})
})
Expand Down Expand Up @@ -278,15 +275,11 @@ describe('My First Test', () => {
alt="Test failing to not find content 'hype'"
/>

:::caution
:::info

<strong>Error Messages</strong>

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).

:::

Expand Down Expand Up @@ -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`_
Expand All @@ -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`_
Expand Down Expand Up @@ -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.

<DocsImage
src="/img/app/get-started/e2e/search-box.png"
alt="Use the search box to find relevant documentation"
/>
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed static/img/app/core-concepts/hitbox.png
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified static/img/app/core-concepts/open-mode/aut-error-e2e.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified static/img/app/core-concepts/open-mode/command-log.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified static/img/app/core-concepts/open-mode/viewport-scaling.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed static/img/app/core-concepts/reload-page.gif
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified static/img/app/get-started/e2e/first-test-failing-contains.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified static/img/app/get-started/e2e/first-test-failing.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified static/img/app/get-started/e2e/first-test.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed static/img/app/get-started/e2e/search-box.png
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.