Test/Suit configuration options + Cypress.isBrowser updates

source/_partial/test_options_config_whitelist.md

@@ -0,0 +1,13 @@
+{% fa fa-exclamation-triangle red %} **Note:** Some configuration values are readonly and cannot be changed via test options. The following configuration values **can be changed** via per test options:
+
+- `animationDistanceThreshold`
+- `baseUrl`
+- `browser`
+- `defaultCommandTimeout`
+- `execTimeout`
+- `env`
+- `requestTimeout`
+- `responseTimeout`
+- `viewportHeight`
+- `viewportWidth`
+- `waitForAnimations`

source/api/commands/exec.md

@@ -140,6 +140,35 @@ cy.exec('echo $USERNAME', { env: { USERNAME: 'johndoe' } })
 
 A command must exit within the `execTimeout` or Cypress will kill the command's process and fail the current test.
 
+## Reset timeout via `Cypress.config()`
+
+You can change the timeout of `cy.exec()` for the remainder of the tests by setting the new values for `execTimeout` within {% url "`Cypress.config()`" config %}.
+
+```js
+Cypress.config('execTimeout', 30000)
+Cypress.config('execTimeout') // => 30000
+```
+
+## Set timeout in the test options
+
+You can configure the `cy.exec()` timeout within a suite or test by passing the new configuration value within the {% url "test options" configuration#Test-Options %}.
+
+This will set the timeout throughout the duration of the tests, then return it to the default `execTimeout` when complete.
+
+```js
+describe('has data available from database', { execTimeout: 90000 }, () => {
+  before(() => {
+    cy.exec('rake db:seed')
+  })
+
+  // tests
+
+  after(() => {
+    cy.exec('rake db:reset')
+  })
+})
+```
+
 # Rules
 
 ## Requirements {% helper_icon requirements %}

source/api/commands/task.md

@@ -277,6 +277,35 @@ See {% issue 2284 '#2284' %} for implementation.
 If multiple task objects use the same key, the later registration will overwrite that particular key, similar to how merging multiple objects with duplicate keys will overwrite the first one.
 {% endnote %}
 
+## Reset timeout via `Cypress.config()`
+
+You can change the timeout of `cy.task()` for the remainder of the tests by setting the new values for `taskTimeout` within {% url "`Cypress.config()`" config %}.
+
+```js
+Cypress.config('taskTimeout', 30000)
+Cypress.config('taskTimeout') // => 30000
+```
+
+## Set timeout in the test options
+
+You can configure the `cy.task()` timeout within a suite or test by passing the new configuration value within the {% url "test options" configuration#Test-Options %}.
+
+This will set the timeout throughout the duration of the tests, then return it to the default `taskTimeout` when complete.
+
+```js
+describe('has data available from database', { taskTimeout: 90000 }, () => {
+  before(() => {
+    cy.task('seedDatabase')
+  })
+
+  // tests
+
+  after(() => {
+    cy.task('resetDatabase')
+  })
+})
+```
+
 # Rules
 
 ## Requirements {% helper_icon requirements %}

source/api/commands/viewport.md

@@ -203,6 +203,36 @@ Scaling the app should not affect any calculations or behavior of your applicati
 
 The upsides to this are that tests should consistently pass or fail regardless of a developers' screen size. Tests will also consistently run in `CI` because all of the viewports will be the same no matter what machine Cypress runs on.
 
+## Reset viewport via `Cypress.config()`
+
+You can change the size of the viewport height and width for the remainder of the tests by setting the new values for `viewportHeight` or `viewportWidth` within {% url "`Cypress.config()`" config %}.
+
+```js
+Cypress.config('viewportWidth', 800)
+Cypress.config('viewportWidth') // => 800
+```
+
+## Set viewport in the test options
+
+You can configure the size of the viewport height and width within a suite or test by passing the new configuration value within the {% url "test options" configuration#Test-Options %}.
+
+This will set the height and width throughout the duration of the tests, then return it to the default `viewportHeight` and `viewportWidth` when complete.
+
+```js
+describe('page display on medium size screen', {
+  viewportHeight: 1000,
+  viewportWidth: 400
+}, () => {
+  it('does not display sidebar', () => {
+    cy.get('#sidebar').should('not.be.visible')
+  })
+
+  it('shows hamburger menu', () => {
+    cy.get('#header').find('i.menu').should('be.visible)
+  })
+})
+```
+
 # Rules
 
 ## Requirements {% helper_icon requirements %}
@@ -249,4 +279,5 @@ When clicking on `viewport` within the command log, the console outputs the foll
 
 # See also
 
-- {% url 'configuration' configuration %}
+- {% url 'Configuration' configuration %}
+- {% url '`Cypress.config()`' config %}

source/api/cypress-api/config.md

@@ -121,6 +121,14 @@ Cypress.config() // => {defaultCommandTimeout: 10000, viewportHeight: 900, ...}
 
 Some configuration values 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.
 
+## Test Options
+
+To apply a specific Cypress {% url "configuration" configuration %} value to a suite or test you can pass an {% url "test options", configuration#Test-Options %} to the test or suite function.
+
+`Cypress.config()` changes the configuration value through the entire spec file. But using test options will only change the configuration value during the suite or tests where they are set then return to their previous default values after the suite or tests are complete.
+
+See the full guide on {% url "test options", configuration#Test-Options %}.
+
 ## Why is it `Cypress.config` and not `cy.config`?
 
 As a rule of thumb anything you call from `Cypress` affects global state. Anything you call from `cy` affects local state.
@@ -135,3 +143,4 @@ Since the configuration added or changed by `Cypress.config` is only in scope fo
 
 - {% url 'configuration' configuration %}
 - The {% url 'Environment Variable' environment-variables %} guide
+- {% url "Test Options" configuration#Test-Options %}

source/api/cypress-api/isbrowser.md

@@ -7,19 +7,24 @@ title: Cypress.isBrowser
 # Syntax
 
 ```javascript
-Cypress.isBrowser(name)
+Cypress.isBrowser(matcher)
+Cypress.isBrowser(matchers)
 Cypress.isBrowser(filter)
 ```
 
 ## Arguments
 
-**{% fa fa-angle-right %} name**  ***(String)***
+**{% fa fa-angle-right %} matcher**  ***(String)***
 
-The name of the browser (case-insensitive).
+The name of the browser (case-insensitive) you want to check against. Name can be prepended with a `!` character to inverse the check.
 
-**{% fa fa-angle-right %} filter**  ***(Object)***
+**{% fa fa-angle-right %} matchers**  ***(Array)***
 
-Filter by the browser properties. You can inspect the current browser's properties by using the {% url "`Cypress.browser`" browser %}. Supported properties are:
+An array of the names of the browsers (case-insensitive) you want to check against. Name can be prepended with a `!` character to inverse the check.
+
+**{% fa fa-angle-right %} filter**  ***(Object or Array)***
+
+Filter one or multiple browsers by the browser properties. You can inspect the current browser's properties by using the {% url "`Cypress.browser`" browser %}. Supported properties are:
 
 Property | Type | Description
 --- | --- | ---
@@ -35,26 +40,60 @@ Property | Type | Description
 
 # Examples
 
-## Name
+## Matcher
 
-### Only run tests in Chrome
+### Only run command in Chrome
 
 ```javascript
-// true when running in Chrome
-if (Cypress.isBrowser('chrome')) {
-  it('only runs in chrome', () => {
-    // test some (hypothetical) issue with chrome
-  })
-}
+it('download extension link', () => {
+  // true when running in Firefox
+  if (Cypress.isBrowser('firefox')) {
+    cy.get('#dl-extension')
+      .should('contain', 'Download Firefox Extension')
+  }
+
+  // true when running in Chrome
+  if (Cypress.isBrowser('chrome')) {
+    cy.get('#dl-extension')
+      .should('contain', 'Download Chrome Extension')
+  }
+})
 ```
 
-### Skip a test in Firefox
+### Run command in all browsers except Chrome
 
 ```javascript
-it('a test', function() {
-  // true when running in Firefox
-  if (Cypress.isBrowser('firefox')) {
-    this.skip()
+it('warns to view page in Chrome browser', () => {
+  // true when running in Firefox, etc...
+  if (Cypress.isBrowser('!chrome')) {
+    cy.get('.browser-warning')
+      .should('contain', 'For optimal viewing, use Chrome browser')
+  }
+})
+```
+
+## Matchers
+
+### Run commands in all specified browsers
+
+```javascript
+it('colors rainbow', () => {
+  // true when running in Electron or Chrome
+  if (Cypress.isBrowser(['electron', 'chrome'])) {
+    cy.get('.rainbox')
+    .should('have.css', 'conic-gradient(red, orange, yellow, green, blue)')
+  }
+})
+```
+
+### Run commands in all browsers except specified
+
+```javascript
+// true when running in browser other than chrome and electron
+it('does not run in Firefox and Chrome', () => {
+  if (Cypress.isBrowser(['!electron', '!chrome'])) {
+    cy.get('#h4')
+    .should('have.css', 'font-size-adjust', '0.5')
   }
 })
 ```
@@ -64,27 +103,60 @@ it('a test', function() {
 ### Only run commands in Chromium-based browser
 
 ```javascript
-it('has correct Chromium-based specific css property', () => {
+it('has CSS reflections', () => {
   // if in Chromium-based browser (Chrome, Electron, etc...)
   // check css property was properly applied
   if (Cypress.isBrowser({ family: 'chromium' })) {
-    cy
-    .get('.header')
-    .should('have.css', 'margin-right')
-    .and('eq', '0')
+    cy.get('.header')
+    .should('have.css', '-webkit-box-reflect', 'left')
   }
 })
 ```
 
 ### Only run on stable release in Chromium-based browser
 
 ```javascript
-// true when running in any stable release of a Chromium-based browser
-if (Cypress.isBrowser({ family: 'chromium', channel: 'stable' })) {
-  it('will not run in Canary or Dev browsers', () => {
-    // test some (hypothetical) issue with chrome
-  })
-}
+it('test', () => {
+  // true when in any stable release of a Chromium-based browser
+  if (Cypress.isBrowser({ family: 'chromium', channel: 'stable' })) {
+    // test some (hypothetical) scenario in chrome stable
+  }
+})
+```
+
+### Only run on specific release channels of browsers
+
+```javascript
+it('test', () => {
+  // true when running in Chrome Canary
+  // and dev releases of Firefox browser
+  if (Cypress.isBrowser([
+    { family: 'chromium', channel: 'canary' },
+    { family: 'firefox', channel: 'dev' }
+  ])) {
+    // test some (hypothetical) scenario
+  }
+})
+```
+
+## Notes
+
+### Test options: `browser`
+
+If you want to target a test or suite to run or be excluded when run in a specific browser, we suggest passing the `browser` within the {% url "test options" configuration#Test-Options %}.  The `browser` option accepts the same {% urlHash "arguments" Arguments %} as `Cypress.isBrowser()`.
+
+```js
+it('Download extension in Firefox', (), { browser: 'firefox' } => {
+  cy.get('#dl-extension')
+    .should('contain', 'Download Firefox Extension')
+})
+```
+
+```js
+it('Show warning outside Chrome', (), {  browser: '!chrome' } => {
+  cy.get('.browser-warning')
+    .should('contain', 'For optimal viewing, use Chrome browser')
+})
 ```
 
 {% history %}
@@ -97,3 +169,4 @@ if (Cypress.isBrowser({ family: 'chromium', channel: 'stable' })) {
 - {% url "Cross Browser Testing" cross-browser-testing %}
 - {% url "`Cypress.browser`" browser %}
 - {% url "Launching Browsers" launching-browsers %}
+- {% url "Test Options" configuration#Test-Options %}