You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Cypress runs tests in a unique interactive runner that allows you to see commands as they execute while also viewing the application under test.
16
+
Cypress runs tests in a unique interactive runner that allows you to see
17
+
commands as they execute while also viewing the application under test.
17
18
18
19
<DocsImagesrc="/img/guides/gui-diagram.png"alt="Cypress Test Runner"></DocsImage>
19
20
20
21
## Command Log
21
22
22
-
The lefthand side of the Test Runner is a visual representation of your test suite. Each test block is properly nested and each test, when clicked, displays every Cypress command and assertion executed within the test's block as well as any command or assertion executed in relevant `before`, `beforeEach`, `afterEach`, and `after` hooks.
23
+
The lefthand side of the Test Runner is a visual representation of your test
24
+
suite. Each test block is properly nested and each test, when clicked, displays
25
+
every Cypress command and assertion executed within the test's block as well as
26
+
any command or assertion executed in relevant `before`, `beforeEach`,
27
+
`afterEach`, and `after` hooks.
23
28
24
29
<DocsImagesrc="/img/guides/command-log.png"alt="Cypress Test Runner"width-600 ></DocsImage>
25
30
26
31
### Open files in your IDE
27
32
28
-
There are some places in the Command Log that display a link to the relevant file where the code is located. Clicking on this link will open the file in your [preferred file opener](/guides/tooling/IDE-integration#File-Opener-Preference).
33
+
There are some places in the Command Log that display a link to the relevant
34
+
file where the code is located. Clicking on this link will open the file in your
<DocsImagesrc="/img/guides/open-file-in-IDE.gif"alt="Open file your IDE" ></DocsImage>
31
38
32
39
### Hovering on Commands
33
40
34
-
Each command and assertion, when hovered over, restores the Application Under Test (righthand side) to the state it was in when that command executed. This allows you to 'time-travel' back to previous states of your application when testing.
41
+
Each command and assertion, when hovered over, restores the Application Under
42
+
Test (righthand side) to the state it was in when that command executed. This
43
+
allows you to 'time-travel' back to previous states of your application when
44
+
testing.
35
45
36
46
<Alerttype="info">
37
47
38
-
By default, Cypress keeps 50 tests worth of snapshots and command data for time traveling. If you are seeing extremely high memory consumption in your browser, you may want to lower the `numTestsKeptInMemory` in your [configuration](/guides/references/configuration#Global).
48
+
By default, Cypress keeps 50 tests worth of snapshots and command data for time
49
+
traveling. If you are seeing extremely high memory consumption in your browser,
50
+
you may want to lower the `numTestsKeptInMemory` in your
Each command, assertion, or error, when clicked on, displays extra information in the dev tools console. Clicking also 'pins' the Application Under Test (righthand side) to its previous state when the command executed.
57
+
Each command, assertion, or error, when clicked on, displays extra information
58
+
in the dev tools console. Clicking also 'pins' the Application Under Test
59
+
(righthand side) to its previous state when the command executed.
45
60
46
61
<DocsImagesrc="/img/guides/clicking-commands.png"alt="Click to console.log and to pin" ></DocsImage>
47
62
48
63
## Errors
49
64
50
-
Cypress prints several pieces of information when an error occurs during a Cypress test.
51
-
52
-
1.**Error name**: This is the type of the error (e.g. AssertionError, CypressError)
53
-
1.**Error message**: This generally tells you what went wrong. It can vary in length. Some are short like in the example, while some are long, and may tell you exactly how to fix the error.
54
-
1.**Learn more:** Some error messages contain a Learn more link that will take you to relevant Cypress documentation.
55
-
1.**Code frame file**: This is usually the top line of the stack trace and it shows the file, line number, and column number that is highlighted in the code frame below. Clicking on this link will open the file in your [preferred file opener](https://on.cypress.io/IDE-integration#File-Opener-Preference) and highlight the line and column in editors that support it.
56
-
1.**Code frame**: This shows a snippet of code where the failure occurred, with the relevant line and column highlighted.
57
-
1.**View stack trace**: Clicking this toggles the visibility of the stack trace. Stack traces vary in length. Clicking on a blue file path will open the file in your [preferred file opener](https://on.cypress.io/IDE-integration#File-Opener-Preference).
58
-
1.**Print to console button**: Click this to print the full error to your DevTools console. This will usually allow you to click on lines in the stack trace and open files in your DevTools.
65
+
Cypress prints several pieces of information when an error occurs during a
66
+
Cypress test.
67
+
68
+
1.**Error name**: This is the type of the error (e.g. AssertionError,
69
+
CypressError)
70
+
1.**Error message**: This generally tells you what went wrong. It can vary in
71
+
length. Some are short like in the example, while some are long, and may tell
72
+
you exactly how to fix the error.
73
+
1.**Learn more:** Some error messages contain a Learn more link that will take
74
+
you to relevant Cypress documentation.
75
+
1.**Code frame file**: This is usually the top line of the stack trace and it
76
+
shows the file, line number, and column number that is highlighted in the
77
+
code frame below. Clicking on this link will open the file in your
For certain commands like [`cy.intercept()`](/api/commands/intercept), [`cy.stub()`](/api/commands/stub), and [`cy.spy()`](/api/commands/spy), an extra instrument panel is displayed above the test to give more information about the state of your tests.
94
+
For certain commands like [`cy.intercept()`](/api/commands/intercept),
95
+
[`cy.stub()`](/api/commands/stub), and [`cy.spy()`](/api/commands/spy), an extra
96
+
instrument panel is displayed above the test to give more information about the
97
+
state of your tests.
65
98
66
99
### Routes
67
100
@@ -77,7 +110,10 @@ For certain commands like [`cy.intercept()`](/api/commands/intercept), [`cy.stub
77
110
78
111
## Application Under Test
79
112
80
-
The righthand side of the Test Runner is used to display the Application Under Test (AUT): the application that was navigated to using a [`cy.visit()`](/api/commands/visit) or any subsequent routing calls made from the visited application.
113
+
The righthand side of the Test Runner is used to display the Application Under
114
+
Test (AUT): the application that was navigated to using a
115
+
[`cy.visit()`](/api/commands/visit) or any subsequent routing calls made from
116
+
the visited application.
81
117
82
118
In the example below, we wrote the following code in our test file:
In the corresponding Application Preview below, you can see `https://example.cypress.io` is being displayed in the righthand side. Not only is the application visible, but it is fully interactable. You can open your developer tools to inspect elements as you would in your normal application. The DOM is completely available for debugging.
126
+
In the corresponding Application Preview below, you can see
127
+
`https://example.cypress.io` is being displayed in the righthand side. Not only
128
+
is the application visible, but it is fully interactable. You can open your
129
+
developer tools to inspect elements as you would in your normal application. The
130
+
DOM is completely available for debugging.
91
131
92
132
<DocsImagesrc="/img/guides/application-under-test.png"alt="Application Under Test" ></DocsImage>
93
133
94
-
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 [Cypress configuration](/guides/references/configuration#Viewport). If the AUT does not fit within the current browser window, it is scaled appropriately to fit within the window.
134
+
The AUT also displays in the size and orientation specified in your tests. You
135
+
can change the size or orientation with the
136
+
[`cy.viewport()`](/api/commands/viewport) command or in your
137
+
[Cypress configuration](/guides/references/configuration#Viewport). If the AUT
138
+
does not fit within the current browser window, it is scaled appropriately to
139
+
fit within the window.
95
140
96
-
The current size and scale of the AUT is displayed in the top right corner of the window.
141
+
The current size and scale of the AUT is displayed in the top right corner of
142
+
the window.
97
143
98
-
The image below shows that our application is displaying at `1000px` width, `660px` height and scaled to `100%`.
144
+
The image below shows that our application is displaying at `1000px` width,
_Note: Internally, the AUT renders within an iframe. This can sometimes cause unexpected behaviors [explained here.](/api/commands/window#Cypress-uses-2-different-windows)_
154
+
_Note: Internally, the AUT renders within an iframe. This can sometimes cause
@@ -117,7 +167,8 @@ The Selector Playground is an interactive feature that helps you:
117
167
118
168
### Uniqueness
119
169
120
-
Cypress will automatically calculate a **unique selector** to use targeted element by running through a series of selector strategies.
170
+
Cypress will automatically calculate a **unique selector** to use targeted
171
+
element by running through a series of selector strategies.
121
172
122
173
By default Cypress will favor:
123
174
@@ -136,7 +187,8 @@ By default Cypress will favor:
136
187
137
188
Cypress allows you to control how a selector is determined.
138
189
139
-
Use the [Cypress.SelectorPlayground](/api/cypress-api/selector-playground-api) API to control the selectors you want returned.
190
+
Use the [Cypress.SelectorPlayground](/api/cypress-api/selector-playground-api)
191
+
API to control the selectors you want returned.
140
192
141
193
</Alert>
142
194
@@ -147,17 +199,25 @@ You may find yourself struggling to write good selectors because:
147
199
- Your application uses dynamic ID's and class names
148
200
- Your tests break whenever there are CSS or content changes
149
201
150
-
To help with these common challenges, the Selector Playground automatically prefers certain `data-*` attributes when determining a unique selector.
202
+
To help with these common challenges, the Selector Playground automatically
203
+
prefers certain `data-*` attributes when determining a unique selector.
151
204
152
-
Please read our [Best Practices guide](/guides/references/best-practices#Selecting-Elements) on helping you target elements and prevent tests from breaking on CSS or JS changes.
205
+
Please read our
206
+
[Best Practices guide](/guides/references/best-practices#Selecting-Elements) on
207
+
helping you target elements and prevent tests from breaking on CSS or JS
208
+
changes.
153
209
154
210
### Finding Selectors
155
211
156
-
To open the Selector Playground, click the `<Icon name="crosshairs" color="grey"></Icon>` button next to the URL at the top of the runner. Hover over elements in your app to preview a unique selector for that element in the tooltip.
212
+
To open the Selector Playground, click the <Iconname="crosshairs"></Icon>
213
+
button next to the URL at the top of the runner. Hover over elements in your app
214
+
to preview a unique selector for that element in the tooltip.
157
215
158
216
<DocsImagesrc="/img/guides/test-runner/open-selector-playground.gif"alt="Opening selector playground and hovering over elements" ></DocsImage>
159
217
160
-
Click on the element and its selector will appear at the top. From there, you can copy it to your clipboard (`<Icon name="copy" color="grey"></Icon>`) or print it to the console (`<Icon name="terminal"></Icon>`).
218
+
Click on the element and its selector will appear at the top. From there, you
219
+
can copy it to your clipboard ( <Iconname="copy"></Icon> ) or print it to the
220
+
console ( <Iconname="terminal"></Icon> ).
161
221
162
222
<DocsImagesrc="/img/guides/test-runner/copy-selector-in-selector-playground.gif"alt="Clicking an element, copying its selector to clipboard, printing it to the console" ></DocsImage>
163
223
@@ -167,27 +227,35 @@ The box at the top that displays the selector is also a text input.
167
227
168
228
#### Editing a Selector
169
229
170
-
When you edit the selector, it will show you how many elements match and highlight those elements in your app.
230
+
When you edit the selector, it will show you how many elements match and
231
+
highlight those elements in your app.
171
232
172
233
<DocsImagesrc="/img/guides/test-runner/typing-a-selector-to-find-in-playground.gif"alt="Type a selector to see what elements it matches" ></DocsImage>
173
234
174
235
#### Switching to Contains
175
236
176
-
You can also experiment with what [`cy.contains()`](/api/commands/contains) would yield given a string of text. Click on `cy.get` and switch to `cy.contains`.
237
+
You can also experiment with what [`cy.contains()`](/api/commands/contains)
238
+
would yield given a string of text. Click on `cy.get` and switch to
239
+
`cy.contains`.
177
240
178
-
Type in text to see which element it matches. Note that [`cy.contains()`](/api/commands/contains) only yields the first element that matches the text, even if multiple elements on the page contain the text.
241
+
Type in text to see which element it matches. Note that
242
+
[`cy.contains()`](/api/commands/contains) only yields the first element that
243
+
matches the text, even if multiple elements on the page contain the text.
179
244
180
245
<DocsImagesrc="/img/guides/test-runner/cy-contains-in-selector-playground.gif"alt="Experiment with cy.contains" ></DocsImage>
181
246
182
247
#### Disabling Highlights
183
248
184
-
If you would like to interact with your app while the Selector Playground is open, the element highlighting might get in the way. Toggling the highlighting off will allow you to interact with your app more easily.
249
+
If you would like to interact with your app while the Selector Playground is
250
+
open, the element highlighting might get in the way. Toggling the highlighting
251
+
off will allow you to interact with your app more easily.
185
252
186
253
<DocsImagesrc="/img/guides/test-runner/turn-off-highlight-in-selector-playground.gif"alt="Turn off highlighting" ></DocsImage>
187
254
188
255
## Keyboard Shortcuts
189
256
190
-
There are keyboard shortcuts to quickly perform common actions from within the Test Runner.
257
+
There are keyboard shortcuts to quickly perform common actions from within the
0 commit comments