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 List of Valid Test Configuration Config Values #4252

Merged
merged 8 commits into from
Dec 21, 2021
Merged

Update List of Valid Test Configuration Config Values #4252

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
f987ab1
update list of writeable config
davidmunechika Dec 3, 2021
3f32e34
update browser config docs
davidmunechika Dec 10, 2021
9cb6fa5
fix spacing
davidmunechika Dec 10, 2021
7ae5375
update Cypress.config docs
davidmunechika Dec 17, 2021
77aad4c
Update wording to be even more specific that the values below are all…
jennifer-shehane Dec 20, 2021
268373f
Don't need to be so specific about why they can't update.
jennifer-shehane Dec 20, 2021
9023081
Merge branch '9.2.0-release' into issue-6407-read-only-config
emilyrohrbough Dec 20, 2021
34adc88
incorrectly resolved Jennifers change
emilyrohrbough Dec 20, 2021
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
34 changes: 18 additions & 16 deletions content/api/cypress-api/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,8 @@ Cypress.config('pageLoadTimeout') // => 60000

<strong class="alert-header">Scope</strong>

Remember, any changes that you make to configuration using this API will be
in effect for the remainder of the tests _in the same spec file._
Remember, any changes that you make to configuration using this API will be in
effect for the remainder of the tests _in the same spec file._

</Alert>

Expand Down Expand Up @@ -140,37 +140,39 @@ Cypress.config() // => {defaultCommandTimeout: 10000, viewportHeight: 900, ...}

### Not all config values can be changed at all times

