Skip to content

Commit 446c5b8

Browse files
robertgussrobertguss
authored
Merge pull request #4034 from cypress-io/bug-ct-intro-missing-code-block
fix: fix the code block that was not rendering on the CT page
2 parents 26d38c1 + 4b368a0 commit 446c5b8

File tree

1 file changed

+123
-45
lines changed

1 file changed

+123
-45
lines changed

‎content/guides/component-testing/introduction.md

+123-45
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,43 @@ title: Introduction
33
containerClass: component-testing
44
---
55

6-
⚠️ The Cypress Component Testing library is still in **Alpha**. We are rapidly developing and expect that the API may undergo breaking changes. Contribute to its development by submitting feature requests or issues [here](https://github.com/cypress-io/cypress/).
6+
⚠️ The Cypress Component Testing library is still in **Alpha**. We are rapidly
7+
developing and expect that the API may undergo breaking changes. Contribute to
8+
its development by submitting feature requests or issues
9+
[here](https://github.com/cypress-io/cypress/).
710

811
</alert>
912

1013
## What is Component Testing?
1114

1215
_Definition: Running tests on a component in isolation._
1316

14-
Typically component tests are run using a Node.js testing framework like `jest` or `mocha`. Components we want to test are rendered in a virtualized browser called [jsdom](https://github.com/jsdom/jsdom).
17+
Typically component tests are run using a Node.js testing framework like `jest`
18+
or `mocha`. Components we want to test are rendered in a virtualized browser
19+
called [jsdom](https://github.com/jsdom/jsdom).
1520

16-
With component testing in Cypress, you can achieve the same goal: test a component in isolation. Instead of having components render inside a terminal, Cypress renders components in a real browser. Since the components you are testing are visible in the browser, this makes it easier to test and debug when a test fails.
21+
With component testing in Cypress, you can achieve the same goal: test a
22+
component in isolation. Instead of having components render inside a terminal,
23+
Cypress renders components in a real browser. Since the components you are
24+
testing are visible in the browser, this makes it easier to test and debug when
25+
a test fails.
1726

18-
Component testing in Cypress is similar to end-to-end testing. The notable differences are:
27+
Component testing in Cypress is similar to end-to-end testing. The notable
28+
differences are:
1929

20-
- There's no need to navigate to a URL. You don't need to call [`cy.visit()`](/api/commands/visit) in your test.
30+
- There's no need to navigate to a URL. You don't need to call
31+
[`cy.visit()`](/api/commands/visit) in your test.
2132
- Cypress provides a blank canvas where we can `mount` components in isolation.
2233

2334
## Getting Started
2435

25-
A Cypress Component Test contains a `mount` function and assertions about the component it has rendered. A test may interact with component as a user would, using Cypress API commands like [.click()](/api/commands/click), [.type()](/api/commands/type), or [many more](/api/api/table-of-contents).
36+
A Cypress Component Test contains a `mount` function and assertions about the
37+
component it has rendered. A test may interact with component as a user would,
38+
using Cypress API commands like [.click()](/api/commands/click),
39+
[.type()](/api/commands/type), or [many more](/api/api/table-of-contents).
2640

27-
With Cypress as the Test Runner and assertions framework, component tests in React and Vue look very similar. Here's an example, written in React:
41+
With Cypress as the Test Runner and assertions framework, component tests in
42+
React and Vue look very similar. Here's an example, written in React:
2843

2944
```javascript
3045
import { mount } from '@cypress/react' // or @cypress/vue
@@ -49,32 +64,51 @@ describe('TodoList', () => {
4964
})
5065
```
5166

52-
If you are already familiar with Cypress, you'll notice it is almost exactly the same as a Cypress end-to-end testing - all your existing Cypress knowledge and experience is transferrable.
67+
If you are already familiar with Cypress, you'll notice it is almost exactly the
68+
same as a Cypress end-to-end testing - all your existing Cypress knowledge and
69+
experience is transferrable.
5370

5471
## Project Setup
5572

56-
Let's go through the setup to start testing components. You can set it up with an existing React or Vue project, or start a new project from scratch. This guide assumes your project uses a [Webpack based](https://webpack.js.org/) tool chain. For our experimental Vite based instructions, please see the information here.
73+
Let's go through the setup to start testing components. You can set it up with
74+
an existing React or Vue project, or start a new project from scratch. This
75+
guide assumes your project uses a [Webpack based](https://webpack.js.org/) tool
76+
chain. For our experimental Vite based instructions, please see the information
77+
here.
5778

5879
<alert type="info">
5980

60-
If you currently do not use Webpack, you can create a separate configuration for Webpack specifically for Cypress Component Testing. Follow the [Webpack getting started guide](https://webpack.js.org/guides/getting-started/) to create a new Webpack config, then continue following the [Installation guide](#Install) below.
81+
If you currently do not use Webpack, you can create a separate configuration for
82+
Webpack specifically for Cypress Component Testing. Follow the
83+
[Webpack getting started guide](https://webpack.js.org/guides/getting-started/)
84+
to create a new Webpack config, then continue following the
85+
[Installation guide](#Install) below.
6186

6287
</alert>
6388

6489
### Prerequisites
6590

6691
- A project with a `package.json` file at the root that runs on Webpack 4 or 5.
67-
- A `webpack.config.js` file, or a way to access Webpack configuration. Refer to your framework's documentation.
68-
- Some components that you want to test that visually display in a browser. It could be a date picker, tabs, responsive images.
69-
- A basic knowledge of how to write tests in Cypress. (See the [Getting Started](/guides/core-concepts/introduction-to-cypress) guide.)
92+
- A `webpack.config.js` file, or a way to access Webpack configuration. Refer to
93+
your framework's documentation.
94+
- Some components that you want to test that visually display in a browser. It
95+
could be a date picker, tabs, responsive images.
96+
- A basic knowledge of how to write tests in Cypress. (See the
97+
[Getting Started](/guides/core-concepts/introduction-to-cypress) guide.)
7098

7199
### ⚠️ Existing end-to-end users
72100

73-
If you are using Cypress Component Testing in a project that also has tests written with the Cypress End-to-End test runner, you may want to configure some Component Testing specific defaults.
101+
If you are using Cypress Component Testing in a project that also has tests
102+
written with the Cypress End-to-End test runner, you may want to configure some
103+
Component Testing specific defaults.
74104

75-
You can configure or override Component Testing defaults in your [configuration file](/guides/references/configuration) (`cypress.json` by default) using the `component` key.
105+
You can configure or override Component Testing defaults in your
106+
[configuration file](/guides/references/configuration) (`cypress.json` by
107+
default) using the `component` key.
76108

77-
For example, if you would like to use a different viewport size or target different test files for Component Testing, your `cypress.json` might look like this:
109+
For example, if you would like to use a different viewport size or target
110+
different test files for Component Testing, your `cypress.json` might look like
111+
this:
78112

79113
```json
80114
{
@@ -88,17 +122,21 @@ For example, if you would like to use a different viewport size or target differ
88122
}
89123
```
90124

91-
The Component Testing runner will use all the configuration at the root level of your configuration file and apply any Component Testing specific overrides.
125+
The Component Testing runner will use all the configuration at the root level of
126+
your configuration file and apply any Component Testing specific overrides.
92127

93128
### Install
94129

95130
<alert type="info">
96131

97-
If you are using [Vue.js](https://vuejs.org/), click on the Vue tab of the code examples in our documentation when available. If there is no Vue tab, the code is the same.
132+
If you are using [Vue.js](https://vuejs.org/), click on the Vue tab of the code
133+
examples in our documentation when available. If there is no Vue tab, the code
134+
is the same.
98135

99136
</alert>
100137

101-
Start by running the command below to install dependencies. It will install both the latest version of Cypress and the tooling you need to run component testing.
138+
Start by running the command below to install dependencies. It will install both
139+
the latest version of Cypress and the tooling you need to run component testing.
102140

103141
<code-group>
104142
<code-block label="React" active>
@@ -119,11 +157,15 @@ npm install --save-dev cypress @cypress/vue @cypress/webpack-dev-server webpack-
119157

120158
<alert type="info">
121159

122-
If it's your first time using Cypress, check out the [main Getting Started documentation](/guides/getting-started/installing-cypress).
160+
If it's your first time using Cypress, check out the
161+
[main Getting Started documentation](/guides/getting-started/installing-cypress).
123162

124163
</alert>
125164

126-
Once installed, you need to configure how Cypress will locate component spec files. In the following configuration file (`cypress.json` by default), all components test files contained within the `src` directory and match the glob given in the `testFiles` key.
165+
Once installed, you need to configure how Cypress will locate component spec
166+
files. In the following configuration file (`cypress.json` by default), all
167+
components test files contained within the `src` directory and match the glob
168+
given in the `testFiles` key.
127169

128170
```json
129171
{
@@ -134,7 +176,11 @@ Once installed, you need to configure how Cypress will locate component spec fil
134176
}
135177
```
136178

137-
You will also need to configure the component testing framework of your choice by installing the corresponding component testing plugin. Read more about Cypress plugins in our [plugins guide](/guides/tooling/plugins-guide). For example, if you are using Create React App, you will need to use the `react-scripts` plugin as shown below in your `cypress/plugins/index.js` file.
179+
You will also need to configure the component testing framework of your choice
180+
by installing the corresponding component testing plugin. Read more about
181+
Cypress plugins in our [plugins guide](/guides/tooling/plugins-guide). For
182+
example, if you are using Create React App, you will need to use the
183+
`react-scripts` plugin as shown below in your `cypress/plugins/index.js` file.
138184

139185
<code-group>
140186
<code-block label="React (using CRA)" active>
@@ -194,28 +240,42 @@ module.exports = (on, config) => {
194240
</code-block>
195241
</code-group>
196242

197-
Note we have a conditional check against `config.testingType`. This is useful if your project is already using existing plugins for the End-to-end runner, and you don't want them to conflict.
243+
Note we have a conditional check against `config.testingType`. This is useful if
244+
your project is already using existing plugins for the End-to-end runner, and
245+
you don't want them to conflict.
198246

199-
If you have a different React development environment from Create React App, such as Next.js, or use a Vue template other than vue-cli, you will need to import the appropriate plugin. See a list of officially maintained plugins [here](https://github.com/cypress-io/cypress/tree/develop/npm/react/plugins). Each of these plugins perform the same tasks under the hood. Alternatively, if you have your own Webpack configuration, you can just provide it (without need for a specific plugin) as specified above.
247+
If you have a different React development environment from Create React App,
248+
such as Next.js, or use a Vue template other than vue-cli, you will need to
249+
import the appropriate plugin. See a list of officially maintained plugins
250+
[here](https://github.com/cypress-io/cypress/tree/develop/npm/react/plugins).
251+
Each of these plugins perform the same tasks under the hood. Alternatively, if
252+
you have your own Webpack configuration, you can just provide it (without need
253+
for a specific plugin) as specified above.
200254

201255
<alert type="info">
202256

203-
If you have separate Webpack configurations for development and production, use the development configuration. It will give better location information using SourceMaps.
257+
If you have separate Webpack configurations for development and production, use
258+
the development configuration. It will give better location information using
259+
SourceMaps.
204260

205261
</alert>
206262

207263
### Writing Component Tests
208264

209265
This example assumes a project with a `<Button />` component.
210266

211-
We recommend locating your component tests next to the components you are testing. If you are using our recommended `testFiles` glob (`**/*spec.{js,jsx,ts,tsx}`) [as described above](#Install):
267+
We recommend locating your component tests next to the components you are
268+
testing. If you are using our recommended `testFiles` glob
269+
(`**/*spec.{js,jsx,ts,tsx}`) [as described above](#Install):
212270

213271
- Navigate to where this component exists in your code.
214272
- Create a spec file in the same folder called `Button.spec.jsx`.
215273

216-
Otherwise create `Button.spec.jsx` in the relevant directory based on your configuration.
274+
Otherwise create `Button.spec.jsx` in the relevant directory based on your
275+
configuration.
217276

218-
Once the test file exists, we can begin to write a test called `Button.spec.jsx`:
277+
Once the test file exists, we can begin to write a test called
278+
`Button.spec.jsx`:
219279

220280
<code-group>
221281
<code-block label="React" active>
@@ -258,7 +318,8 @@ it('Button', () => {
258318

259319
<alert type="info">
260320

261-
The React and Vue tests are nearly identical, allowing for a common shared test style across frameworks!
321+
The React and Vue tests are nearly identical, allowing for a common shared test
322+
style across frameworks!
262323

263324
</alert>
264325

@@ -272,11 +333,13 @@ npx cypress open-ct
272333

273334
<DocsImage src="/img/guides/component-testing/one-spec.png" alt="Single Spec file with single test run" ></DocsImage>
274335

275-
- Try to modify the test in your editor, make the test fail, etc. The tests will re-run instantly with immediate visual feedback.
336+
- Try to modify the test in your editor, make the test fail, etc. The tests will
337+
re-run instantly with immediate visual feedback.
276338

277339
### Set up CI
278340

279-
Sometimes we want to run tests without interactivity and see all results in the terminal, like when we run our tests in continuous integration.
341+
Sometimes we want to run tests without interactivity and see all results in the
342+
terminal, like when we run our tests in continuous integration.
280343

281344
To run all component tests in the terminal, run the command below:
282345

@@ -288,27 +351,38 @@ In the project we just built, this command will show the following results.
288351

289352
<DocsImage src="/img/guides/component-testing/run-result.png" alt="Result of headless test run" ></DocsImage>
290353

291-
To make the component tests part of your [continuous integration](/guides/continuous-integration/introduction) pipeline, add a script to run `npx cypress run-ct` to your CI configuration.
354+
To make the component tests part of your
355+
[continuous integration](/guides/continuous-integration/introduction) pipeline,
356+
add a script to run `npx cypress run-ct` to your CI configuration.
292357

293-
For example, see the repo [cypress-react-component-example](https://github.com/bahmutov/cypress-react-component-example) that uses [Cypress GitHub Action](https://github.com/cypress-io/github-action) to first run the E2E tests, then run the component tests.
358+
For example, see the repo
359+
[cypress-react-component-example](https://github.com/bahmutov/cypress-react-component-example)
360+
that uses [Cypress GitHub Action](https://github.com/cypress-io/github-action)
361+
to first run the E2E tests, then run the component tests.
294362

295363
### Experimental
296364

297-
The tools listed in this section are actively being developed. We will support early adoption of these projects in order to get community feedback. Please report issues against these projects in Github or contact us on [Discord](https://discord.gg/Cd4CdSx) for additional support.
365+
The tools listed in this section are actively being developed. We will support
366+
early adoption of these projects in order to get community feedback.
367+
Please report issues against these projects in Github or contact us on
368+
[Discord](https://discord.gg/Cd4CdSx) for additional support.
298369

299370
#### Vite
300371

301-
For a quick-start, please take a look at the boilerplate repositories below. To setup a project from scratch please check out the below plugins file.
372+
For a quick-start, please take a look at the boilerplate repositories below. To
373+
setup a project from scratch please check out the below plugins file.
302374

303375
**From Boilerplate**
304376

305-
- [Vite + Vue 3](https://github.com/JessicaSachs/cypress-loves-vite) (VueConfUS 2021 by Jessica Sachs)
377+
- [Vite + Vue 3](https://github.com/JessicaSachs/cypress-loves-vite) (VueConfUS
378+
2021 by Jessica Sachs)
306379

307380
**From Scratch**
308381

309-
To get started with Vite, please follow the installation instructions for Webpack, but replace `@cypress/webpack-dev-server` with `@cypress/vite-dev-server`. Here is a sample `plugins.js` file where the `dev-server:start` event is registered with Vite.
310-
311-
<code-block label="plugins.js">
382+
To get started with Vite, please follow the installation instructions for
383+
Webpack, but replace `@cypress/webpack-dev-server` with
384+
`@cypress/vite-dev-server`. Here is a sample `plugins.js` file where the
385+
`dev-server:start` event is registered with Vite.
312386

313387
```js
314388
import { startDevServer } from '@cypress/vite-dev-server'
@@ -323,9 +397,9 @@ export default function (on, config) {
323397
}
324398
```
325399

326-
</code-block>
327-
328-
Exactly like Webpack, you should start Cypress with `yarn cypress open-ct`. Writing component tests when using Vite is _exactly_ the same as when using Webpack. Minor differences may occur depending on the
400+
Exactly like Webpack, you should start Cypress with `yarn cypress open-ct`.
401+
Writing component tests when using Vite is _exactly_ the same as when using
402+
Webpack. Minor differences may occur depending on the
329403

330404
**Known issues**
331405

@@ -335,12 +409,16 @@ Exactly like Webpack, you should start Cypress with `yarn cypress open-ct`. Writ
335409

336410
**Debugging Strategies**
337411

338-
Issues will often arise during the initial compilation and start of your project. Please collect logs and focus on stripping down your `viteConfig` to work around any issues. Please log any issues in Github.
412+
Issues will often arise during the initial compilation and start of your
413+
project. Please collect logs and focus on stripping down your `viteConfig` to
414+
work around any issues. Please log any issues in Github.
339415

340416
**Collecting logs**
341417

342-
To debug any Vite issues, run Cypress using `DEBUG=cypress:* yarn cypress open-ct`.
418+
To debug any Vite issues, run Cypress using
419+
`DEBUG=cypress:* yarn cypress open-ct`.
343420

344421
**Compiling your project**
345422

346-
Remove all plugins and pass in an empty `viteConfig` into the `startDevServer` options. Add plugins in one-at-a-time
423+
Remove all plugins and pass in an empty `viteConfig` into the `startDevServer`
424+
options. Add plugins in one-at-a-time

0 commit comments

Comments
 (0)