From a8484991c75584d7bad4109006e66b836d19a0a0 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Wed, 8 Apr 2020 12:55:33 +0630 Subject: [PATCH 01/15] begin adding section for per test configuration --- source/guides/core-concepts/writing-and-organizing-tests.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/guides/core-concepts/writing-and-organizing-tests.md b/source/guides/core-concepts/writing-and-organizing-tests.md index fc77dcfd24..1968c7c1f3 100644 --- a/source/guides/core-concepts/writing-and-organizing-tests.md +++ b/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. @@ -278,6 +278,10 @@ it.skip('returns "fizz" when number is multiple of 3', function () { }) ``` +## Per Test Configuration + +To apply a specific {% url "Cypress configuration" configuration %} value to a suite or test, pass a configuration object to the function. + ## Dynamically Generate Tests You can dynamically generate tests using JavaScript. From 041719b0a4ccd84ca3305de3c51b6d55868fc64f Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Wed, 8 Apr 2020 13:30:51 +0630 Subject: [PATCH 02/15] update isbrowser based on changes to https://github.com/cypress-io/cypress/pull/5346/files --- source/api/cypress-api/isbrowser.md | 57 +++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 3 deletions(-) diff --git a/source/api/cypress-api/isbrowser.md b/source/api/cypress-api/isbrowser.md index 434725f0f1..fffee23b13 100644 --- a/source/api/cypress-api/isbrowser.md +++ b/source/api/cypress-api/isbrowser.md @@ -8,6 +8,8 @@ title: Cypress.isBrowser ```javascript Cypress.isBrowser(name) +Cypress.isBrowser(exclusion) +Cypress.isBrowser(names) Cypress.isBrowser(filter) ``` @@ -15,11 +17,19 @@ Cypress.isBrowser(filter) **{% fa fa-angle-right %} name** ***(String)*** -The name of the browser (case-insensitive). +The name of the browser (case-insensitive) you want to match. -**{% fa fa-angle-right %} filter** ***(Object)*** +**{% fa fa-angle-right %} exclusion** ***(String)*** -Filter by the browser properties. You can inspect the current browser's properties by using the {% url "`Cypress.browser`" browser %}. Supported properties are: +The name of the browser (case-insensitive) you want to exclude prepended with a `!` character. + +**{% fa fa-angle-right %} names** ***(Array)*** + +An array of the names of the browsers (case-insensitive) you want to match. + +**{% 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 --- | --- | --- @@ -59,6 +69,32 @@ it('a test', function() { }) ``` +## Exclusion + +### Run tests in all browsers but firefox + +```javascript +// true when running in Chrome, Electron, etc... +if (Cypress.isBrowser('!firefox')) { + it('does not run in Firefox', () => { + // test some (hypothetical) issue excluding Firefox + }) +} +``` + +## Names + +### Run tests in all specified browsers + +```javascript +// true when running in Firefox and Chrome +if (Cypress.isBrowser(['firefox', 'chrome'])) { + it('runs in Firefox and Chrome only', () => { + // test some (hypothetical) issue in the browsers + }) +} +``` + ## Filter ### Only run commands in Chromium-based browser @@ -87,6 +123,21 @@ if (Cypress.isBrowser({ family: 'chromium', channel: 'stable' })) { } ``` +### Only run on specific release channels of browsers + +```javascript +// true when running in any stable release of a Chromium-based browser +// and dev releases of Firefox browser +if (Cypress.isBrowser([ + { family: 'chromium', channel: 'stable' }, + { family: 'firefox', channel: 'dev' } +])) { + it('will not run in Canary or stable Firefox browsers', () => { + // test some (hypothetical) issue + }) +} +``` + {% history %} {% url "4.0.0" changelog#4-0-0 %} | Added `isBrowser` command. {% endhistory %} From 930de5e534e405f5943da297b91db72818f8a4a1 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Wed, 8 Apr 2020 14:30:25 +0630 Subject: [PATCH 03/15] update isBrowser again...maybe better syntax now. --- source/api/cypress-api/isbrowser.md | 34 ++++++++++++++++------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/source/api/cypress-api/isbrowser.md b/source/api/cypress-api/isbrowser.md index fffee23b13..9773382d0b 100644 --- a/source/api/cypress-api/isbrowser.md +++ b/source/api/cypress-api/isbrowser.md @@ -7,25 +7,20 @@ title: Cypress.isBrowser # Syntax ```javascript -Cypress.isBrowser(name) -Cypress.isBrowser(exclusion) -Cypress.isBrowser(names) +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) you want to match. +The name of the browser (case-insensitive) you want to match or you want to exclude (prepended with a `!` character). -**{% fa fa-angle-right %} exclusion** ***(String)*** +**{% fa fa-angle-right %} matchers** ***(Array)*** -The name of the browser (case-insensitive) you want to exclude prepended with a `!` character. - -**{% fa fa-angle-right %} names** ***(Array)*** - -An array of the names of the browsers (case-insensitive) you want to match. +An array of the names of the browsers (case-insensitive) you want to match or you want to exclude (prepended with a `!` character). **{% fa fa-angle-right %} filter** ***(Object or Array)*** @@ -45,7 +40,7 @@ Property | Type | Description # Examples -## Name +## Matcher ### Only run tests in Chrome @@ -69,8 +64,6 @@ it('a test', function() { }) ``` -## Exclusion - ### Run tests in all browsers but firefox ```javascript @@ -82,7 +75,7 @@ if (Cypress.isBrowser('!firefox')) { } ``` -## Names +## Matchers ### Run tests in all specified browsers @@ -95,6 +88,17 @@ if (Cypress.isBrowser(['firefox', 'chrome'])) { } ``` +### Run tests in all browsers except specified + +```javascript +// true when running in browser other than chrome and firefox +if (Cypress.isBrowser(['!firefox', '!chrome'])) { + it('does not run in Firefox and Chrome', () => { + // test some (hypothetical) issue in the browsers + }) +} +``` + ## Filter ### Only run commands in Chromium-based browser From d33c439f1d8e49bb07dbba9625cb8e84a2501a26 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Wed, 8 Apr 2020 14:30:59 +0630 Subject: [PATCH 04/15] Write section on configuration values per test including examples and whitelisted values. --- .../writing-and-organizing-tests.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/source/guides/core-concepts/writing-and-organizing-tests.md b/source/guides/core-concepts/writing-and-organizing-tests.md index dfbb1a1766..47d9554716 100644 --- a/source/guides/core-concepts/writing-and-organizing-tests.md +++ b/source/guides/core-concepts/writing-and-organizing-tests.md @@ -282,6 +282,53 @@ it.skip('returns "fizz" when number is multiple of 3', () => { To apply a specific {% url "Cypress configuration" configuration %} value to a suite or test, pass a configuration object to the function. +{% note warning %} +Some configuration values are readonly and cannot be changed via test configuration. +{% endnote %} + +### The following configuration values are allowed: + +Option | Default | Description +----- | ---- | ---- +`animationDistanceThreshold` | `5` | The distance in pixels an element must exceed over time to be considered animating +`baseUrl` | `null` | URL used as prefix for {% url `cy.visit()` visit %} or {% url `cy.request()` request %} command's URL +`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 {% url `cy.exec()` exec %} command +`env` | `{}` | Any values to be set as {% url 'environment variables' environment-variables %} +`requestTimeout` | `5000` | Time, in milliseconds, to wait for an XHR request to go out in a {% url `cy.wait()` wait %} command +`responseTimeout` | `30000` | Time, in milliseconds, to wait until a response in a {% url `cy.request()` request %}, {% url `cy.wait()` wait %}, {% url `cy.fixture()` fixture %}, {% url `cy.getCookie()` getcookie %}, {% url `cy.getCookies()` getcookies %}, {% url `cy.setCookie()` setcookie %}, {% url `cy.clearCookie()` clearcookie %}, {% url `cy.clearCookies()` clearcookies %}, and {% url `cy.screenshot()` screenshot %} commands +`viewportHeight` | `660` | Default height in pixels for the application under tests' viewport (Override with {% url `cy.viewport()` viewport %} command) +`viewportWidth` | `1000` | Default width in pixels for the application under tests' viewport. (Override with {% url `cy.viewport()` viewport %} command) +`waitForAnimations` | `true` | Whether to wait for elements to finish animating before executing commands + +### 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. From 36602e589fb98ac627fc3e9d9109d13a5f0597c1 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Wed, 8 Apr 2020 14:33:25 +0630 Subject: [PATCH 05/15] Add per test configuration examples to configuration doc --- source/guides/references/configuration.md | 53 ++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/source/guides/references/configuration.md b/source/guides/references/configuration.md index 6e4d1e59f5..66fa121eb6 100644 --- a/source/guides/references/configuration.md +++ b/source/guides/references/configuration.md @@ -134,7 +134,7 @@ This gives you the option to do things like override the `baseUrl` or environmen When {% url 'running Cypress from the Command Line' command-line %} you can pass a `--config` flag. -**Examples:** +### Examples: ```shell cypress open --config watchForFileChanges=false,waitForAnimations=false @@ -209,6 +209,57 @@ Cypress.config('pageLoadTimeout', 100000) Cypress.config('pageLoadTimeout') // => 100000 ``` +## Per test configuration + +To apply a specific {% url "Cypress configuration" configuration %} value to a suite or test, pass a configuration object to the function. + +{% note warning %} +Some configuration values are readonly and cannot be changed via test configuration. +{% endnote %} + +### The following configuration values are allowed: + +Option | Default | Description +----- | ---- | ---- +`animationDistanceThreshold` | `5` | The distance in pixels an element must exceed over time to be considered animating +`baseUrl` | `null` | URL used as prefix for {% url `cy.visit()` visit %} or {% url `cy.request()` request %} command's URL +`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 {% url `cy.exec()` exec %} command +`env` | `{}` | Any values to be set as {% url 'environment variables' environment-variables %} +`requestTimeout` | `5000` | Time, in milliseconds, to wait for an XHR request to go out in a {% url `cy.wait()` wait %} command +`responseTimeout` | `30000` | Time, in milliseconds, to wait until a response in a {% url `cy.request()` request %}, {% url `cy.wait()` wait %}, {% url `cy.fixture()` fixture %}, {% url `cy.getCookie()` getcookie %}, {% url `cy.getCookies()` getcookies %}, {% url `cy.setCookie()` setcookie %}, {% url `cy.clearCookie()` clearcookie %}, {% url `cy.clearCookies()` clearcookies %}, and {% url `cy.screenshot()` screenshot %} commands +`viewportHeight` | `660` | Default height in pixels for the application under tests' viewport (Override with {% url `cy.viewport()` viewport %} command) +`viewportWidth` | `1000` | Default width in pixels for the application under tests' viewport. (Override with {% url `cy.viewport()` viewport %} command) +`waitForAnimations` | `true` | Whether to wait for elements to finish animating before executing commands + +### 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() +}) +``` + # Resolved Configuration When you open a Cypress project, clicking on the **Settings** tab will display the resolved configuration to you. This helps you to understand and see where different values came from. Each set value is highlighted to show where the value has been set via the following ways: From d20075d06a2cd5fe553dd103b348660403eb8b0e Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Thu, 9 Apr 2020 16:21:16 +0630 Subject: [PATCH 06/15] Move whitelisted values for per test config into partial --- source/_partial/per_test_config_whitelist.md | 12 ++++++ .../writing-and-organizing-tests.md | 38 ++++++++----------- source/guides/references/configuration.md | 21 +--------- 3 files changed, 30 insertions(+), 41 deletions(-) create mode 100644 source/_partial/per_test_config_whitelist.md diff --git a/source/_partial/per_test_config_whitelist.md b/source/_partial/per_test_config_whitelist.md new file mode 100644 index 0000000000..99520b5a37 --- /dev/null +++ b/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` diff --git a/source/guides/core-concepts/writing-and-organizing-tests.md b/source/guides/core-concepts/writing-and-organizing-tests.md index 47d9554716..44dcffc8ca 100644 --- a/source/guides/core-concepts/writing-and-organizing-tests.md +++ b/source/guides/core-concepts/writing-and-organizing-tests.md @@ -199,10 +199,6 @@ 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 }) @@ -210,6 +206,10 @@ describe('Hooks', () => { afterEach(() => { // runs after each test in the block }) + + after(() => { + // runs once after all tests in the block + }) }) ``` @@ -280,26 +280,20 @@ it.skip('returns "fizz" when number is multiple of 3', () => { ## Per Test Configuration -To apply a specific {% url "Cypress configuration" configuration %} value to a suite or test, pass a configuration object to the function. +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. -{% note warning %} -Some configuration values are readonly and cannot be changed via test configuration. -{% endnote %} +### Syntax + +```javascript +describe(name, configuration, fn) +context(name, configuration, fn) +it(name, configuration, fn) +specify(name, configuration, fn) +``` + +### Whitelisted config values -### The following configuration values are allowed: - -Option | Default | Description ------ | ---- | ---- -`animationDistanceThreshold` | `5` | The distance in pixels an element must exceed over time to be considered animating -`baseUrl` | `null` | URL used as prefix for {% url `cy.visit()` visit %} or {% url `cy.request()` request %} command's URL -`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 {% url `cy.exec()` exec %} command -`env` | `{}` | Any values to be set as {% url 'environment variables' environment-variables %} -`requestTimeout` | `5000` | Time, in milliseconds, to wait for an XHR request to go out in a {% url `cy.wait()` wait %} command -`responseTimeout` | `30000` | Time, in milliseconds, to wait until a response in a {% url `cy.request()` request %}, {% url `cy.wait()` wait %}, {% url `cy.fixture()` fixture %}, {% url `cy.getCookie()` getcookie %}, {% url `cy.getCookies()` getcookies %}, {% url `cy.setCookie()` setcookie %}, {% url `cy.clearCookie()` clearcookie %}, {% url `cy.clearCookies()` clearcookies %}, and {% url `cy.screenshot()` screenshot %} commands -`viewportHeight` | `660` | Default height in pixels for the application under tests' viewport (Override with {% url `cy.viewport()` viewport %} command) -`viewportWidth` | `1000` | Default width in pixels for the application under tests' viewport. (Override with {% url `cy.viewport()` viewport %} command) -`waitForAnimations` | `true` | Whether to wait for elements to finish animating before executing commands +{% partial per_test_config_whitelist %} ### Configure suite of tests configuration diff --git a/source/guides/references/configuration.md b/source/guides/references/configuration.md index 66fa121eb6..4d6acf15bb 100644 --- a/source/guides/references/configuration.md +++ b/source/guides/references/configuration.md @@ -211,26 +211,9 @@ Cypress.config('pageLoadTimeout') // => 100000 ## Per test configuration -To apply a specific {% url "Cypress configuration" configuration %} value to a suite or test, pass a configuration object to the function. +To apply a specific Cypress {% url "configuration" configuration %} value to a suite or test, pass a configuration object to the function. -{% note warning %} -Some configuration values are readonly and cannot be changed via test configuration. -{% endnote %} - -### The following configuration values are allowed: - -Option | Default | Description ------ | ---- | ---- -`animationDistanceThreshold` | `5` | The distance in pixels an element must exceed over time to be considered animating -`baseUrl` | `null` | URL used as prefix for {% url `cy.visit()` visit %} or {% url `cy.request()` request %} command's URL -`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 {% url `cy.exec()` exec %} command -`env` | `{}` | Any values to be set as {% url 'environment variables' environment-variables %} -`requestTimeout` | `5000` | Time, in milliseconds, to wait for an XHR request to go out in a {% url `cy.wait()` wait %} command -`responseTimeout` | `30000` | Time, in milliseconds, to wait until a response in a {% url `cy.request()` request %}, {% url `cy.wait()` wait %}, {% url `cy.fixture()` fixture %}, {% url `cy.getCookie()` getcookie %}, {% url `cy.getCookies()` getcookies %}, {% url `cy.setCookie()` setcookie %}, {% url `cy.clearCookie()` clearcookie %}, {% url `cy.clearCookies()` clearcookies %}, and {% url `cy.screenshot()` screenshot %} commands -`viewportHeight` | `660` | Default height in pixels for the application under tests' viewport (Override with {% url `cy.viewport()` viewport %} command) -`viewportWidth` | `1000` | Default width in pixels for the application under tests' viewport. (Override with {% url `cy.viewport()` viewport %} command) -`waitForAnimations` | `true` | Whether to wait for elements to finish animating before executing commands +{% partial per_test_config_whitelist %} ### Configure suite of tests configuration From 39b7fbb916b422c27243f47f30b829a6e31e690b Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Thu, 9 Apr 2020 16:21:35 +0630 Subject: [PATCH 07/15] update examples of isBrowser to be more command based --- source/api/cypress-api/isbrowser.md | 134 ++++++++++++++++------------ 1 file changed, 76 insertions(+), 58 deletions(-) diff --git a/source/api/cypress-api/isbrowser.md b/source/api/cypress-api/isbrowser.md index 9773382d0b..d98b377a54 100644 --- a/source/api/cypress-api/isbrowser.md +++ b/source/api/cypress-api/isbrowser.md @@ -16,11 +16,11 @@ Cypress.isBrowser(filter) **{% fa fa-angle-right %} matcher** ***(String)*** -The name of the browser (case-insensitive) you want to match or you want to exclude (prepended with a `!` character). +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 %} matchers** ***(Array)*** -An array of the names of the browsers (case-insensitive) you want to match or you want to exclude (prepended with a `!` character). +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)*** @@ -42,61 +42,60 @@ Property | Type | Description ## 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 - }) -} -``` - -### Skip a test in Firefox - -```javascript -it('a test', function() { +it('download extension link', () => { // true when running in Firefox if (Cypress.isBrowser('firefox')) { - this.skip() + 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') } }) ``` -### Run tests in all browsers but firefox +### Run command in all browsers except Chrome ```javascript -// true when running in Chrome, Electron, etc... -if (Cypress.isBrowser('!firefox')) { - it('does not run in Firefox', () => { - // test some (hypothetical) issue excluding Firefox - }) -} +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 tests in all specified browsers +### Run commands in all specified browsers ```javascript -// true when running in Firefox and Chrome -if (Cypress.isBrowser(['firefox', 'chrome'])) { - it('runs in Firefox and Chrome only', () => { - // test some (hypothetical) issue in the browsers - }) -} +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 tests in all browsers except specified +### Run commands in all browsers except specified ```javascript -// true when running in browser other than chrome and firefox -if (Cypress.isBrowser(['!firefox', '!chrome'])) { - it('does not run in Firefox and Chrome', () => { - // test some (hypothetical) issue in the browsers - }) -} +// 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') + } +}) ``` ## Filter @@ -104,14 +103,12 @@ if (Cypress.isBrowser(['!firefox', '!chrome'])) { ### 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') } }) ``` @@ -119,27 +116,47 @@ it('has correct Chromium-based specific css property', () => { ### 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 -// true when running in any stable release of a Chromium-based browser -// and dev releases of Firefox browser -if (Cypress.isBrowser([ - { family: 'chromium', channel: 'stable' }, - { family: 'firefox', channel: 'dev' } -])) { - it('will not run in Canary or stable Firefox browsers', () => { - // test some (hypothetical) issue - }) -} +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 %} @@ -152,3 +169,4 @@ if (Cypress.isBrowser([ - {% url "Cross Browser Testing" cross-browser-testing %} - {% url "`Cypress.browser`" browser %} - {% url "Launching Browsers" launching-browsers %} +- {% url "Per Test Configuration" configuration#Per-test-configuration %} From cc6f6e9c5ecf42efd0b4d1b42b79e8aa2c2814fb Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Thu, 9 Apr 2020 16:21:54 +0630 Subject: [PATCH 08/15] Update cross browser testing to use new recommended per test config to ignore/run tests --- source/guides/guides/cross-browser-testing.md | 55 ++++++------------- 1 file changed, 16 insertions(+), 39 deletions(-) diff --git a/source/guides/guides/cross-browser-testing.md b/source/guides/guides/cross-browser-testing.md index 6d4170f86f..cd820e7abc 100644 --- a/source/guides/guides/cross-browser-testing.md +++ b/source/guides/guides/cross-browser-testing.md @@ -182,57 +182,33 @@ workflows: ## Running Specific Tests by Browser -There may be instances where it can be useful to run or ignore one or more tests. For example, test run duration can be reduced by only running smoke-tests against Chrome and not Firefox. This type of granular selection of test execution depends on the type of tests and the level of confidence those specific tests provide to the overall project. +There may be instances where it can be useful to run or ignore one or more tests when in specific browsers. For example, test run duration can be reduced by only running smoke-tests against Chrome and not Firefox. This type of granular selection of test execution depends on the type of tests and the level of confidence those specific tests provide to the overall project. {% note success 'Tip' %} When considering to ignore or only run a particular test within a given browser, assess the true need for the test to run on multiple browsers. {% endnote %} -In the example below we've implemented two helper functions that utilize {% url "`Cypress.isBrowser()`" isbrowser %}, accepting a browser string (e.g. 'chrome', 'firefox') and a callback function of tests: - -- `runOn` can be used to *only* run a test or suite of tests for a given browser. -- `ignoreOn` can be used to completely ignore the execution of a test or test suite for a given browser. +You can specify a browser to run or exclude the test within by passing a configuration option to the test or suite. The `browser` configuration accepts the same arguments as {% url "`Cypress.isBrowser()`" isbrowser#Arguments %}. ```js -const runOn = (browser, fn) => { - if (Cypress.isBrowser(browser)) { - fn() - } -} - -const ignoreOn = (browser, fn) => { - if (!Cypress.isBrowser(browser)) { - fn() - } -} +// Run the test if Cypress is run via Firefox +it('Download extension in Firefox', (), { browser: 'firefox' } => { + cy.get('#dl-extension') + .should('contain', 'Download Firefox Extension') +}) // Run happy path tests if Cypress is run via Firefox -runOn('firefox', () => { - describe('happy path suite', () => { - it('...') - it('...') - it('...') - }) +describe('happy path suite', { browser: 'firefox' }, () => { + it('...') + it('...') + it('...') }) -// Ignore test if Cypress is running via Firefox +// Ignore test if Cypress is running via Chrome // This test is not recorded to the Cypress Dashboard -ignoreOn('firefox', () => { - it('a test', () => { - // ... test body - }) -} -``` - -It is important to note that *ignoring* tests is different from *skipping* tests. When a test is skipped, it is still displayed within test result reports, but when a test is ignored it will never be displayed within reports. If you need to skip a test by browser, but still include it in a custom report or record it to the Cypress Dashboard, you can utilize the following practice: - -```js -// Skip the test, but still record it to the Cypress Dashboard -it('a test', function() { - if (!Cypress.isBrowser('firefox')) { - this.skip() - } - // ... test body +it('Show warning outside Chrome', (), { browser: '!chrome' } => { + cy.get('.browser-warning') + .should('contain', 'For optimal viewing, use Chrome browser') }) ``` @@ -242,3 +218,4 @@ it('a test', function() { - {% url "`Cypress.browser`" browser %} - {% url "`Cypress.isBrowser`" isbrowser %} - {% url "Launching Browsers" launching-browsers %} +- {% url "Per Test Configuration" configuration#Per-test-configuration %} From 1afcb4d0e52a8f86decdb81652c9b9a4cc51654e Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Thu, 9 Apr 2020 16:40:18 +0630 Subject: [PATCH 09/15] Update headings for test declaration config --- source/api/cypress-api/isbrowser.md | 2 +- source/guides/core-concepts/writing-and-organizing-tests.md | 6 ++---- source/guides/guides/cross-browser-testing.md | 2 +- source/guides/references/configuration.md | 6 ++---- 4 files changed, 6 insertions(+), 10 deletions(-) diff --git a/source/api/cypress-api/isbrowser.md b/source/api/cypress-api/isbrowser.md index d98b377a54..a89d7fc5ce 100644 --- a/source/api/cypress-api/isbrowser.md +++ b/source/api/cypress-api/isbrowser.md @@ -169,4 +169,4 @@ it('Show warning outside Chrome', (), { browser: '!chrome' } => { - {% url "Cross Browser Testing" cross-browser-testing %} - {% url "`Cypress.browser`" browser %} - {% url "Launching Browsers" launching-browsers %} -- {% url "Per Test Configuration" configuration#Per-test-configuration %} +- {% url "Per Test Configuration" configuration#Test-Declaration %} diff --git a/source/guides/core-concepts/writing-and-organizing-tests.md b/source/guides/core-concepts/writing-and-organizing-tests.md index 44dcffc8ca..6ad15fc05c 100644 --- a/source/guides/core-concepts/writing-and-organizing-tests.md +++ b/source/guides/core-concepts/writing-and-organizing-tests.md @@ -278,7 +278,7 @@ it.skip('returns "fizz" when number is multiple of 3', () => { }) ``` -## Per Test Configuration +## 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. @@ -315,9 +315,7 @@ describe('page display on medium size screen', { ### Configure single test configuration ```js -it('open product view', (), { - waitForAnimations: false -} => { +it('open product view', (), { waitForAnimations: false } => { cy.contains('Add to Cart').click() cy.get('#modal').contains('Confirm').click() }) diff --git a/source/guides/guides/cross-browser-testing.md b/source/guides/guides/cross-browser-testing.md index cd820e7abc..796e765829 100644 --- a/source/guides/guides/cross-browser-testing.md +++ b/source/guides/guides/cross-browser-testing.md @@ -218,4 +218,4 @@ it('Show warning outside Chrome', (), { browser: '!chrome' } => { - {% url "`Cypress.browser`" browser %} - {% url "`Cypress.isBrowser`" isbrowser %} - {% url "Launching Browsers" launching-browsers %} -- {% url "Per Test Configuration" configuration#Per-test-configuration %} +- {% url "Per Test Configuration" configuration#Test-Declaration %} diff --git a/source/guides/references/configuration.md b/source/guides/references/configuration.md index 4d6acf15bb..4a606e3cad 100644 --- a/source/guides/references/configuration.md +++ b/source/guides/references/configuration.md @@ -209,7 +209,7 @@ Cypress.config('pageLoadTimeout', 100000) Cypress.config('pageLoadTimeout') // => 100000 ``` -## Per test configuration +## Test Declaration To apply a specific Cypress {% url "configuration" configuration %} value to a suite or test, pass a configuration object to the function. @@ -235,9 +235,7 @@ describe('page display on medium size screen', { ### Configure single test configuration ```js -it('open product view', (), { - waitForAnimations: false -} => { +it('open product view', (), { waitForAnimations: false } => { cy.contains('Add to Cart').click() cy.get('#modal').contains('Confirm').click() }) From b5a46e59a4ac48b47691b0b1e54d9af26292634a Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Thu, 9 Apr 2020 16:40:34 +0630 Subject: [PATCH 10/15] Give examples of alternatives to viewport size within cy.viewport doc --- source/api/commands/viewport.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/source/api/commands/viewport.md b/source/api/commands/viewport.md index a7872d8a2a..f79f00b01b 100644 --- a/source/api/commands/viewport.md +++ b/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 %} From 8fa4f215e6ebda8c764bd731b8aa567812b02b9d Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Thu, 9 Apr 2020 16:52:37 +0630 Subject: [PATCH 11/15] Add examples of reseting timeouts for exec and task via other means. --- source/api/commands/exec.md | 29 +++++++++++++++++++++++++++++ source/api/commands/task.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) diff --git a/source/api/commands/exec.md b/source/api/commands/exec.md index 1a8a25bfec..30db2a2cc7 100644 --- a/source/api/commands/exec.md +++ b/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 %} diff --git a/source/api/commands/task.md b/source/api/commands/task.md index c85c05f8e3..c64c72a305 100644 --- a/source/api/commands/task.md +++ b/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 %} From 94f873c0719fdabeea20aa29cd8020ba6e179294 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Thu, 30 Apr 2020 15:27:16 +0630 Subject: [PATCH 12/15] update naming convention for new feature to 'Test Options' --- ...st.md => test_options_config_whitelist.md} | 2 +- source/api/commands/exec.md | 4 ++-- source/api/commands/task.md | 4 ++-- source/api/commands/viewport.md | 4 ++-- source/api/cypress-api/isbrowser.md | 6 +++--- .../writing-and-organizing-tests.md | 20 ++++++++++--------- source/guides/guides/cross-browser-testing.md | 4 ++-- source/guides/references/configuration.md | 12 ++++++----- 8 files changed, 30 insertions(+), 26 deletions(-) rename source/_partial/{per_test_config_whitelist.md => test_options_config_whitelist.md} (63%) diff --git a/source/_partial/per_test_config_whitelist.md b/source/_partial/test_options_config_whitelist.md similarity index 63% rename from source/_partial/per_test_config_whitelist.md rename to source/_partial/test_options_config_whitelist.md index 99520b5a37..cb5b7f564e 100644 --- a/source/_partial/per_test_config_whitelist.md +++ b/source/_partial/test_options_config_whitelist.md @@ -1,4 +1,4 @@ -{% 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: +{% 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` diff --git a/source/api/commands/exec.md b/source/api/commands/exec.md index 30db2a2cc7..7bfe07c965 100644 --- a/source/api/commands/exec.md +++ b/source/api/commands/exec.md @@ -149,9 +149,9 @@ Cypress.config('execTimeout', 30000) Cypress.config('execTimeout') // => 30000 ``` -## Set timeout in the test declaration +## Set timeout in the test options -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 %}. +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. diff --git a/source/api/commands/task.md b/source/api/commands/task.md index c64c72a305..c70d013f5e 100644 --- a/source/api/commands/task.md +++ b/source/api/commands/task.md @@ -286,9 +286,9 @@ Cypress.config('taskTimeout', 30000) Cypress.config('taskTimeout') // => 30000 ``` -## Set timeout in the test declaration +## Set timeout in the test options -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 %}. +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. diff --git a/source/api/commands/viewport.md b/source/api/commands/viewport.md index f79f00b01b..f79fca5c87 100644 --- a/source/api/commands/viewport.md +++ b/source/api/commands/viewport.md @@ -212,9 +212,9 @@ Cypress.config('viewportWidth', 800) Cypress.config('viewportWidth') // => 800 ``` -## Set viewport in the test declaration +## 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 values as a second argument within the {% url "test declaration" configuration#Test-Declaration %}. +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. diff --git a/source/api/cypress-api/isbrowser.md b/source/api/cypress-api/isbrowser.md index a89d7fc5ce..2985821a44 100644 --- a/source/api/cypress-api/isbrowser.md +++ b/source/api/cypress-api/isbrowser.md @@ -141,9 +141,9 @@ it('test', () => { ## Notes -### Per test configuration: `browser` +### 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` configuration value per test or suite. The `browser` configuration accepts the same {% urlHash "arguments" Arguments %} as `Cypress.isBrowser()`. +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' } => { @@ -169,4 +169,4 @@ it('Show warning outside Chrome', (), { browser: '!chrome' } => { - {% url "Cross Browser Testing" cross-browser-testing %} - {% url "`Cypress.browser`" browser %} - {% url "Launching Browsers" launching-browsers %} -- {% url "Per Test Configuration" configuration#Test-Declaration %} +- {% url "Test Options" configuration#Test-Options %} diff --git a/source/guides/core-concepts/writing-and-organizing-tests.md b/source/guides/core-concepts/writing-and-organizing-tests.md index 6ad15fc05c..791f909938 100644 --- a/source/guides/core-concepts/writing-and-organizing-tests.md +++ b/source/guides/core-concepts/writing-and-organizing-tests.md @@ -278,24 +278,26 @@ it.skip('returns "fizz" when number is multiple of 3', () => { }) ``` -## Test Declaration Configuration +## Test Options -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. +To apply a specific Cypress {% url "configuration" configuration %} value to a suite or test, pass an options object to the test or suite function as the second argument. + +These options will take effect during the suite or tests where they are set then return to their previous default values after the suite or tests are complete. ### Syntax ```javascript -describe(name, configuration, fn) -context(name, configuration, fn) -it(name, configuration, fn) -specify(name, configuration, fn) +describe(name, options, fn) +context(name, options, fn) +it(name, options, fn) +specify(name, options, fn) ``` ### Whitelisted config values -{% partial per_test_config_whitelist %} +{% partial test_options_config_whitelist %} -### Configure suite of tests configuration +### Suite of test options ```js describe('page display on medium size screen', { @@ -312,7 +314,7 @@ describe('page display on medium size screen', { }) ``` -### Configure single test configuration +### Single test options ```js it('open product view', (), { waitForAnimations: false } => { diff --git a/source/guides/guides/cross-browser-testing.md b/source/guides/guides/cross-browser-testing.md index 796e765829..8bfa541659 100644 --- a/source/guides/guides/cross-browser-testing.md +++ b/source/guides/guides/cross-browser-testing.md @@ -188,7 +188,7 @@ There may be instances where it can be useful to run or ignore one or more tests When considering to ignore or only run a particular test within a given browser, assess the true need for the test to run on multiple browsers. {% endnote %} -You can specify a browser to run or exclude the test within by passing a configuration option to the test or suite. The `browser` configuration accepts the same arguments as {% url "`Cypress.isBrowser()`" isbrowser#Arguments %}. +You can specify a browser to run or exclude by passing a matcher to the suite or test within the {% url "test options" configuration#Test-Options %}. The `browser` option accepts the same arguments as {% url "`Cypress.isBrowser()`" isbrowser#Arguments %}. ```js // Run the test if Cypress is run via Firefox @@ -218,4 +218,4 @@ it('Show warning outside Chrome', (), { browser: '!chrome' } => { - {% url "`Cypress.browser`" browser %} - {% url "`Cypress.isBrowser`" isbrowser %} - {% url "Launching Browsers" launching-browsers %} -- {% url "Per Test Configuration" configuration#Test-Declaration %} +- {% url "Test Options" configuration#Test-Options %} diff --git a/source/guides/references/configuration.md b/source/guides/references/configuration.md index 4a606e3cad..0d5b32d4eb 100644 --- a/source/guides/references/configuration.md +++ b/source/guides/references/configuration.md @@ -209,13 +209,15 @@ Cypress.config('pageLoadTimeout', 100000) Cypress.config('pageLoadTimeout') // => 100000 ``` -## Test Declaration +## Test Options -To apply a specific Cypress {% url "configuration" configuration %} value to a suite or test, pass a configuration object to the function. +To apply a specific Cypress {% url "configuration" configuration %} value to a suite or test, pass an options object to the test or suite function. -{% partial per_test_config_whitelist %} +These options will take effect during the suite or tests where they are set then return to their previous default values after the suite or tests are complete. -### Configure suite of tests configuration +{% partial test_options_config_whitelist %} + +### Suite of test options ```js describe('page display on medium size screen', { @@ -232,7 +234,7 @@ describe('page display on medium size screen', { }) ``` -### Configure single test configuration +### Single test options ```js it('open product view', (), { waitForAnimations: false } => { From 7c5c4eddad336053b2e11edd6646bd0e481b1cdf Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Thu, 30 Apr 2020 16:01:49 +0630 Subject: [PATCH 13/15] Add test options to more places, including example of how to set env --- source/api/cypress-api/config.md | 9 +++ source/guides/guides/environment-variables.md | 72 ++++++++++++++++++- source/guides/references/configuration.md | 4 ++ 3 files changed, 83 insertions(+), 2 deletions(-) diff --git a/source/api/cypress-api/config.md b/source/api/cypress-api/config.md index 3ebc285660..851849f81d 100644 --- a/source/api/cypress-api/config.md +++ b/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 %} diff --git a/source/guides/guides/environment-variables.md b/source/guides/guides/environment-variables.md index 802c2fa690..1298eadf5f 100644 --- a/source/guides/guides/environment-variables.md +++ b/source/guides/guides/environment-variables.md @@ -48,6 +48,7 @@ There are 5 different ways to set environment variables. Each has a slightly dif - {% urlHash "Export as `CYPRESS_*`" Option-3-CYPRESS %} - {% urlHash "Pass in the CLI as `--env`" Option-4-env %} - {% urlHash "Set an environment variable within your plugins." Option-5-Plugins %} +- {% urlHash "Set an environment variable within test options." Option-6-Test-Options %} Don't feel obligated to pick just one method. It is common to use one strategy for local development but another when running in {% url 'CI' continuous-integration %}. @@ -205,10 +206,74 @@ Cypress.env('api_server') // 'http://localhost:8888/api/v1/' Instead of setting environment variables in a file, you can use plugins to dynamically set them with Node code. This enables you to do things like use `fs` and read off configuration values and dynamically change them. -While this may take a bit more work than other options - it yields you the most amount of flexibility and the ability to manage configuration however you'd like. - {% url "We've fully documented how to do this here." configuration-api %} +### Overview + +{% note success Benefits %} +- Most amount of flexibility +- Ability to manage configuration however you'd like +{% endnote %} + +{% note danger Downsides %} +- Requires knowledge of writing in Node +- More challenging +{% endnote %} + +## Option #6: Test Options + +You can set environment variables for specific suites or tests by passing the `env` values to the {% url "test options" configuration#Test-Options %}. + +### Suite of test options + +```js +// change environment variable for single suite of tests +describe('test against Spanish site', { + env: { + language: 'es' + } +}, () => { + it('displays Spanish', () => { + cy.visit(`https://docs.cypress.io/${Cypress.env('language')}/`) + cy.contains('¿Por qué Cypress?') + }) +}) +``` + +### Single test options + +```js +// change environment variable for single test +it('smoke test develop api', (), { + env: { + api: 'https://dev.myapi.com' + } +} => { + cy.request(Cypress.env('api')).its('status').should('eq', 200) +}) + +// change environment variable for single test +it('smoke test staging api', (), { + env: { + api: 'https://staging.myapi.com' + } +} => { + cy.request(Cypress.env('api')).its('status').should('eq', 200) +}) +``` + +### Overview + +{% note success Benefits %} +- Only takes effect for duration of suite or test. +- More clear where environment variables come from. +- Allows for dynamic values between tests +{% endnote %} + +{% note danger Downsides %} +- Environment value can be set from multiple tests requiring maintenance +{% endnote %} + # Overriding Configuration If your environment variables match a standard configuration key, then instead of setting an `environment variable` they will instead override the configuration value. @@ -229,4 +294,7 @@ You can {% url 'read more about how environment variables can change configurati ## See also +- {% url "`Cypress.env()`" env %} +- {% url "Configuration API" configuration-api %} - {% url "Environment Variables recipe" recipes#Server-Communication %} +- {% url "Test Options" configuration#Test-Options %} diff --git a/source/guides/references/configuration.md b/source/guides/references/configuration.md index 0d5b32d4eb..c380953fb6 100644 --- a/source/guides/references/configuration.md +++ b/source/guides/references/configuration.md @@ -396,3 +396,7 @@ IntelliSense is available for Cypress while editing your configuration file. {% {% history %} {% url "3.5.0" changelog %} | Added support for option `nodeVersion` {% endhistory %} + +# See also + +- {% url "`Cypress.config()`" config %} From ad91d9ac27a77715a49ae48f3231eca206235ea8 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Thu, 30 Apr 2020 16:03:44 +0630 Subject: [PATCH 14/15] remove danger note --- source/guides/guides/environment-variables.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/source/guides/guides/environment-variables.md b/source/guides/guides/environment-variables.md index 1298eadf5f..59b4bfc513 100644 --- a/source/guides/guides/environment-variables.md +++ b/source/guides/guides/environment-variables.md @@ -270,10 +270,6 @@ it('smoke test staging api', (), { - Allows for dynamic values between tests {% endnote %} -{% note danger Downsides %} -- Environment value can be set from multiple tests requiring maintenance -{% endnote %} - # Overriding Configuration If your environment variables match a standard configuration key, then instead of setting an `environment variable` they will instead override the configuration value. From 3785bfd0b9c4000351a994215e42bb99b30b7e98 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Thu, 30 Apr 2020 16:04:26 +0630 Subject: [PATCH 15/15] add browser to whitelisted options --- source/_partial/test_options_config_whitelist.md | 1 + 1 file changed, 1 insertion(+) diff --git a/source/_partial/test_options_config_whitelist.md b/source/_partial/test_options_config_whitelist.md index cb5b7f564e..810e2f3ede 100644 --- a/source/_partial/test_options_config_whitelist.md +++ b/source/_partial/test_options_config_whitelist.md @@ -2,6 +2,7 @@ - `animationDistanceThreshold` - `baseUrl` +- `browser` - `defaultCommandTimeout` - `execTimeout` - `env`