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.

Sign up for GitHub

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 validation error scenarios #4842

Merged
merged 8 commits into from
Nov 29, 2022
Merged

Update validation error scenarios #4842

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e4d4449
Update validation error scenarios
emilyrohrbough Nov 7, 2022
5fc0575
Delete stubs-with-aliases-and-error-in-command-log.png
emilyrohrbough Nov 7, 2022
31019c2
Delete stub-in-command-log.png
emilyrohrbough Nov 7, 2022
07c3e20
Delete inspect-the-stubbed-object-and-any-calls-or-arguments-made.png
emilyrohrbough Nov 7, 2022
c5d6a2c
Update content/api/commands/session.md
emilyrohrbough Nov 15, 2022
d7989ca
Merge branch 'master' into fix-validation-err-handling-scenarios
emilyrohrbough Nov 28, 2022
0e17fab
Merge branch 'master' into fix-validation-err-handling-scenarios
emilyrohrbough Nov 29, 2022
8f93f6c
fix markdown
emilyrohrbough Nov 29, 2022
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
29 changes: 15 additions & 14 deletions content/api/commands/session.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,10 +140,10 @@ before `setup` runs, regardless of the testIsolation configuration.

**<Icon name="angle-right"></Icon> options** **_(Object)_**

| Option | Default | Description |
| ------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `validate` | `undefined` | Validates the newly-created or restored session.<br><br>Function to run immediately after the session is created and `setup` function runs or after a session is restored and the page is cleared. If this returns `false`, throws an exception, contains any failing Cypress command, or returns a Promise which rejects or resolves to `false`, the session is considered invalid.<br><br>- If validation fails immediately after `setup`, the test will fail.<br>- If validation fails after restoring a session, `setup` will re-run. |
| `cacheAcrossSpecs` | `false` | When enabled, the newly created session is considered "global" and can be restored in any spec during the test execution in the same Cypress run on the same machine. Use this option for a session that will be used multiple times, across many specs. |
| Option | Default | Description g |
| ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `validate` | `undefined` | Validates the newly-created or restored session.<br><br>Function to run immediately after the session is created and `setup` function runs or after a session is restored and the page is cleared. If it throws an exception, contains any failing Cypress command, returns a Promise which rejects or resolves to `false`, or the last Cypress command yielded `false`, the session is considered invalid.<br><br>- If validation fails immediately after `setup`, the test will fail.<br>- If validation fails after restoring a session, `setup` will re-run. |
| `cacheAcrossSpecs` | `false` | When enabled, the newly created session is considered "global" and can be restored in any spec during the test execution in the same Cypress run on the same machine. Use this option for a session that will be used multiple times, across many specs. |

### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)

Expand Down Expand Up @@ -370,9 +370,17 @@ it('should transfer money between users', () => {

### Validating the session

If the `validate` function return `false`, throws an exception, returns a
Promise that resolves to `false` or rejects, or contains any failing Cypress
command, the session will be considered invalid, and `setup` will be re-run.
The `validate` function is used to ensure the session has been correctly
established. This is especially helpful when a cached session is being restored,
because if the session is not valid, `cy.session()` will recreate the session by
re-running `setup`.

The following scenarios will mark the session as invalid:

- the `validate` function throws an exception
- the `validate` function returns a Promise that resolves to `false` or rejects
- the `validate` function contains failing Cypress command
- the last Cypress command in the `validate` function yielded `false`

Here are a few `validate` examples:

Expand All @@ -392,13 +400,6 @@ function validate() {
cy.visit('/account', { failOnStatusCode: false })
cy.url().should('match', /^/account/)
}

// Or just return false if the session is invalid
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we not want an example for "the validate function returns a Promise that resolves to false or rejects" anymore?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to do more comprehensive evaluation for the docs for the v12 release.

function validate() {
if (!MyApp.isSessionValid()) {
return false
}
}
```

### Modifying session data before caching
Expand Down