Some configuration values are readonly and cannot be changed while running a test. Anything
that's not directly under Cypress's control - like timeouts, `userAgent`, or
environment variables - will be ignored at run-time. Be sure to review the list of
[test configuration options](/guides/references/configuration##Test-Configuration).
Some configuration values are readonly and cannot be changed during running a
Copy link
Member

Choose a reason for hiding this comment

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

268373f#diff-915c4bed144b351513cdcaa774106a940b56dc71f5a53116990509f9353c46a1R143

test. Anything that is not listed in the
[test configuration options](/guides/references/configuration#Test-Configuration)
cannot be updated at runtime. Be sure to review the list of
[test configuration options that can be updated](/guides/references/configuration#Test-Configuration).

### Test Configuration vs `Cypress.config()`

To apply specific Cypress configuration values to a suite or test, you can pass a
[test configuration](/guides/references/configuration#Test-Configuration) object
to the test or suite function.
To apply specific Cypress configuration values to a suite or test, you can pass
a [test configuration](/guides/references/configuration#Test-Configuration)
object to the test or suite function.

While `Cypress.config()` changes configuration values through the entire spec
file, using test configuration will only change configuration values during the
suite or test where they are set. The values will then reset to the previous
default values after the suite or test is complete.

See the full guide on [test configuration](/guides/references/configuration#Test-Configuration).
See the full guide on
[test configuration](/guides/references/configuration#Test-Configuration).

### `Cypress.config()` executes Synchronously

It's important to note that `Cypress.config()` executes synchronously and will not wait for the Cypress commands above it to execute.
If you need to update your configuration mid-test, be sure to chain the
It's important to note that `Cypress.config()` executes synchronously and will
not wait for the Cypress commands above it to execute. If you need to update
your configuration mid-test, be sure to chain the
[asynchronously Cypress command](/guides/core-concepts/introduction-to-cypress#Commands-Are-Asynchronous).

```javascript
it('using cy.then', () => {
cy.visit('/my-test_page')
cy.click('#download-html')
.then(() => {
Cypress.config('baseUrl', 'null')
})
cy.click('#download-html').then(() => {
Cypress.config('baseUrl', 'null')
})
cy.visit('/downloads/contents.html')
})
```
Expand Down
53 changes: 30 additions & 23 deletions content/guides/references/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,15 +54,15 @@ you should understand well. The default values listed here are meaningful.

</Alert>

| Option | Default | Description |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultCommandTimeout` | `4000` | Time, in milliseconds, to wait until most DOM based commands are considered timed out |
| `execTimeout` | `60000` | Time, in milliseconds, to wait for a system command to finish executing during a [`cy.exec()`](/api/commands/exec) command |
| `taskTimeout` | `60000` | Time, in milliseconds, to wait for a task to finish executing during a [`cy.task()`](/api/commands/task) command |
| `pageLoadTimeout` | `60000` | Time, in milliseconds, to wait for `page transition events` or [`cy.visit()`](/api/commands/visit), [`cy.go()`](/api/commands/go), [`cy.reload()`](/api/commands/reload) commands to fire their page `load` events. Network requests are limited by the underlying operating system, and may still time out if this value is increased. |
| `requestTimeout` | `5000` | Time, in milliseconds, to wait for a request to go out in a [`cy.wait()`](/api/commands/wait) command |
| `responseTimeout` | `30000` | Time, in milliseconds, to wait until a response in a [`cy.request()`](/api/commands/request), [`cy.wait()`](/api/commands/wait), [`cy.fixture()`](/api/commands/fixture), [`cy.getCookie()`](/api/commands/getcookie), [`cy.getCookies()`](/api/commands/getcookies), [`cy.setCookie()`](/api/commands/setcookie), [`cy.clearCookie()`](/api/commands/clearcookie), [`cy.clearCookies()`](/api/commands/clearcookies), and [`cy.screenshot()`](/api/commands/screenshot) commands |
| `slowTestThreshold` | `10000 \| 250` | Time, in milliseconds, to consider a test "slow" during `cypress run`. A slow test will display in orange text in the default reporter. You will often want to configure this differently for component and e2e testing. Default is 10000 for e2e and 250 for component tests. |
| Option | Default | Description |
| ----------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultCommandTimeout` | `4000` | Time, in milliseconds, to wait until most DOM based commands are considered timed out |
| `execTimeout` | `60000` | Time, in milliseconds, to wait for a system command to finish executing during a [`cy.exec()`](/api/commands/exec) command |
| `taskTimeout` | `60000` | Time, in milliseconds, to wait for a task to finish executing during a [`cy.task()`](/api/commands/task) command |
| `pageLoadTimeout` | `60000` | Time, in milliseconds, to wait for `page transition events` or [`cy.visit()`](/api/commands/visit), [`cy.go()`](/api/commands/go), [`cy.reload()`](/api/commands/reload) commands to fire their page `load` events. Network requests are limited by the underlying operating system, and may still time out if this value is increased. |
| `requestTimeout` | `5000` | Time, in milliseconds, to wait for a request to go out in a [`cy.wait()`](/api/commands/wait) command |
| `responseTimeout` | `30000` | Time, in milliseconds, to wait until a response in a [`cy.request()`](/api/commands/request), [`cy.wait()`](/api/commands/wait), [`cy.fixture()`](/api/commands/fixture), [`cy.getCookie()`](/api/commands/getcookie), [`cy.getCookies()`](/api/commands/getcookies), [`cy.setCookie()`](/api/commands/setcookie), [`cy.clearCookie()`](/api/commands/clearcookie), [`cy.clearCookies()`](/api/commands/clearcookies), and [`cy.screenshot()`](/api/commands/screenshot) commands |
| `slowTestThreshold` | `10000 \| 250` | Time, in milliseconds, to consider a test "slow" during `cypress run`. A slow test will display in orange text in the default reporter. You will often want to configure this differently for component and e2e testing. Default is 10000 for e2e and 250 for component tests. |

### Folders / Files

Expand Down Expand Up @@ -319,27 +319,32 @@ You can

## Test Configuration

We provide two options to override the configuration while your test are running, `Cypress.config()` and
suite-specific or test-specific configuration overrides.
We provide two options to override the configuration while your test are
running, `Cypress.config()` and suite-specific or test-specific configuration
overrides.

<Icon name="exclamation-triangle" color="red"></Icon> **Note:** Some
configuration values are readonly and cannot be changed via test configuration.
The following configuration values **can be changed** via per test
configuration:
<Icon name="exclamation-triangle" color="red"></Icon> **Note:** The
configuration values below are all writeable and **can be changed** via per test
configuration. Any other configuration values are readonly and cannot be changed
at run time.

- `animationDistanceThreshold`
- `baseUrl`
- `browser` **note:** filters whether the tests or a suite of tests runs
davidmunechika marked this conversation as resolved.
Show resolved Hide resolved
depending on the current browser
- `blockHosts`
- `defaultCommandTimeout`
- `execTimeout`
- `env` **note:** Provided environment variables will be merged with current
environment variables.
- `execTimeout`
- `experimentalSessionSupport`
- `includeShadowDom`
- `keystrokeDelay`
- `numTestsKeptInMemory`
- `pageLoadTimeout`
- `redirectionLimit`
- `requestTimeout`
- `responseTimeout`
- `retries`
- `screenshotOnRunFailure`
- `scrollBehavior`
- `slowTestThreshold`
- `viewportHeight`
Expand All @@ -351,15 +356,16 @@ configuration:
You can also override configuration values within your test using
[`Cypress.config()`](/api/cypress-api/config).


This changes the configuration _for the remaining execution of the current spec file_.
The values will reset to the previous default values after the spec has complete.
This changes the configuration _for the remaining execution of the current spec
file_. The values will reset to the previous default values after the spec has
complete.

```javascript
Cypress.config('pageLoadTimeout', 100000)

Cypress.config('pageLoadTimeout') // => 100000
```

#### Test-specific Configuration

To apply specific Cypress [configuration](/guides/references/configuration)
Expand All @@ -381,8 +387,9 @@ specify(name, config, fn)

##### Suite configuration

If you want to target a suite of tests to run or be excluded when run in a specific browser, you can override
the `browser` configuration within the suite configuration. The `browser` option accepts the same arguments as
If you want to target a suite of tests to run or be excluded when run in a
specific browser, you can override the `browser` configuration within the suite
configuration. The `browser` option accepts the same arguments as
[`Cypress.isBrowser()`](/api/cypress-api/isbrowser).

You can configure the number of times to retries a suite of tests if they fail
Expand Down