@@ -302,7 +302,7 @@ just in case".
302
302
:::
303
303
304
304
Later in this guide we'll go into much more detail about
305
- [ Default Assertions] ( #Default -Assertions ) and [ Timeouts] ( #Timeouts ) .
305
+ [ Implicit Assertions] ( #Implicit -Assertions ) and [ Timeouts] ( #Timeouts ) .
306
306
307
307
## Chains of Commands
308
308
@@ -912,11 +912,10 @@ randomly fail. This would lead to flaky, inconsistent results.
912
912
913
913
:::info
914
914
915
- While Cypress is built using Promises that come from
916
- [ Bluebird] ( http://bluebirdjs.com/ ) , these are not what we expose as commands and
917
- assertions on ` cy ` . If you'd like to learn more about handling asynchronous
918
- Cypress Commands please read our
919
- [ Core Concept Guide] ( /guides/core-concepts/variables-and-aliases ) .
915
+ While Cypress does have a [ ` .then() ` ] ( /api/commands/then ) command, Cypress
916
+ commands are not Promises and cannot be ` await ` ed. If you'd like to learn more
917
+ about handling asynchronous Cypress Commands please read our
918
+ [ Variables and Aliases Guide] ( /guides/core-concepts/variables-and-aliases ) .
920
919
921
920
:::
922
921
@@ -958,24 +957,22 @@ model after a real user working step by step.
958
957
#### You cannot add a ` .catch ` error handler to a failed command
959
958
960
959
In Cypress there is no built in error recovery from a failed command. A command
961
- and its assertions all _ eventually_ pass , or if one fails, all remaining
962
- commands are not executed, and the test fails.
960
+ _ eventually_ passes , or if it fails, all remaining commands are not executed,
961
+ and the test as a whole fails.
963
962
964
963
You might be wondering:
965
964
966
965
> How do I create conditional control flow, using if/else? So that if an element
967
966
> does (or doesn't) exist, I choose what to do?
968
967
969
- The problem with this question is that this type of conditional control flow
970
- ends up being non-deterministic. This means different test runs may behave
971
- differently, which makes them less deterministic and consistent . In general,
972
- there are only a handful of very specific situations where you _ can _ create
973
- control flow using Cypress commands.
968
+ Cypress does not support this type of conditional control flow because it leads
969
+ to non-deterministic tests - different runs may behave differently, which makes
970
+ them less consistent and useful for verifying your application's correctness . In
971
+ general, there are only a handful of very specific situations where you can or
972
+ should create control flow using Cypress commands.
974
973
975
974
With that said, as long as you are aware of the potential pitfalls with control
976
- flow, it is possible to do this in Cypress!
977
-
978
- You can read all about how to do
975
+ flow, it is possible to do this in Cypress! You can read all about how to do
979
976
[ conditional testing] ( /guides/core-concepts/conditional-testing ) here.
980
977
981
978
## Assertions
@@ -989,33 +986,18 @@ Assertions describe the **desired** state of your **elements**, your
989
986
990
987
:::
991
988
992
- What makes Cypress unique from other testing tools is that commands
993
- ** automatically retry** their assertions. In fact, they will look "downstream"
994
- at what you're expressing and modify their behavior to make your assertions
995
- pass.
996
-
997
- You should think of assertions as ** guards** .
998
-
999
- Use your ** guards** to describe what your application should look like, and
1000
- Cypress will automatically ** block, wait, and retry** until it reaches that
1001
- state.
1002
-
1003
- :::tip
1004
-
1005
- <strong >Core Concept</strong >
1006
-
1007
- Each command documents its behavior with assertions - such as how it retries or
1008
- waits for assertions to pass.
1009
-
1010
- :::
989
+ What makes Cypress unique from other testing tools is that assertions
990
+ ** automatically retry** . Think of them as ** guards** - assertions describe what
991
+ your application should look like, and Cypress will automatically ** block, wait,
992
+ and retry** until it reaches that state.
1011
993
1012
994
### Asserting in English
1013
995
1014
996
Let's look at how you'd describe an assertion in English:
1015
997
1016
998
:::note
1017
999
1018
- After clicking on this ` <button> ` , I expect its class to eventually be ` active ` .
1000
+ After clicking on this ` <button> ` , I expect its class to be ` active ` .
1019
1001
1020
1002
:::
1021
1003
@@ -1027,7 +1009,9 @@ cy.get('button').should('have.class', 'active')
1027
1009
```
1028
1010
1029
1011
This above test will pass even if the ` .active ` class is applied to the button
1030
- asynchronously - or after an indeterminate period of time.
1012
+ asynchronously, after an indeterminate period of time or even if the button is
1013
+ removed from the DOM entirely for a while (replaced with a waiting spinner, for
1014
+ example).
1031
1015
1032
1016
``` javascript
1033
1017
// even though we are adding the class
@@ -1078,7 +1062,7 @@ cy.get('form').submit()
1078
1062
:::
1079
1063
1080
1064
Without a single explicit assertion, there are dozens of ways this test can
1081
- fail! Here's a few:
1065
+ fail. Here's a few:
1082
1066
1083
1067
- The initial [ ` cy.mount() ` ] ( /api/commands/mount ) or
1084
1068
[ ` cy.visit() ` ] ( /api/commands/visit ) could respond with something other than
@@ -1096,17 +1080,16 @@ fail! Here's a few:
1096
1080
1097
1081
<strong >Core Concept</strong >
1098
1082
1099
- With Cypress, you don't have to assert to have a useful test. Even without
1100
- assertions , a few lines of Cypress can ensure thousands of lines of code are
1101
- working properly across the client and server!
1083
+ With Cypress, you don't have to write explicit assertions to have a useful test.
1084
+ Without a single ` expect() ` or ` .should() ` , a few lines of Cypress can ensure
1085
+ thousands of lines of code are working properly across the client and server.
1102
1086
1103
- This is because many commands have a built in
1104
- [ Default Assertion] ( #Default-Assertions ) which offer you a high level of
1105
- guarantee.
1087
+ This is because many commands have a built in Implicit Assertions which offer
1088
+ you a high level of confidence that your application is working as expected.
1106
1089
1107
1090
:::
1108
1091
1109
- ### Default Assertions
1092
+ ### Implicit Assertions
1110
1093
1111
1094
Many commands have default, built-in assertions, or rather have requirements
1112
1095
that may cause it to fail without needing an explicit assertion you've added.
@@ -1159,7 +1142,7 @@ they can fail, typically by passing a `{force: true}` option.
1159
1142
1160
1143
``` js
1161
1144
cy
1162
- // there is a default assertion that this
1145
+ // there is an implicit assertion that this
1163
1146
// button must exist in the DOM before proceeding
1164
1147
.get (' button' )
1165
1148
@@ -1168,16 +1151,16 @@ cy
1168
1151
.click ()
1169
1152
```
1170
1153
1171
- Cypress will automatically _ wait_ for elements to pass their default assertions.
1172
- Like with the explicit assertions you've added, all of these assertions share
1173
- the _ same _ timeout values .
1154
+ Cypress will automatically _ wait_ for elements to pass their implicit
1155
+ assertions. See [ Timeouts ] ( #Timeouts ) below for more on how timeouts are
1156
+ determined .
1174
1157
1175
- #### Example #2 : Reversing the Default Assertion
1158
+ #### Example #2 : Reversing the Implicit Assertion
1176
1159
1177
1160
Most of the time, when querying for elements, you expect them to eventually
1178
1161
exist. But sometimes you wish to wait until they _ don't_ exist.
1179
1162
1180
- All you have to do is add that assertion and Cypress will ** reverse ** its rules
1163
+ All you have to do is add that assertion and Cypress will ** skip ** implicitly
1181
1164
waiting for elements to exist.
1182
1165
1183
1166
``` js
@@ -1196,15 +1179,14 @@ cy.get('#modal').should('not.exist')
1196
1179
1197
1180
<strong >Core Concept</strong >
1198
1181
1199
- By adding [ ` .should('not.exist') ` ] ( /api/commands/should ) to any DOM command,
1200
- Cypress will reverse its default assertion and automatically wait until the
1201
- element does not exist.
1182
+ If you want to disable the default existence assertion, you can add
1183
+ [ ` .should('not.exist') ` ] ( /api/commands/should ) to any DOM command.
1202
1184
1203
1185
:::
1204
1186
1205
- #### Example #3 : Other Default Assertions
1187
+ #### Example #3 : Other Implicit Assertions
1206
1188
1207
- Other commands have other default assertions not related to the DOM.
1189
+ Other commands have other implicit assertions not related to the DOM.
1208
1190
1209
1191
For instance, [ ` .its() ` ] ( /api/commands/its ) requires that the property you're
1210
1192
asking about exists on the object.
@@ -1236,20 +1218,20 @@ use them in Cypress.
1236
1218
1237
1219
There are two ways to write assertions in Cypress:
1238
1220
1239
- 1 . ** Implicit Subjects :** Using [ ` .should() ` ] ( /api/commands/should ) or
1221
+ 1 . ** As Cypress Commands :** Using [ ` .should() ` ] ( /api/commands/should ) or
1240
1222
[ ` .and() ` ] ( /api/commands/and ) .
1241
- 2 . ** Explicit Subjects :** Using ` expect ` .
1223
+ 2 . ** As Mocha Assertions :** Using ` expect ` .
1242
1224
1243
- ### Implicit Subjects
1225
+ ### Command Assertions
1244
1226
1245
1227
Using [ ` .should() ` ] ( /api/commands/should ) or [ ` .and() ` ] ( /api/commands/and )
1246
1228
commands is the preferred way of making assertions in Cypress. These are typical
1247
1229
Cypress commands, which means they apply to the currently yielded subject in the
1248
1230
command chain.
1249
1231
1250
1232
``` javascript
1251
- // the implicit subject here is the first <tr>
1252
- // this asserts that the <tr> has an .active class
1233
+ // The subject here is the first <tr>.
1234
+ // This asserts that the <tr> has an .active class
1253
1235
cy .get (' tbody tr:first' ).should (' have.class' , ' active' )
1254
1236
```
1255
1237
@@ -1268,29 +1250,11 @@ subject, [`.and('have.attr')`](/api/commands/and) is executed against the same
1268
1250
element. This is handy when you need to assert multiple things against a single
1269
1251
subject quickly.
1270
1252
1271
- If we wrote this assertion in the explicit form "the long way", it would look
1272
- like this:
1273
-
1274
- ``` js
1275
- cy .get (' tbody tr:first' ).should (($tr ) => {
1276
- expect ($tr).to .have .class (' active' )
1277
- expect ($tr).to .have .attr (' href' , ' /users' )
1278
- })
1279
- ```
1280
-
1281
- The implicit form is much shorter! So when would you want to use the explicit
1282
- form?
1283
-
1284
- Typically when you want to:
1285
-
1286
- - Assert multiple things about the same subject
1287
- - Massage the subject in some way prior to making the assertion
1288
-
1289
- ### Explicit Subjects
1253
+ ### Mocha Assertions
1290
1254
1291
- Using ` expect ` allows you to pass in a specific subject and make an assertion
1292
- about it . This is probably how you're used to seeing assertions written in unit
1293
- tests:
1255
+ Using ` expect ` allows you to assert on any javascript object, not just the
1256
+ current subject . This is probably how you're used to seeing assertions written
1257
+ in unit tests:
1294
1258
1295
1259
``` js
1296
1260
// the explicit subject here is the boolean: true
@@ -1306,7 +1270,7 @@ Check out our example recipes for [unit testing](/examples/recipes) and
1306
1270
1307
1271
:::
1308
1272
1309
- Explicit assertions are great when you want to:
1273
+ Mocha assertions are great when you want to:
1310
1274
1311
1275
- Perform custom logic prior to making the assertion.
1312
1276
- Make multiple assertions against the same subject.
@@ -1361,7 +1325,7 @@ cy.get('p').should(($p) => {
1361
1325
1362
1326
When using a callback function with [ ` .should() ` ] ( /api/commands/should ) , be sure
1363
1327
that the entire function can be executed multiple times without side effects.
1364
- Cypress applies its [ retry] ( /guides/core-concepts/retry-ability ) logic to these
1328
+ Cypress applies its [ retry logic ] ( /guides/core-concepts/retry-ability ) to these
1365
1329
functions: if there's a failure, it will repeatedly rerun the assertions until
1366
1330
the timeout is reached. That means your code should be retry-safe. The technical
1367
1331
term for this means your code must be ** idempotent** .
@@ -1384,10 +1348,10 @@ Remember because assertions are used to describe a condition of the previous
1384
1348
commands - the ` timeout ` modification goes on the previous commands _ not the
1385
1349
assertions_ .
1386
1350
1387
- #### Example #1 : Default Assertion
1351
+ #### Example #1 : Implicit Assertion
1388
1352
1389
1353
``` js
1390
- // because .get() has a default assertion
1354
+ // because .get() has a implicit assertion
1391
1355
// that this element exists, it can time out and fail
1392
1356
cy .get (' .mobile-nav' )
1393
1357
```
@@ -1416,14 +1380,14 @@ The _total_ amount of time Cypress will wait for _all_ of the assertions to pass
1416
1380
is for the duration of the [ cy.get()] ( /api/commands/get ) ` timeout ` (which is 4
1417
1381
seconds).
1418
1382
1419
- Timeouts can be modified per command and this will affect all default assertions
1420
- and any assertions chained after that command.
1383
+ Timeouts can be modified per command and this will affect all implicit
1384
+ assertions and any assertions chained after that command.
1421
1385
1422
1386
#### Example #3 : Modifying Timeouts
1423
1387
1424
1388
``` js
1425
- // we've modified the timeout which affects default
1426
- // plus all added assertions
1389
+ // we've modified the timeout which affects the implicit
1390
+ // assertions as well as all explicit ones.
1427
1391
cy .get (' .mobile-nav' , { timeout: 10000 })
1428
1392
.should (' be.visible' )
1429
1393
.and (' contain' , ' Home' )
0 commit comments