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

Rename uses of whitelist for renamed options. #2928

Merged
merged 2 commits into from Jun 30, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
17 changes: 9 additions & 8 deletions source/api/commands/server.md
Expand Up @@ -57,7 +57,7 @@ Option | Default | Description
`onAnyRequest` | `undefined` | callback function called when any request is sent
`onAnyResponse` | `undefined` | callback function called when any response is returned
`urlMatchingOptions` | `{ matchBase: true }` | The default options passed to `minimatch` when using glob strings to match URLs
`whitelist` | function | Callback function that filters requests from ever being logged or stubbed. By default this matches against asset-like requests such as for `.js`, `.jsx`, `.html`, and `.css` files.
`ignore` | function | Callback function that filters requests from ever being logged or stubbed. By default this matches against asset-like requests such as for `.js`, `.jsx`, `.html`, and `.css` files.

## Yields {% helper_icon yields %}

Expand All @@ -70,7 +70,7 @@ Option | Default | Description
### After starting a server:

- Any request that does **NOT** match a {% url `cy.route()` route %} will {% url 'pass through to the server' network-requests#Don’t-Stub-Responses %}.
- Any request that matches the `options.whitelist` function will **NOT** be logged or stubbed. In other words it is filtered and ignored.
- Any request that matches the `options.ignore` function will **NOT** be logged or stubbed.
- You will see requests named as `(XHR Stub)` or `(XHR)` in the Command Log.

```javascript
Expand Down Expand Up @@ -181,27 +181,27 @@ cy.server({

### Change the default filtering

`cy.server()` comes with a `whitelist` function that by default filters out any requests that are for static assets like `.html`, `.js`, `.jsx`, and `.css`.
`cy.server()` comes with an `ignore` function that by default filters out any requests that are for static assets like `.html`, `.js`, `.jsx`, and `.css`.

Any request that passes the `whitelist` will be ignored - it will not be logged nor will it be stubbed in any way (even if it matches a specific {% url `cy.route()` route %}).
Any request that passes the `ignore` will be ignored - it will not be logged nor will it be stubbed in any way (even if it matches a specific {% url `cy.route()` route %}).

The idea is that we never want to interfere with static assets that are fetched via Ajax.

**The default filter function in Cypress is:**

```javascript
const whitelist = (xhr) => {
const ignore = (xhr) => {
// this function receives the xhr object in question and
// will filter if it's a GET that appears to be a static resource
return xhr.method === 'GET' && /\.(jsx?|html|css)(\?.*)?$/.test(xhr.url)
// will ignore if it's a GET that appears to be a static resource
return xhr.method === 'GET' && /\.(jsx?|coffee|html|less|s?css|svg)(\?.*)?$/.test(xhr.url)
}
```

**You can override this function with your own specific logic:**

```javascript
cy.server({
whitelist: (xhr) => {
ignore: (xhr) => {
// specify your own function that should return
// truthy if you want this xhr to be ignored,
// not logged, and not stubbed.
Expand Down Expand Up @@ -270,6 +270,7 @@ The intention of {% url "`cy.request()`" request %} is to be used for checking e
- `cy.server()` does *not* log in the Command Log

{% history %}
{% url "5.0.0" changelog#5-0-0 %} | Renamed `whitelist` option to `ignore`
{% url "0.13.6" changelog#0-13-6 %} | Added `onAbort` callback option
{% url "0.5.10" changelog#0-5-10 %} | Added `delay` option
{% url "0.3.3" changelog#0-3-3 %} | Added `whitelist` option
Expand Down
11 changes: 6 additions & 5 deletions source/api/cypress-api/cookies.md
Expand Up @@ -129,7 +129,7 @@ Any change you make here will take effect immediately for the remainder of every
A great place to put this configuration is in your `cypress/support/index.js` file, since it is loaded before any test files are evaluated.
{% endnote %}

### `whitelist` accepts:
### `preserve` accepts:

- String
- Array
Expand All @@ -142,7 +142,7 @@ A great place to put this configuration is in your `cypress/support/index.js` fi
// now any cookie with the name 'session_id' will
// not be cleared before each test runs
Cypress.Cookies.defaults({
whitelist: 'session_id'
preserve: 'session_id'
})
```

Expand All @@ -152,7 +152,7 @@ Cypress.Cookies.defaults({
// now any cookie with the name 'session_id' or 'remember_token'
// will not be cleared before each test runs
Cypress.Cookies.defaults({
whitelist: ['session_id', 'remember_token']
preserve: ['session_id', 'remember_token']
})
```

Expand All @@ -162,15 +162,15 @@ Cypress.Cookies.defaults({
// now any cookie that matches this RegExp
// will not be cleared before each test runs
Cypress.Cookies.defaults({
whitelist: /session|remember/
preserve: /session|remember/
})
```

### Preserve Function

```javascript
Cypress.Cookies.defaults({
whitelist: (cookie) => {
preserve: (cookie) => {
// implement your own logic here
// if the function returns truthy
// then the cookie will not be cleared
Expand All @@ -180,6 +180,7 @@ Cypress.Cookies.defaults({
```

{% history %}
{% url "5.0.0" changelog#5-0-0 %} | Renamed `whitelist` option to `preserve`
{% url "0.16.1" changelog#0-16-1 %} | `{verbose: false}` option added
{% url "0.16.0" changelog#0-16-0 %} | Removed support for `Cypress.Cookies.get`, `Cypress.Cookies.set` and `Cypress.Cookies.remove`
{% url "0.12.4" changelog#0-12-4 %} | `Cypress.Cookies` API added
Expand Down
2 changes: 1 addition & 1 deletion source/api/cypress-api/cypress-server.md
Expand Up @@ -28,7 +28,7 @@ Pass in an options object to change the default behavior of `Cypress.Server`.
Cypress.Server.defaults({
delay: 500,
force404: false,
whitelist: (xhr) => {
ignore: (xhr) => {
// handle custom logic for filtering XHR requests
}
})
Expand Down
2 changes: 1 addition & 1 deletion source/faq/questions/using-cypress-faq.md
Expand Up @@ -420,7 +420,7 @@ You can preserve specific cookies across tests using the {% url "Cypress.Cookies
// now any cookie with the name 'session_id' will
// not be cleared before each test runs
Cypress.Cookies.defaults({
whitelist: 'session_id'
preserve: 'session_id'
})
```

Expand Down