Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update quickstart.md #4783

Closed
wants to merge 16 commits into from
Prev Previous commit
Next Next commit
some IA restructure
elylucas committed Oct 4, 2022
commit ed3f7ed463a7d8c7288890d318a8fc882237af83
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.
36 changes: 18 additions & 18 deletions content/_data/sidebar.json
Original file line number Diff line number Diff line change
@@ -95,42 +95,42 @@
"slug": "devs-vs-users"
},
{
"title": "React Component Testing"
"title": "React"
},
{
"title": "Introduction",
"slug": "react"
},
{
"title": "React Quickstart",
"slug": "quickstart-react"
},
{
"title": "React Mount Guide",
"slug": "mounting-react"
"title": "React API",
"slug": "api-react"
},
{
"title": "Vue Component Testing"
"title": "React Examples",
"slug": "examples-react"
},
{
"title": "Quickstart: Vue",
"slug": "quickstart-vue"
},
{
"title": "Mounting Components",
"slug": "mounting-vue"
"title": "Vue Component Testing"
},
{
"title": "Testing Vue Components",
"slug": "testing-vue"
"title": "Introduction",
"slug": "vue"
},
{
"title": "Testing Vue Components with Emitted Events",
"slug": "events-vue"
"title": "Vue Quickstart",
"slug": "quickstart-vue"
},
{
"title": "Testing Vue Components with Slots",
"slug": "slots-vue"
"title": "Vue API",
"slug": "api-vue"
},
{
"title": "Custom Mount Commands and Styles",
"slug": "custom-mount-vue"
"title": "Vue Examples",
"slug": "examples-vue"
},
{
"title": "Angular Component Testing"
21 changes: 21 additions & 0 deletions content/guides/component-testing/api-react.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
title: 'React Mount API'
---

## `mount`

We ship a `mount()` function for mounting React components in isolation. It is
responsible for rendering the component within Cypress's sandboxed iframe and
handling any framework-specific cleanup.

The `mount()` function is imported directly from the `cypress` module:

```js
// React 16, 17
import { mount } from 'cypress/react'

// React 18
import { mount } from 'cypress/react18'
```

...
Original file line number Diff line number Diff line change
@@ -1,31 +1,15 @@
---
title: React Mount Guide
title: React Examples
---

## Mounting Components in React

### What is the Mount Function?

We ship a `mount()` function for mounting React components in isolation. It is
responsible for rendering the component within Cypress's sandboxed iframe and
handling any framework-specific cleanup.

The `mount()` function is imported directly from the `cypress` module:

```js
// React 16, 17
import { mount } from 'cypress/react'

// React 18
import { mount } from 'cypress/react18'
```
## Custom Mount Commands

### Using `cy.mount()` Anywhere

While you can use the `mount` function in your tests, we recommend using
[`cy.mount()`](/api/commands/mount), which is a
[custom command](/api/cypress-api/custom-commands) that is defined in the
**cypress/support/component.js** file:
While you can use the [mount()](/guides/component-testing/api-react#mount)
function in your tests, we recommend using [`cy.mount()`](/api/commands/mount),
which is a [custom command](/api/cypress-api/custom-commands) that is defined in
the **cypress/support/component.js** file:

<code-group>
<code-block label="cypress/support/component.js" active>
@@ -42,20 +26,13 @@ Cypress.Commands.add('mount', mount)
This allows you to use `cy.mount()` in any test without having to import the
`mount()` function in each and every spec file.

You can customize `cy.mount()` to fit your needs. For instance, if you are using
By default, `cy.mount()` is a simple passthrough to `mount()`, however, you can
customize `cy.mount()` to fit your needs. For instance, if you are using
providers or other global app-level setups in your React app, you can configure
them here.

We will go over some common scenarios for customizing the command.

## Customizing cy.mount()

If you need to wrap your component in a parent component in order to work
properly (like providing a context), you might consider creating a custom mount
command that does so.

Below are a few examples that demonstrate this technique. These examples can be
adjusted for most other providers that you will need to support.
Below are a few examples that demonstrate using a custom mount command. These
examples can be adjusted for most other providers that you will need to support.

### React Router

55 changes: 31 additions & 24 deletions content/guides/component-testing/quickstart-react.md
Original file line number Diff line number Diff line change
@@ -177,19 +177,24 @@ describe('<Stepper>', () => {
</code-group>

Let's break down the spec. First, we import the `Stepper` component. Next, we
set up a `describe` block which acts as a container for a suite of tests. The
`describe` block takes in two parameters, the first of which is the name of the
test suite, and the second is a function that will execute the tests.

Inside the `describe` function, we defined a test using the `it` function,
representing a single test. We briefly describe what the test does as the first
param and a function that contains the test code as the second param. In our
example above, we only have one test, but soon we'll see how we can add multiple
`it` blocks inside of a `describe` for a series of tests.

The test executes one command: `cy.mount(<Stepper />)`. The `cy` object is a
global that is used to interact with the Cypress API, and the `mount` method off
of it mounts a component and prepares it for testing.
organize our tests using special blocks. We use two of these blocks in this
spec, `describe`, and `it`. These are global functions provided by Cypress,
which means you don't have to import them directly to use them. We use them to
group similar tests together. The top-level `describe` block will be the
container for all our tests in a file, and each `it` represents an individual
test. The `describe` block takes in two parameters, the first of which is the
name of the test suite, and the second is a function that will execute the
tests.

We defined a test using the `it` function inside `describe`. The first parameter
to `describe` is a brief description of the spec, and the second parameter is a
function that contains the test code. In our example above, we only have one
test, but soon we'll see how we can add multiple `it` blocks inside of a
`describe` for a series of tests.

The test executes one command: `cy.mount(<Stepper />)`. The `cy` object is
another global that is used to interact with the Cypress API, and the `mount`
method off of it mounts a component and prepares it for testing.

Now it's time to see the test in action.

@@ -224,7 +229,7 @@ prop that can specify an initial count.

Let's test that mounting the component in its default state has a count of "0".

To do so, we will use a selector to select the `span` element that contains the
To do so, we will use a selector to access the `span` element that contains the
counter of the component, and then assert that the text value of the element is
what we expect it to be.

@@ -239,7 +244,7 @@ Add the following test inside the `describe` block:
<code-group>
<code-block label="src/components/Stepper.cy.jsx" active>

```jsx
```js
it('stepper should default to 0', () => {
cy.mount(<Stepper />)
cy.get('span').should('have.text', '0')
@@ -263,9 +268,8 @@ In the `Stepper` component, the `span` tag has a `data-cy` attribute on it:
<span data-cy="counter">{count}</span>
```

We can use this data attribute to assign a unique id that we can use for testing
purposes. We can then use an attribute selector in our test to select the
element instead:
We can use data attributes to assign a unique id that can be used for testing
purposes. Update the test to pass in an attribute selector to `cy.get()`:

<code-group>
<code-block label="src/components/Stepper.cy.jsx" active>
@@ -284,14 +288,16 @@ Our selector is now future-proof. For more info on writing good selectors, see
our guide
[Selector Best Practices](/guides/references/best-practices#Selecting-Elements).

### Passing Props to Components

We should also have a test to ensure the `initial` prop sets the test to
something else besides its default value of "0". We can pass in props to the
`Stepper` component in the `mount` method:

<code-group>
<code-block label="src/components/Stepper.cy.jsx" active>

```jsx
```js
it('supports an "initial" prop to set the value', () => {
cy.mount(<Stepper initial={100} />)
cy.get('[data-cy=counter]').should('have.text', '100')
@@ -336,8 +342,8 @@ component. Consumers are alerted to changes to the state by passing in a
callback to the `onChange` prop.

As the developer of the Stepper component, you want to make sure that when the
end-user clicks the increment and decrement buttons, that the **onChange** prop
is called in the consuming component.
end-user clicks the increment and decrement buttons, that the `onChange` prop is
called with the proper values in the consuming component.

### Using Spies

@@ -366,9 +372,10 @@ it('clicking + fires a change event with the incremented value', () => {
</code-group>

First, we create a new spy by calling the `cy.spy()` method. We pass in a string
that gives the spy an [alias](/guides/core-concepts/variables-and-aliases) (a
name by which we can reference it later). In `cy.mount()`, we initialize the
component and pass the spy into it. After that, we click the increment button.
that gives the spy an [alias](/guides/core-concepts/variables-and-aliases),
which give the spy a name by which we can reference it later. In `cy.mount()`,
we initialize the component and pass the spy into it. After that, we click the
increment button.

The next line is a bit different. We've seen how we can use the `cy.get()`
method to select elements, but we can also use it to grab any aliases we've set
394 changes: 343 additions & 51 deletions content/guides/component-testing/quickstart-vue.md

Large diffs are not rendered by default.

80 changes: 80 additions & 0 deletions content/guides/component-testing/react.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
---
title: 'React Component Testing'
---

## Framework Support

Cypress Component Testing supports React 16+ in a variety of different
frameworks:

- Create React App
- Next.js
- React with Vite
- Custom Webpack Config

## Tutorial

Visit the [React Quickstart Guide](/guides/component-testing/quickstart-react)
for a step-by-step tutorial.

## Installation

To get up and running with Cypress Component Testing in React, install Cypress
into your project:

```bash
npm i cypress -D
```

Open Cypress:

```bash
npx cypress open
```

The Cypress Launchpad will now open and guide you through the configuring your
project.

Whenever you run Cypress for the first time, the app will prompt you to set up
either E2E Testing or Component Testing. Click on "Component Testing" to start
the configuration wizard.

<DocsImage
src="/img/guides/component-testing/select-test-type.jpg"
caption="Choose Component Testing"> </DocsImage>

The Project Setup screen automatically detects your framework and bundler. Click
"Next Step" to continue.

<DocsImage
src="/img/guides/component-testing/project-setup-react.jpg"
caption="React and Vite are automatically detected"> </DocsImage>

The next screen checks that all the required dependencies are installed. All the
items should have green checkboxes on them, indicating zeverything is good, so
click "Continue".

<DocsImage
src="/img/guides/component-testing/dependency-detection-react.jpg"
caption="All necessary dependencies are installed"> </DocsImage>

Next, Cypress generates all the necessary configuration files and gives you a
list of all the changes it made to your project.

<DocsImage
src="/img/guides/component-testing/scaffolded-files.jpg"
caption="The Cypress launchpad will scaffold all of these files for you">
</DocsImage>

After setting up component testing, you will be at the browser selection screen.

Pick the browser of your choice and click the "Start Component Testing" button
to open the Cypress test runner.

<DocsImage
src="/img/guides/component-testing/select-browser.jpg"
caption="Choose your browser"> </DocsImage>

Your React project is now set up with Component Testing! For a guide on writing
a test, checkout the [Quickstart](/guides/component-testing/quickstart-react)
tutorial.
79 changes: 79 additions & 0 deletions content/guides/component-testing/vue.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
title: 'Vue Component Testing'
---

## Framework Support

Cypress Component Testing supports Vue 2+ in a variety of different frameworks:

- Vue CLI
- Nuxt
- Vue with Vite
- Custom Webpack Config

## Tutorial

Visit the [Vue Quickstart Guide](/guides/component-testing/quickstart-vue) for a
step-by-step tutorial.

## Installation

To get up and running with Cypress Component Testing in Vue, install Cypress
into your project:

```bash
npm i cypress -D
```

Open Cypress:

```bash
npx cypress open
```

The Cypress Launchpad will now open and guide you through the configuring your
project.

Whenever you run Cypress for the first time, the app will prompt you to set up
either E2E Testing or Component Testing. Click on "Component Testing" to start
the configuration wizard.

<DocsImage
src="/img/guides/component-testing/select-test-type.jpg"
caption="Choose Component Testing"> </DocsImage>

The Project Setup screen automatically detects your framework and bundler. Click
"Next Step" to continue.

<DocsImage
src="/img/guides/component-testing/project-setup-vue.jpg"
caption="Vue and Vite are automatically detected"> </DocsImage>

The next screen checks that all the required dependencies are installed. All the
items should have green checkboxes on them, indicating everything is good, so
click "Continue".

<DocsImage
src="/img/guides/component-testing/dependency-detection-vue.jpg"
caption="All necessary dependencies are installed"> </DocsImage>

Next, Cypress generates all the necessary configuration files and gives you a
list of all the changes it made to your project.

<DocsImage
src="/img/guides/component-testing/scaffolded-files.jpg"
caption="The Cypress launchpad will scaffold all of these files for you">
</DocsImage>

After setting up component testing, you will be at the browser selection screen.

Pick the browser of your choice and click the "Start Component Testing" button
to open the Cypress test runner.

<DocsImage
src="/img/guides/component-testing/select-browser.jpg"
caption="Choose your browser"> </DocsImage>

Your Vue project is now set up with Component Testing! For a guide on writing a
test, checkout the [Quickstart](/guides/component-testing/quickstart-vue)
tutorial.