Test/Suit configuration options + Cypress.isBrowser updates

source/_partial/per_test_config_whitelist.md

@@ -0,0 +1,12 @@
+{% fa fa-exclamation-triangle red %} **Note:** Some configuration values are readonly and cannot be changed via test configuration. The following configuration values **can be changed** via per test configuration:
+
+- `animationDistanceThreshold`
+- `baseUrl`
+- `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 declaration
+
+You can configure the `cy.exec()` timeout within a suite or test by passing the new configuration value as a second argument within the {% url "test declaration" configuration#Test-Declaration %}.
+
+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 declaration
+
+You can configure the `cy.task()` timeout within a suite or test by passing the new configuration value as a second argument within the {% url "test declaration" configuration#Test-Declaration %}.
+
+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 declaration
+
+You can configure the size of the viewport height and width within a suite or test by passing the new configuration values as a second argument within the {% url "test declaration" configuration#Test-Declaration %}.
+
+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/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
+
+### Per test configuration: `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` configuration value per test or suite. The `browser` configuration 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 "Per Test Configuration" configuration#Test-Declaration %}

source/guides/core-concepts/writing-and-organizing-tests.md

@@ -141,7 +141,7 @@ If you're familiar with writing tests in JavaScript, then writing tests in Cypre
 
 ## Test Structure
 
-The test interface borrowed from {% url 'Mocha' bundled-tools#Mocha %} provides `describe()`, `context()`, `it()` and `specify()`.
+The test interface, borrowed from {% url 'Mocha' bundled-tools#Mocha %}, provides `describe()`, `context()`, `it()` and `specify()`.
 
 `context()` is identical to `describe()` and `specify()` is identical to `it()`, so choose whatever terminology works best for you.
 
@@ -199,17 +199,17 @@ describe('Hooks', () => {
     // runs once before all tests in the block
   })
 
-  after(() => {
-    // runs once after all tests in the block
-  })
-
   beforeEach(() => {
     // runs before each test in the block
   })
 
   afterEach(() => {
     // runs after each test in the block
   })
+
+  after(() => {
+    // runs once after all tests in the block
+  })
 })
 ```
 
@@ -278,6 +278,49 @@ it.skip('returns "fizz" when number is multiple of 3', () => {
 })
 ```
 
+## Test Declaration Configuration
+
+To apply a specific Cypress {% url "configuration" configuration %} value to a suite or test, pass a configuration object to test or suite the function as the second argument.
+
+### Syntax
+
+```javascript
+describe(name, configuration, fn)
+context(name, configuration, fn)
+it(name, configuration, fn)
+specify(name, configuration, fn)
+```
+
+### Whitelisted config values
+
+{% partial per_test_config_whitelist %}
+
+### Configure suite of tests configuration
+
+```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)
+  })
+})
+```
+
+### Configure single test configuration
+
+```js
+it('open product view', (), { waitForAnimations: false } => {
+  cy.contains('Add to Cart').click()
+  cy.get('#modal').contains('Confirm').click()
+})
+```
+
 ## Dynamically Generate Tests
 
 You can dynamically generate tests using JavaScript.