${cmd} will continue to ${urls.retry} its specified assertions until it times out.
${assertion}.
${promise}.
` tag + +Unlike other tags, `` doesn't ignore leading, trailing, or duplicate whitespaces as shown below: + +```html + +Other tags + Hello, World ! + +Pre tag + Hello, World ! +``` + +Rendered result: + +{% imgTag /img/api/contains/contains-pre-exception.png "The result of pre tag" %} + +To reflect this behavior, Cypress also doesn't ignore them. + +```js +// test result for above code + +cy.get('p').contains('Hello, World !') // pass +cy.get('p').contains(' Hello, World !') // fail + +cy.get('pre').contains('Hello, World !') // fail +cy.get('pre').contains(' Hello, World !') // pass +``` + ## Single Element ### Only the *first* matched element will be returned @@ -362,6 +405,10 @@ When clicking on the `contains` command within the command log, the console outp {% imgTag /img/api/contains/see-elements-found-from-contains-in-console.png "console.log contains" %} +{% history %} +{% url "4.0.0" changelog#4-0-0 %} | Added support for option `matchCase`. +{% endhistory %} + # See also - {% url `cy.get()` get %} diff --git a/source/api/commands/writefile.md b/source/api/commands/writefile.md index e469b80ef2..7271eabc6f 100644 --- a/source/api/commands/writefile.md +++ b/source/api/commands/writefile.md @@ -73,11 +73,10 @@ To use encoding with other options, have your options object be your third param If the path to the file does not exist, the file and its path will be created. If the file already exists, it will be over-written. ```javascript -cy - .writeFile('path/to/message.txt', 'Hello World') - .then((text) => { - expect(text).to.equal('Hello World') // true - }) +cy.writeFile('path/to/message.txt', 'Hello World') +cy.readFile('path/to/message.txt').then((text) => { + expect(text).to.equal('Hello World') // true +}) ``` `{projectRoot}/path/to/message.txt` will be created with the following contents: @@ -94,9 +93,9 @@ JavaScript arrays and objects are stringified and formatted into text. ```javascript cy.writeFile('path/to/data.json', { name: 'Eliza', email: 'eliza@example.com' }) - .then((user) => { - expect(user.name).to.equal('Eliza') - }) +cy.readFile('path/to/data.json').then((user) => { + expect(user.name).to.equal('Eliza') // true +}) ``` `{projectRoot}/path/to/data.json` will be created with the following contents: @@ -180,6 +179,7 @@ When clicking on the `writeFile` command within the command log, the console out {% imgTag /img/api/writefile/console-log-shows-contents-written-to-file.png "Console Log writeFile" %} {% history %} +{% url "4.0.0" changelog#4-0-0 %} | `cy.writeFile()` now yields `null` instead of `contents` {% url "3.1.1" changelog#3-1-1 %} | Added `flag` option and appending with `a+` {% url "1.0.0" changelog#1.0.0 %} | `cy.writeFile()` command added {% endhistory %} diff --git a/source/api/cypress-api/browser.md b/source/api/cypress-api/browser.md index 0f4cdde617..18ac3253d5 100644 --- a/source/api/cypress-api/browser.md +++ b/source/api/cypress-api/browser.md @@ -10,6 +10,21 @@ title: Cypress.browser Cypress.browser // returns browser object ``` +The object has the following properties: + +Property | Type | Description +--- | --- | --- +`channel` | `string` | Release channel of the browser, such as `stable`, `dev`, or `canary`. +`displayName` | `string` | Human-readable display name for the browser. +`family` | `string` | Rendering engine being used. `chromium` or `firefox`. +`isChosen` | `boolean` | Whether the browser is selected in the browser selector of the Test Runner. +`majorVersion` | `number` | The major version number of the browser. +`name`| `string` | Machine-friendly name, like `chrome`, `electron`, or `firefox`. +`path` | `string` | Path to the browser on disk. Blank for Electron. +`version` | `string` | Full version. +`isHeadless` | `boolean` | Whether the browser is running headlessly. +`isHeaded` | `boolean` | Whether the browser displays headed. + # Examples ## Log browser information @@ -20,11 +35,14 @@ Cypress.browser // returns browser object it('log browser info', function() { console.log(Cypress.browser) // { - // name: 'chrome', + // channel: 'stable', // displayName: 'Chrome', - // version: '67.123.456.90', - // majorVersion: '67', - // path: '/path/to/browser', + // family: 'chromium', + // isChosen: true, + // majorVersion: 80, + // name: 'chrome', + // path: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', + // version: '80.0.3987.87', // isHeaded: true, // isHeadless: false // } @@ -78,6 +96,7 @@ cy.screenshot() # See also -- {% url "Launching Browsers" launching-browsers %} - {% url "Browser Launch API" browser-launch-api %} - +- {% url "Cross Browser Testing" cross-browser-testing %} +- {% url "`Cypress.isBrowser`" isbrowser %} +- {% url "Launching Browsers" launching-browsers %} diff --git a/source/api/cypress-api/isbrowser.md b/source/api/cypress-api/isbrowser.md new file mode 100644 index 0000000000..4e3948b0a3 --- /dev/null +++ b/source/api/cypress-api/isbrowser.md @@ -0,0 +1,99 @@ +--- +title: Cypress.isBrowser +--- + +`Cypress.isBrowser` checks if the current browser matches the given name or filter. + +# Syntax + +```javascript +Cypress.isBrowser(name) +Cypress.isBrowser(filter) +``` + +## Arguments + +**{% fa fa-angle-right %} name** ***(String)*** + +The name of the browser (case-insensitive). + +**{% fa fa-angle-right %} filter** ***(Object)*** + +Filter 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 +--- | --- | --- +`name`| `string` | Machine-friendly name, like `chrome`, `electron`, or `firefox`. +`family` | `string` | Rendering engine being used. `chromium` or `firefox`. +`channel` | `string` | Release channel of the browser, such as `stable`, `dev`, or `canary`. +`displayName` | `string` | Human-readable display name for the browser. +`version` | `string` | Full version. +`path` | `string` | Path to the browser on disk. Blank for Electron. +`majorVersion` | `number` | The major version number of the browser. +`isHeadless` | `boolean` | Whether the browser is running headlessly. +`isHeaded` | `boolean` | Whether the browser displays headed. + +# Examples + +## Name + +### Only run tests in Chrome + +```javascript +// true when running in Chrome +if (Cypress.isBrowser('chrome')) { + it('only runs in chrome', function () { + // test some (hypothetical) issue with chrome + }) +} +``` + +### Skip a test in Firefox + +```javascript +it('a test', function() { + // true when running in Firefox + if (Cypress.isBrowser('firefox')) { + this.skip() + } +}) +``` + +## Filter + +### Only run commands in Chromium-based browser + +```javascript +it('has correct Chromium-based specific css property', function () { + // 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') + } +}) +``` + +### 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', function () { + // test some (hypothetical) issue with chrome + }) +} +``` + +{% history %} +{% url "4.0.0" changelog#4-0-0 %} | Added `isBrowser` command. +{% endhistory %} + +# See also + +- {% url "Browser Launch API" browser-launch-api %} +- {% url "Cross Browser Testing" cross-browser-testing %} +- {% url "`Cypress.browser`" browser %} +- {% url "Launching Browsers" launching-browsers %} diff --git a/source/api/cypress-api/iscy.md b/source/api/cypress-api/iscy.md index ca99414600..7b16255c63 100644 --- a/source/api/cypress-api/iscy.md +++ b/source/api/cypress-api/iscy.md @@ -14,7 +14,7 @@ Cypress.isCy(obj) ## Arguments -**{% fa fa-angle-right %} obj** ***(any)*** +**{% fa fa-angle-right %} obj** ***(Object)*** The object to test. diff --git a/source/api/plugins/browser-launch-api.md b/source/api/plugins/browser-launch-api.md index 5aab1e7ef0..c76ffb0c9c 100644 --- a/source/api/plugins/browser-launch-api.md +++ b/source/api/plugins/browser-launch-api.md @@ -2,55 +2,119 @@ title: Browser Launch API --- -Before Cypress launches a browser, it gives you the ability to modify the arguments used to launch it. +Before Cypress launches a browser, it gives you the opportunity to modify the browser preferences, install extensions, add and remove command-line arguments, and modify other options. -This is helpful to modify, remove, or add your own arguments. +# Syntax -The most common use case is adding your own web extension - [example recipe](https://www.cypress.io/blog/2020/01/07/how-to-load-the-react-devtools-extension-in-cypress/). +```js +on('before:browser:launch', (browser = {}, launchOptions) => { /* ... */ }) +``` + +**{% fa fa-angle-right %} browser** ***(object)*** + +An object describing the browser being launched, with the following properties: + +Property | Type | Description +--- | --- | --- +`name`| `string` | Machine-friendly name, like `chrome`, `electron`, or `firefox`. +`family` | `string` | Rendering engine being used. `chromium` or `firefox`. +`channel` | `string` | Release channel of the browser, such as `stable`, `dev`, or `canary`. +`displayName` | `string` | Human-readable display name for the browser. +`version` | `string` | Full version. +`path` | `string` | Path to the browser on disk. Blank for Electron. +`info` | `string` | *(Optional)* Extra information about the browser (used for display in the browser selector of the Test Runner) +`majorVersion` | `number` | The major version number of the browser. +`isHeadless` | `boolean` | Whether the browser is running headlessly. +`isHeaded` | `boolean` | Whether the browser displays headed. + +**{% fa fa-angle-right %} launchOptions** ***(object)*** + +Options that can be modified to control how the browser is launched, with the following properties: + +Property | Type | Description +--- | --- | --- +`preferences` | `object` | An object describing browser preferences. Differs between browsers. See {% urlHash "Changing browser preferences" Changing-browser-preferences %} for details. +`args` | `string[]` | An array of strings that will be passed as command-line args when the browser is launched. Has no effect on Electron. See {% urlHash "Modify browser launch arguments" Modify-browser-launch-arguments %} for details. +`extensions` | `string[]` | An array of paths to folders containing unpacked WebExtensions to be loaded before the browser starts. Note: Electron currently only supports Chrome DevTools extensions. See {% urlHash "Add browser extensions" Add-browser-extensions %} for details. # Usage -## Modify args based on browser +## Modify browser launch arguments, preferences, and extensions -Using your {% url "`pluginsFile`" plugins-guide %} you can tap into the `before:browser:launch` event and modify the arguments based on the browser that Cypress is launching. +Using your {% url "`pluginsFile`" plugins-guide %} you can tap into the `before:browser:launch` event and modify how Cypress launches the browser (e.g. modify arguments, user preferences, and extensions). -This event will yield you the `browser` as an object, and `args` which are the default arguments used to launch the browser. +This event will yield you the `browser` object, which gives you information about the browser, and the `launchOptions` object, which allows you to modify how the browser is launched. -`args` may be an array or an object (based on the type of browser we're launching). Whatever you return from this event will become the new args for launching the browser. +The returned `launchOptions` object will become the new launch options for the browser. -Here are options for the currently supported browsers: +### Modify browser launch arguments: -* {% url 'Chrome, Chromium, or Canary' "https://peter.sh/experiments/chromium-command-line-switches/" %} -* {% url 'Electron' "https://github.com/electron/electron/blob/master/docs/api/browser-window.md#new-browserwindowoptions" %} +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser = {}, launchOptions) => { + if (browser.family === 'chromium' && browser.name !== 'electron') { + // `args` is an array of all the arguments that will + // be passed to Chromium-based browsers when it launchers + launchOptions.args.push('--start-fullscreen') + + // whatever you return here becomes the launchOptions + return launchOptions + } + + if (browser.family === 'firefox') { + launchOptions.args.push('-some-cli-argument') + + return launchOptions + } + }) +} +``` + +### Add browser extensions: + +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser, launchOptions) => { + // supply the path to an unpacked WebExtension + // NOTE: extensions cannot be loaded in headless Chrome + launchOptions.extensions.push('/path/to/webextension') + + return launchOptions + }) +} +``` + +### Changing browser preferences: ```js module.exports = (on, config) => { - on('before:browser:launch', (browser = {}, args) => { - // browser will look something like this - // { - // name: 'chrome', - // displayName: 'Chrome', - // version: '63.0.3239.108', - // path: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', - // majorVersion: '63' - // } - - if (browser.name === 'chrome') { - // `args` is an array of all the arguments - // that will be passed to Chrome when it launchers - args.push('--start-fullscreen') - - // whatever you return here becomes the new args - return args + on('before:browser:launch', (browser, launchOptions) => { + if (browser.family === 'chromium' && browser.name !== 'electron') { + // in Chromium, preferences can exist in Local State, Preferences, or Secure Preferences + // via launchOptions.preferences, these can be acccssed as `localState`, `default`, and `secureDefault` + + // for example, to set `somePreference: true` in Preferences: + launchOptions.preferences.default.somePreference = true + + // more information about Chromium preferences can be found here: + // https://www.chromium.org/developers/design-documents/preferences + + return launchOptions + } + + if (browser.family === 'firefox') { + // launchOptions.preferences is a map of preference names to values + launchOptions.preferences['browser.startup.homepage'] = 'https://cypress.io' + + return launchOptions } if (browser.name === 'electron') { - // `args` is a `BrowserWindow` options object + // launchOptions.preferences is a `BrowserWindow` `options` object: // https://electronjs.org/docs/api/browser-window#new-browserwindowoptions - args['fullscreen'] = true + launchOptions.preferences.darkTheme = true - // whatever you return here becomes the new args - return args + return launchOptions } }) } @@ -78,7 +142,7 @@ Cypress already sets some the Electron command line switches internally. See fil ## See all Chrome browser switches -If you are running Cypress tests using Chrome browser, you can see ALL currently set command line switches and the browser version information by opening a new tab and typing `chrome://version` url. +If you are running Cypress tests using a Chromium-based browser, you can see ALL currently set command line switches and the browser version information by opening a new tab and typing `chrome://version` url. {% imgTag /img/api/chrome-switches.png "See all Chrome switches" %} @@ -94,16 +158,22 @@ You can however send your own video file for testing by passing a Chrome command ```js module.exports = (on, config) => { - on('before:browser:launch', (browser = {}, args) => { - if (browser.name === 'chrome') { + on('before:browser:launch', (browser = {}, launchOptions) => { + if (browser.family === 'chromium' && browser.name !== 'electron') { // Mac/Linux - args.push('--use-file-for-fake-video-capture=cypress/fixtures/my-video.y4m') + launchOptions.args.push('--use-file-for-fake-video-capture=cypress/fixtures/my-video.y4m') // Windows - // args.push('--use-file-for-fake-video-capture=c:\\path\\to\\video\\my-video.y4m') + // launchOptions.args.push('--use-file-for-fake-video-capture=c:\\path\\to\\video\\my-video.y4m') } - return args + return launchOptions }) } ``` + +{% history %} +{% url "4.0.0" changelog#4-0-0 %} | New `options` object replaces old `args` as second argument to `before:browser:launch` +{% url "4.0.0" changelog#4-0-0 %} | All Chromium-based browsers, including Electron, have `chromium` set as their `family` property. +{% url "4.0.0" changelog#4-0-0 %} | Added `channel` property to browser. +{% endhistory %} diff --git a/source/api/plugins/configuration-api.md b/source/api/plugins/configuration-api.md index 307bfbd2fc..cab6b1b360 100644 --- a/source/api/plugins/configuration-api.md +++ b/source/api/plugins/configuration-api.md @@ -41,7 +41,7 @@ Additionally, Cypress will respect and await promises you return. This enables y ## Customize available browsers -The configuration includes the list of browsers found on your system that are available to Cypress. +The configuration includes the list of browsers found on your system that are available to Cypress. {% note info %} Read our full guide on {% url "Launching Browsers" launching-browsers %} for more information on how this works. @@ -54,8 +54,9 @@ In the plugins file, you can filter the list of browsers passed inside the `conf module.exports = (on, config) => { // inside config.browsers array each object has information like // { - // name: 'canary', - // family: 'chrome', + // name: 'chrome', + // family: 'chromium', + // channel: 'canary', // displayName: 'Canary', // version: '80.0.3966.0', // path: @@ -63,7 +64,7 @@ module.exports = (on, config) => { // majorVersion: 80 // } return { - browsers: config.browsers.filter((b) => b.family === 'chrome') + browsers: config.browsers.filter((b) => b.family === 'chromium') } } ``` diff --git a/source/faq/questions/general-questions-faq.md b/source/faq/questions/general-questions-faq.md index 97ac30ae3d..1ba683d0c8 100644 --- a/source/faq/questions/general-questions-faq.md +++ b/source/faq/questions/general-questions-faq.md @@ -92,7 +92,7 @@ No. In fact Cypress' architecture is very different from Selenium in a few criti ## {% fa fa-angle-right %} If Cypress runs in the browser, doesn't that mean it's sandboxed? -Yes, technically; it's sandboxed and has to follow the same rules as every other browser. That's actually a good thing because it doesn't require a browser extension, and it naturally will work across all browsers (which enables cross-browser testing). +Yes, technically; it's sandboxed and has to follow the same rules as every other browser. That's actually a good thing because it doesn't require a browser extension, and it naturally will work across all browsers (which enables cross browser testing). But Cypress is actually way beyond a basic JavaScript application running in the browser. It is also a desktop application and communicates with back end web services. diff --git a/source/guides/getting-started/installing-cypress.md b/source/guides/getting-started/installing-cypress.md index ddc6764e4b..fd7c763c55 100644 --- a/source/guides/getting-started/installing-cypress.md +++ b/source/guides/getting-started/installing-cypress.md @@ -19,6 +19,10 @@ Cypress is a desktop application that is installed on your computer. The desktop - **Linux** Ubuntu 12.04 and above, Fedora 21 and Debian 8 *(64-bit only)* - **Windows** 7 and above +If using `npm` to install Cypress, we support: + +- **Node.js** 8 and above + # Installing ## {% fa fa-terminal %} `npm install` @@ -122,7 +126,7 @@ After a moment, the Cypress Test Runner will launch. The Cypress Test Runner attempts to find all compatible browsers on the user's machine. The drop down to select a different browser is in the top right corner of the Test Runner. -{% imgTag /img/guides/select-browser.png "Select a different browser" %} +{% imgTag /img/guides/browser-list-dropdown.png "Select a different browser" %} Read {% url "Launching Browsers" launching-browsers %} for more information on how Cypress controls a real browser during end-to-end tests. diff --git a/source/guides/guides/command-line.md b/source/guides/guides/command-line.md index bd48af2f32..6abcafde0d 100644 --- a/source/guides/guides/command-line.md +++ b/source/guides/guides/command-line.md @@ -69,7 +69,7 @@ npx cypress run --record --spec "cypress/integration/my-spec.js" ## `cypress run` -Runs Cypress tests to completion. By default, `cypress run` will run all tests headlessly in the `Electron` browser. +Runs Cypress tests to completion. By default, `cypress run` will run all tests headlessly in the Electron browser. ```shell cypress run [options] @@ -85,8 +85,8 @@ Option | Description `--config-file`, `-C` | {% urlHash "Specify configuration file" cypress-run-config-file-lt-config-file-gt %} `--env`, `-e` | {% urlHash "Specify environment variables" cypress-run-env-lt-env-gt %} `--group` | {% urlHash "Group recorded tests together under a single run" cypress-run-group-lt-name-gt %} -`--headed` | {% urlHash "Displays the browser instead of running headlessly (defaults to true for Chrome-family browsers)" cypress-run-headed %} -`--headless` | {% urlHash "Hide the browser instead of running headed (defaults to true for Electron)" cypress-run-headless %} +`--headed` | {% urlHash "Displays the browser instead of running headlessly (default for Firefox and Chromium-based browsers)" cypress-run-headed %} +`--headless` | {% urlHash "Hide the browser instead of running headed (default for Electron)" cypress-run-headless %} `--help`, `-h` | Output usage information `--key`, `-k` | {% urlHash "Specify your secret record key" cypress-run-record-key-lt-record-key-gt %} `--no-exit` | {% urlHash "Keep Cypress Test Runner open after tests in a spec file run" cypress-run-no-exit %} @@ -105,7 +105,9 @@ Option | Description cypress run --browser chrome ``` -The "browser" argument can be set to "chrome", "canary", "chromium", or "electron" to launch a browser detected on your system. Cypress will attempt to automatically find the installed browser for you. +The "browser" argument can be set to `chrome`, `chromium`, `edge`, `electron`, `firefox` to launch a browser detected on your system. Cypress will attempt to automatically find the installed browser for you. + +To launch non-stable browsers, add a colon and the desired release channel. For example, to launch Chrome Canary, use `chrome:canary`. You can also choose a browser by supplying a path: @@ -113,8 +115,6 @@ You can also choose a browser by supplying a path: cypress run --browser /usr/bin/chromium ``` -Currently, only browsers in the Chrome family are supported. - {% url "Having trouble with browser detection? Check out the debugging guide" debugging#Launching-browsers %} ### `cypress run --ci-build-id ` @@ -195,6 +195,10 @@ Specifying the `--ci-build-id` may also be necessary. ### `cypress run --headed` +{% note warning %} +Video recording is not currently supported in Electron with the `--headed` flag. See {% issue 1767 %} for more details. +{% endnote %} + By default, Cypress will run tests in Electron headlessly. Passing `--headed` will force Electron to be shown. This matches how you run Electron in interactive mode. @@ -205,9 +209,9 @@ cypress run --headed ### `cypress run --headless` -For backwards-compatibility reasons, when using Chrome, Cypress will run tests in headed mode by default. +Cypress will run tests in Chrome and Firefox headed by default. -Passing `--headless` will force Chrome to be hidden. +Passing `--headless` will force the browser to be hidden. ```shell cypress run --headless --browser chrome @@ -325,7 +329,7 @@ Give a run multiple tags. cypress run --record --tag "production,nightly" ``` -The Dashboard will display any tags sent with the appropriate run. +The Dashboard will display any tags sent with the appropriate run. {% imgTag /img/dashboard/dashboard-run-with-tags.png "Cypress run in the Dashboard displaying flags" %} @@ -365,7 +369,7 @@ cypress open --browser /usr/bin/chromium If found, the specified browser will be added to the list of available browsers in the Cypress Test Runner. -Currently, only browsers in the Chrome family are supported. +Currently, only browsers in the Chrome family are supported (including the new Chromium-based Microsoft Edge and Brave). {% url "Having trouble launching a browser? Check out the debugging guide" debugging#Launching-browsers %} diff --git a/source/guides/guides/continuous-integration.md b/source/guides/guides/continuous-integration.md index dac2520d56..f9600f2003 100644 --- a/source/guides/guides/continuous-integration.md +++ b/source/guides/guides/continuous-integration.md @@ -734,9 +734,9 @@ If you want colors to be disabled, you can pass the `NO_COLOR` environment varia NO_COLOR=1 cypress run ``` - # See also - {% url cypress-example-kitchensink https://github.com/cypress-io/cypress-example-kitchensink#ci-status %} is set up to run on multiple CI providers. +- {% url "Cross Browser Testing Guide" cross-browser-testing %} - {% url "Blog: Setting up Bitbucket Pipelines with proper caching of npm and Cypress" https://www.cypress.io/blog/2018/08/30/setting-up-bitbucket-pipelines-with-proper-caching-of-npm-and-cypress/ %} - {% url "Blog: Record Test Artifacts from any Docker CI" https://www.cypress.io/blog/2018/08/28/record-test-artifacts-from-any-ci/ %} diff --git a/source/guides/guides/cross-browser-testing.md b/source/guides/guides/cross-browser-testing.md new file mode 100644 index 0000000000..2549015a07 --- /dev/null +++ b/source/guides/guides/cross-browser-testing.md @@ -0,0 +1,244 @@ +--- +title: Cross Browser Testing +--- + +Cypress has the capability to run tests across multiple browsers. Currently, Cypress has support for {% url "Chrome-family browsers" launching-browsers#Chrome-Browsers %} (including Electron) and beta support for Firefox browsers. + +{% note warning 'Web Security' %} +Tests that require the {% url "`chromeWebSecurity` configuration option to be disabled" web-security#Disabling-Web-Security %} may experience issues in non-Chromium based browsers. +{% endnote %} + +{% note warning 'Firefox Garbage Collection' %} +Cypress triggers Firefox's internal garbage collection (GC) to better manage the browser's memory consumption. {% url "Learn more here" configuration#firefoxGcInterval %}. +{% endnote %} + +Excluding {% url "Electron" launching-browsers#Electron-Browser %}, any browser you want to run Cypress tests in needs to be installed on your local system or CI environment. A full list of detected browsers is displayed within the browser selection menu of the {% url "Test Runner" test-runner %}. + +{% imgTag /img/guides/cross-browser-testing/cypress-browser-selector.png "Cypress Test Runner with Firefox selected as the browser" "no-border" %} + +The desired browser can also specified via the {% url `--browser` command-line#Options %} flag when using {% url `run` command-line#cypress-run %} command to launch Cypress. For example, to run Cypress tests in Firefox: + +```shell +cypress run --browser firefox +``` + +To make launching of Cypress with a specific browser even more convenient, npm scripts can be used as a shortcut: + +```json +"scripts": { + "cy:run:chrome": "cypress run --browser chrome", + "cy:run:firefox": "cypress run --browser firefox" +} +``` + +# Continuous Integration Strategies + +When incorporating testing of multiple browsers within your QA process, you must implement a CI strategy that provides an optimal level of confidence while taking into consideration test duration and infrastructure costs. This optimal strategy will vary by the type and needs of a particular project. This guide we present several strategies to consider when crafting the strategy for your project. + +CI strategies will be demonstrated using the {% url "Circle CI Cypress Orb" https://circleci.com/orbs/registry/orb/cypress-io/cypress %} for its concise and readable configuration, but the same concepts apply for most CI providers. + +{% note info 'Docker Images for Testing' %} +The CI configuration examples within this guide use {% url "Cypress's Docker images" https://github.com/cypress-io/cypress-docker-images/tree/master/browsers %} to provision testing environments with desired versions of Node, Chrome, and Firefox. +{% endnote %} + +## Periodic Basis + +Generally, it is desired to run tests with each pushed commit, but it may not be necessary to do so for all browsers. For example, we can choose to run tests within Chrome for each commit, but only run Firefox on a periodic basis (i.e. nightly). The periodic frequency will depend on the scheduling of your project releases, so consider a test run frequency that is appropriate for the release schedule of your project. + +{% note info 'Cron Scheduling' %} +Typically CI providers allow for the scheduling of CI jobs via {% url "cron expressions" https://en.wikipedia.org/wiki/Cron %}. For example, the expression `0 0 * * *` translates to "everyday at midnight" or nightly. Helpful {% url "online utilities" https://crontab.guru/ %} are available to assist with creation and translation of cron expressions. +{% endnote %} + +The following example demonstrates a nightly CI schedule against production (`master` branch) for Firefox: + +```yaml +version: 2.1 +orbs: + cypress: cypress-io/cypress@1 +workflows: + nightly: + triggers: + - schedule: + cron: "0 0 * * *" + filters: + branches: + only: + - master + jobs: + - cypress/run: + executor: cypress/browsers-chrome73-ff68 + browser: firefox + start: npm start + wait-on: http://localhost:3000 +``` + +## Production Deployment + +For projects that exhibit consistently stable behavior across browsers, it may be better to run tests against additional browsers only before merging changes in the production deployment branch. + +The following example demonstrates only running Firefox tests when commits are merged into a specific branch (`develop` branch in this case) so any potential Firefox issues can be caught before a production release: + +```yaml +version: 2.1 +orbs: + cypress: cypress-io/cypress@1 +workflows: + test_develop: + jobs: + - filters: + branches: + only: + - develop + - cypress/run: + executor: cypress/browsers-chrome73-ff68 + browser: firefox + start: npm start + wait-on: http://localhost:3000 +``` + +## Subset of Tests + +We can choose to only run a subset of tests against a given browser. For example, we can execute only the happy or critical path related test files, or a directory of specific "smoke" test files. It is not always necessary to have both browsers always running *all* tests. + +In the example below, the Chrome `cypress/run` job runs *all* tests against Chrome and reports results to the {% url "Cypress Dashboard" https://on.cypress.io/dashboard %} using a ({% url "group" parallelization#Grouping-test-runs %}) named `chrome`. + +The Firefox `cypress/run` job runs a subset of tests, defined in the `spec` parameter, against the Firefox browser, and reports the results to the {% url "Cypress Dashboard" https://on.cypress.io/dashboard %} under the group `firefox-critical-path`. + +{% note info %} +**Note:** The `name` under each `cypress/run` job which will be shown in the Circle CI workflow UI to distinguish the jobs. +{% endnote %} + +```yaml +version: 2.1 +orbs: + cypress: cypress-io/cypress@1 +workflows: + build: + jobs: + - cypress/install + - cypress/run: + name: Chrome + requires: + - cypress/install + executor: cypress/browsers-chrome73-ff68 + start: npm start + wait-on: http://localhost:3000 + record: true + group: chrome + browser: chrome + - cypress/run: + name: Firefox + requires: + - cypress/install + executor: cypress/browsers-chrome73-ff68 + start: npm start + wait-on: http://localhost:3000 + record: true + group: firefox-critical-path + browser: firefox + spec: "cypress/integration/signup.spec.js,cypress/integration/login.spec.js" +``` + +## Parallelize per browser + +Execution of test files can be parallelized on a per {% url "group" parallelization#Grouping-test-runs %} basis, where test files can be grouped by the browser under test. This versatility enables the ability to allocate the desired amount of CI resources towards a browser to either improve test duration or to minimize CI costs. + +**You do not have to run all browsers at the same parallelization level.** In the example below, the Chrome dedicated `cypress/run` job runs *all* tests in parallel, across **4 machines**, against Chrome and reports results to the {% url "Cypress Dashboard" https://on.cypress.io/dashboard %} under the group name `chrome`. The Firefox dedicated `cypress/run` job runs a *subset* of tests in parallel, across **2 machines**, defined by the `spec` parameter, against the Firefox browser and reports results to the {% url "Cypress Dashboard" https://on.cypress.io/dashboard %} under the group named `firefox`. + +```yaml +version: 2.1 +orbs: + cypress: cypress-io/cypress@1 +workflows: + build: + jobs: + - cypress/install + - cypress/run: + name: Chrome + requires: + - cypress/install + executor: cypress/browsers-chrome73-ff68 + record: true + start: npm start + wait-on: http://localhost:3000 + parallel: true + parallelism: 4 + group: chrome + browser: chrome + - cypress/run: + name: Firefox + requires: + - cypress/install + executor: cypress/browsers-chrome73-ff68 + record: true + start: npm start + wait-on: http://localhost:3000 + parallel: true + parallelism: 2 + group: firefox + browser: firefox + spec: "cypress/integration/app.spec.js,cypress/integration/login.spec.js,cypress/integration/about.spec.js" +``` + +## 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. + +{% 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. + +```js +const runOn = (browser, fn) => { + if (Cypress.isBrowser(browser) { + fn() + } +} + +const ignoreOn = (browser, fn) => { + if (!Cypress.isBrowser(browser) { + fn() + } +} + +// Run happy path tests if Cypress is run via Firefox +runOn('firefox', () => { + describe('happy path suite', () => { + it('...') + it('...') + it('...') + }) +}) + +// Ignore test if Cypress is running via Firefox +// This test is not recorded to the Cypress Dashboard +ignoreOn('firefox', () => { + it('a test', function() { + // ... 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 +}) +``` + +# See also + +- {% url "Browser Launch API" browser-launch-api %} +- {% url "`Cypress.browser`" browser %} +- {% url "`Cypress.isBrowser`" isbrowser %} +- {% url "Launching Browsers" launching-browsers %} diff --git a/source/guides/guides/debugging.md b/source/guides/guides/debugging.md index 6a2542a844..6cfc273cdc 100644 --- a/source/guides/guides/debugging.md +++ b/source/guides/guides/debugging.md @@ -158,7 +158,9 @@ Browser Name | Expected Bundle Identifier | Expected Executable --- | --- | --- `chrome` | `com.google.Chrome` | `Contents/MacOS/Google Chrome` `chromium` | `org.chromium.Chromium` | `Contents/MacOS/Chromium` -`canary` | `com.google.Chrome.canary` | `Contents/MacOS/Google Chrome Canary` +`chrome:canary` | `com.google.Chrome.canary` | `Contents/MacOS/Google Chrome Canary` + +For the current list, see {% url 'packages/launcher' https://github.com/cypress-io/cypress/blob/develop/packages/launcher/lib/darwin/index.ts %} files. ### Linux @@ -168,7 +170,7 @@ Browser Name | Expected Binary Name(s) --- | --- `chrome` | `google-chrome`, `chrome`, or `google-chrome-stable` `chromium` | `chromium-browser` or `chromium` -`canary` | `google-chrome-canary` +`chrome:canary` | `google-chrome-canary` These binary names should work for most Linux distributions. If your distribution packages browsers under a different binary name, you can add a symlink using the expected binary name so that Cypress can detect it. @@ -186,7 +188,9 @@ Browser Name | Expected Path --- | --- `chrome` | `C:/Program Files (x86)/Google/Chrome/Application/chrome.exe` `chromium` | `C:/Program Files (x86)/Google/chrome-win32/chrome.exe` -`canary` | `%APPDATA%/../Local/Google/Chrome SxS/Application/chrome.exe` +`chrome:canary` | `%APPDATA%/../Local/Google/Chrome SxS/Application/chrome.exe` + +For the current list, see {% url 'packages/launcher' https://github.com/cypress-io/cypress/blob/develop/packages/launcher/lib/windows/index.ts %} files. To make a browser installed at a different path be auto-detected, create a symbolic link using `mklink` in the location that Cypress expects to find your browser. @@ -251,9 +255,6 @@ DEBUG=cypress:* cypress run ```shell set DEBUG=cypress:* -``` - -```shell cypress run ``` @@ -309,6 +310,31 @@ cy.now('task', 123) The `cy.now()` command is an internal command and may change in the future. {% endnote %} +## Log memory and CPU usage + +You can tell Cypress to log out a summary of the memory and CPU usage of itself and any subprocesses at a regular interval by enabling the `cypress:server:util:process_profiler` debug stream, like so: + +**On Mac or Linux:** + +```shell +DEBUG=cypress:server:util:process_profiler cypress run +``` + +**On Windows:** + +```shell +set DEBUG=cypress:server:util:process_profiler +cypress run +``` + +In the resulting output, processes are grouped by their name. + +{% imgTag /img/guides/troubleshooting-cypress-process-profiler-cli.jpg "Process printout of Cypress in CLI" %} + +By default, process information is collected and summarized is printed once every 10 seconds. You can override this interval by setting the `CYPRESS_PROCESS_PROFILER_INTERVAL` environment variable to the desired interval in milliseconds. + +You can also obtain more detailed per-process information by enabling the verbose `cypress-verbose:server:util:process_profiler` debug stream. + ## Additional information ### Write command log to the terminal diff --git a/source/guides/guides/launching-browsers.md b/source/guides/guides/launching-browsers.md index b991b54698..4c9951be90 100644 --- a/source/guides/guides/launching-browsers.md +++ b/source/guides/guides/launching-browsers.md @@ -14,11 +14,18 @@ When Cypress is initially run from the Test Runner, you can choose to run Cypres - {% url "Canary" https://www.google.com/chrome/browser/canary.html %} - {% url "Chrome" https://www.google.com/chrome/browser/desktop/index.html %} - {% url "Chromium" https://www.chromium.org/Home %} +- {% url "Edge" https://www.microsoft.com/edge %} +- {% url "Edge Beta" https://www.microsoftedgeinsider.com/download %} +- {% url "Edge Canary" https://www.microsoftedgeinsider.com/download %} +- {% url "Edge Dev" https://www.microsoftedgeinsider.com/download %} - {% url "Electron" https://electron.atom.io/ %} +- {% url "Firefox" https://www.mozilla.org/firefox/ %} (Beta support) +- {% url "Firefox Developer Edition" https://www.mozilla.org/firefox/developer/ %} (Beta support) +- {% url "Firefox Nightly" https://www.mozilla.org/firefox/nightly/ %} (Beta support) Cypress automatically detects available browsers on your OS. You can switch the browser in the Test Runner by using the drop down in the top right corner: -{% imgTag /img/guides/select-browser.png "Select a different browser" %} +{% imgTag /img/guides/browser-list-dropdown.png "Select a different browser" %} {% partial chromium_download %} @@ -42,7 +49,7 @@ Because Electron is the default browser - it is typically run in CI. If you are All Chrome* flavored browsers will be detected and are supported. -### You can launch Chrome browsers: +You can launch Chrome like this: ```shell cypress run --browser chrome @@ -61,11 +68,44 @@ cypress run --browser chromium Or Chrome Canary: ```shell -cypress run --browser canary +cypress run --browser chrome:canary +``` + +Or Microsoft Edge (Chromium-based): + +```shell +cypress run --browser edge +``` + +Or Microsoft Edge Canary (Chromium-based): + +```shell +cypress run --browser edge:canary ``` {% url 'Having issues launching installed browsers? Read more about debugging browser launching' debugging#Launching-browsers %} +## Firefox Browsers (beta) + +Firefox-family browsers have beta support. + +You can launch Firefox like this: + +```shell +cypress run --browser firefox +``` + +Or Firefox Developer/Nightly Edition: + +```shell +cypress run --browser firefox:dev +cypress run --browser firefox:nightly +``` + +To use this command in CI, you need to install these other browsers - or use one of our {% url 'docker images' docker %}. + +By default, we will launch Firefox in headed mode. To run Firefox headlessly, you can pass the `--headless` argument to `cypress run`. + ## Launching by a path You can launch any supported browser by specifying a path to the binary: @@ -93,8 +133,9 @@ In the plugins file, you can filter the list of browsers passed inside the `conf module.exports = (on, config) => { // inside config.browsers array each object has information like // { - // name: 'canary', - // family: 'chrome', + // name: 'chrome', + // channel: 'canary', + // family: 'chromium', // displayName: 'Canary', // version: '80.0.3966.0', // path: @@ -102,7 +143,7 @@ module.exports = (on, config) => { // majorVersion: 80 // } return { - browsers: config.browsers.filter((b) => b.family === 'chrome') + browsers: config.browsers.filter((b) => b.family === 'chromium') } } ``` @@ -115,7 +156,7 @@ When you open the Test Runner in a project that uses the above modifications to If you return an empty list of browsers or `browsers: null`, the default list will be restored automatically. {% endnote %} -If you have installed a Chromium-based browser like {% url Brave https://brave.com/ %}, {% url Vivaldi https://vivaldi.com/ %} and even the new {% url "Microsoft Edge Beta" https://www.microsoftedgeinsider.com/en-us/ %} you can add them to the list of returned browsers. Here is a plugins file that inserts a local Brave browser into the returned list. +If you have installed a Chromium-based browser like {% url Brave https://brave.com/ %}, {% url Vivaldi https://vivaldi.com/ %} you can add them to the list of returned browsers. Here is a plugins file that inserts a local Brave browser into the returned list. ```javascript // cypress/plugins/index.js @@ -134,7 +175,8 @@ const findBrowser = () => { return { name: 'Brave', - family: 'chrome', + channel: 'stable', + family: 'chromium', displayName: 'Brave', version, path: browserPath, @@ -154,7 +196,7 @@ module.exports = (on, config) => { {% imgTag /img/guides/plugins/brave-browser.png "List of browsers includes Brave browser" %} -Once selected, the Brave browser is detected using the same approach as any other browser of the `chrome` family. +Once selected, the Brave browser is detected using the same approach as any other browser of the `chromium` family. {% imgTag /img/guides/plugins/brave-running-tests.png "Brave browser executing end-to-end tests" %} @@ -162,7 +204,7 @@ If you modify the list of browsers, you can see the {% url "resolved configurati ## Unsupported Browsers -Many browsers such as Firefox, Safari, and Internet Explorer are not currently supported. While it may be possible to modify the list of browsers found and run Cypress within them - we do not guarantee full functionality. Support for more browsers is on our roadmap. You can read an exhaustive explanation about our future cross browser testing strategy {% issue 310 'here' %}. +Many browsers such as Safari and Internet Explorer are not currently supported. Support for more browsers is on our roadmap. You can read an explanation about our future cross browser roadmap {% issue 310 'here' %}. # Browser Environment @@ -174,8 +216,8 @@ When Cypress goes to launch your browser it will give you an opportunity to modi This enables you to do things like: -- Load your own chrome extension -- Enable or disable experimental chrome features +- Load your own extension +- Enable or disable experimental features {% url 'This part of the API is documented here.' browser-launch-api %} @@ -210,16 +252,16 @@ You can see all of the default chrome command line switches we send {% url "here # Browser Icon -You might notice that if you already have the browser open you will see two of the same browser icons in your Dock. +You might notice that if you already have the browser open you will see two of the same browser icons in your dock. {% video local /img/snippets/switching-between-cypress-and-other-chrome-browser.mp4 %} We understand that when Cypress is running in its own profile it can be difficult to tell the difference between your normal browser and Cypress. -For this reason we recommend {% url "downloading Chromium" https://www.chromium.org/Home %} or {% url "downloading Canary" https://www.google.com/chrome/browser/canary.html %}. These browsers both have different icons from the standard Chrome browser, making them more distinguishable. You can also use the bundled {% urlHash "Electron browser" Electron-Browser %}, which does not have a Dock icon. +For this reason you may find downloading and using a browser's release channel versions (Dev, Canary, etc) useful. These browsers have different icons from the standard stable browser, making them more distinguishable. You can also use the bundled {% urlHash "Electron browser" Electron-Browser %}, which does not have a dock icon. {% video local /img/snippets/switching-cypress-browser-and-canary-browser.mp4 %} -Additionally, we've made the browsers spawned by Cypress look different than regular sessions. You'll see a darker theme around the chrome of the browser. You'll always be able to visually distinguish these. +Additionally, in Chrome-based browsers, we've made the browser spawned by Cypress look different than regular sessions. You'll see a darker theme around the chrome of the browser. You'll always be able to visually distinguish these. {% imgTag /img/guides/cypress-browser-chrome.png "Cypress Browser with darker chrome" %} diff --git a/source/guides/guides/module-api.md b/source/guides/guides/module-api.md index 236f9006c9..e5e65f0650 100644 --- a/source/guides/guides/module-api.md +++ b/source/guides/guides/module-api.md @@ -24,8 +24,8 @@ Option | Type | Description `configFile` | *string / boolean* | Path to the config file to be used. If `false` is passed, no config file will be used. `env` | *object* | Specify {% url "environment variables" environment-variables %} `group` | *string* | {% url "Group" parallelization#Grouping-test-runs %} recorded tests together under a single run -`headed` | *boolean* | Displays the browser instead of running headlessly (defaults to true for Chrome-family browsers) -`headless` | *boolean* | Hide the browser instead of running headed (defaults to true for Electron) +`headed` | *boolean* | Displays the browser instead of running headlessly (default Firefox and Chromium-based browsers) +`headless` | *boolean* | Hide the browser instead of running headed (defaults for Electron) `key` | *string* | Specify your secret record key `exit` | *boolean* | Whether to close Cypress after all tests run `parallel` | *boolean* | Run recorded specs in {% url "parallel" parallelization %} across multiple machines @@ -45,7 +45,6 @@ cypress.run({ browser: 'chrome', config: { baseUrl: 'http://localhost:8080', - chromeWebSecurity: false, video: true, }, env: { diff --git a/source/guides/guides/parallelization.md b/source/guides/guides/parallelization.md index 3c208bfde3..6e57fd4518 100644 --- a/source/guides/guides/parallelization.md +++ b/source/guides/guides/parallelization.md @@ -19,7 +19,7 @@ If your project has a large number of tests, it can take a long time for tests t Cypress can run recorded tests in parallel across multiple machines since version {% url "3.1.0" changelog#3-1-0 %}. While parallel tests can also technically run on a single machine, we do not recommend it since this machine would require significant resources to run your tests efficiently. -This guide assumes you already have your project running and {% url "recording" projects#Setup %} within Continuous Integration. If you have not set up your project yet, check out our {% url "Continuous Integration guide" continuous-integration %}. +This guide assumes you already have your project running and {% url "recording" projects#Setup %} within Continuous Integration. If you have not set up your project yet, check out our {% url "Continuous Integration guide" continuous-integration %}. If you are running or planning to run tests across multiple browsers (Firefox, Chrome, or Edge), we also recommend checking out our {% url "Cross Browser Testing guide" cross-browser-testing %} for helpful CI strategies when using parallelization. {% imgTag /img/guides/parallelization/parallelization-diagram.png "Parallelization Diagram" "no-border" %} @@ -147,6 +147,13 @@ For multiple runs to be grouped into a single run, it is required for CI machine {% imgTag /img/guides/parallelization/machines-view-grouping-expanded.png "Machines view grouping expanded" "no-border" %} +{% note info %} +# Cross Browser Testing + +Grouping test runs with or without parallelization is a useful mechanism when implementing a CI strategy for cross browser testing. Check out the {% url "Cross Browser Testing guide" cross-browser-testing %} to learn more. + +{% endnote %} + ## Grouping by browser You can test your application against different browsers and view the results under a single run within the Dashboard. Below, we name our groups the same name as the browser being tested: @@ -287,6 +294,8 @@ The Machines View charts spec files by the machines that executed them. This vie # See also +- {% url "Continuous Integration Guide" continuous-integration %} +- {% url "Cross Browser Testing Guide" cross-browser-testing %} - {% url "Blog: Run Your End-to-end Tests 10 Times Faster with Automatic Test Parallelization" https://www.cypress.io/blog/2018/09/05/run-end-to-end-tests-on-ci-faster/ %} - {% url "Blog: Run and group tests the way you want to" https://glebbahmutov.com/blog/run-and-group-tests/ %} - {% url "CI Configurations in Kitchen Sink Example" https://github.com/cypress-io/cypress-example-kitchensink#ci-status %} diff --git a/source/guides/guides/screenshots-and-videos.md b/source/guides/guides/screenshots-and-videos.md index b380faf4d6..c931b46900 100644 --- a/source/guides/guides/screenshots-and-videos.md +++ b/source/guides/guides/screenshots-and-videos.md @@ -27,7 +27,11 @@ Cypress clears any existing screenshots before `cypress run`. If you do not want # Videos -Cypress also records videos when running tests. +{% note warning %} +Video recording is not currently supported in Electron with the {% url "`--headed` flag" command-line#cypress-run-headed %}. See {% issue 1767 %} for more details. +{% endnote %} + +Cypress records a video for each spec file when running tests. Video recording can be turned off entirely by setting {% url `video` configuration#Videos %} to `false` from within your configuration. diff --git a/source/guides/guides/web-security.md b/source/guides/guides/web-security.md index 51def0f2eb..7a04a8bf85 100644 --- a/source/guides/guides/web-security.md +++ b/source/guides/guides/web-security.md @@ -260,9 +260,17 @@ So if you cannot work around any of the issues using the suggested workarounds a One last thing to consider here is that every once in a while we discover bugs in Cypress that lead to cross-origin errors that can otherwise be fixed. If you think you're experiencing a bug, {% open_an_issue 'open an issue' %}. -To start, you will need to understand that *not all browsers expose a way to turn off web security*. Some do, some don't. If you rely on disabling web security, you will not be able to run tests on browsers that do not support this feature. +{% note warning 'Chrome only' %} +Disabling web security is only supported in Chrome-based browsers. Settings in `chromeWebSecurity` will have no effect in other browsers. We will log a warning in this case. -## Setting `chromeWebSecurity` to `false` allows you to do the following: +{% imgTag /img/guides/chrome-web-security-stdout-warning.jpg 'chromeWebSecurity warning in stdout'%} + +If you rely on disabling web security, you will not be able to run tests on browsers that do not support this feature. +{% endnote %} + +## Set `chromeWebSecurity` to `false` + +Setting `chromeWebSecurity` to `false` in Chrome-based browsers allows you to do the following: - Display insecure content - Navigate to any superdomain without cross-origin errors @@ -272,7 +280,7 @@ One thing you may notice though is that Cypress still enforces visiting a single Still here? That's cool, let's disable web security! -### Set `chromeWebSecurity` to `false` in your {% url "configuration file (`cypress.json` by default)" configuration %}` and we'll take care of the rest +### Set `chromeWebSecurity` to `false` in your {% url "configuration file (`cypress.json` by default)" configuration %}` ```json { diff --git a/source/guides/references/assertions.md b/source/guides/references/assertions.md index acebdae621..cabe0f80e2 100644 --- a/source/guides/references/assertions.md +++ b/source/guides/references/assertions.md @@ -110,6 +110,7 @@ These assertions are available for TDD assertions (`assert`). You can see the en | .isNotString(*value*, *[message]*) | `assert.isNotString(2, 'val not string')` | | .isNumber(*value*, *[message]*) | `assert.isNumber(2, 'val is number')` | | .isNotNumber(*value*, *[message]*) | `assert.isNotNumber('e2e', 'val not number')` | +| .isFinite(*value*, *[message]*) | `assert.isFinite('e2e', 'val is finite')` | | .isBoolean(*value*, *[message]*) | `assert.isBoolean(true, 'val is bool')` | | .isNotBoolean(*value*, *[message]*) | `assert.isNotBoolean('true', 'val not bool')` | | .typeOf(*value*, *name*, *[message]*) | `assert.typeOf('e2e', 'string', 'val is string')` | diff --git a/source/guides/references/configuration.md b/source/guides/references/configuration.md index f1ef4aed44..a79cd4ec7f 100644 --- a/source/guides/references/configuration.md +++ b/source/guides/references/configuration.md @@ -76,10 +76,11 @@ Option | Default | Description Option | Default | Description ----- | ---- | ---- -`chromeWebSecurity` | `true` | Whether Chrome Web Security for same-origin policy and insecure mixed content is enabled. {% url 'Read more about this here' web-security %} -`userAgent` | `null` | Enables you to override the default user agent the browser sends in all request headers. User agent values are typically used by servers to help identify the operating system, browser, and browser version. See {% url "User-Agent MDN Documentation" https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent %} for example user agent values. +`chromeWebSecurity` | `true` | Whether to enable Chromium-based browser's Web Security for same-origin policy and insecure mixed content. {% url 'Read more about Web Security' web-security %}. `blacklistHosts` | `null` | A String or Array of hosts that you wish to block traffic for. {% urlHash 'Please read the notes for examples on using this.' blacklistHosts %} +`firefoxGcInterval` | `{ "runMode": 1, "openMode": null }` | Controls whether Cypress forces Firefox to run garbage collection (GC) cleanup and how frequently. During {% url "`cypress run`" command-line#cypress-run %}, the default value is `1`. During {% url "`cypress open`" command-line#cypress-open %}, the default value is `null`. See full details {% urlHash "here" firefoxGcInterval %}. `modifyObstructiveCode` | `true` | Whether Cypress will search for and replace obstructive JS code in `.js` or `.html` files. {% urlHash 'Please read the notes for more information on this setting.' modifyObstructiveCode %} +`userAgent` | `null` | Enables you to override the default user agent the browser sends in all request headers. User agent values are typically used by servers to help identify the operating system, browser, and browser version. See {% url "User-Agent MDN Documentation" https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent %} for example user agent values. ## Viewport @@ -259,6 +260,72 @@ Cypress modifies these scripts at the network level, and therefore there is a ti You can turn this option off if the application or site you're testing **does not** implement these security measures. Additionally it's possible that the patterns we search for may accidentally rewrite valid JS code. If that's the case, please disable this option. +## firefoxGcInterval + +Firefox has a {% url "known bug" https://bugzilla.mozilla.org/show_bug.cgi?id=1608501 %} where it does not run its internal garbage collection (GC) fast enough, which can lead to consuming all available system memory and crashing. You can progress on this issue {% issue 6187 'here' %}. + +Cypress prevents Firefox from crashing by forcing Firefox to run its GC cleanup routines between tests. + +Running GC is an expensive and **blocking** routine. It adds significant time to the overall run, and causes Firefox to "freeze" for the duration of GC cleanup. This causes the browser not to respond to any user input. + +Cypress runs GC cleanup during {% url "`cypress run`" command-line#cypress-run %} only because we don't expect users to interact with the browser - since this is typically run in CI. We've disabled running GC during {% url "`cypress open`" command-line#cypress-open %} because users typically interact with the browser. + +Because GC adds additional time to the overall run, we've added the amount of time this routine has taken to the bottom of the Command Log in the Test Runner. + +{% imgTag /img/guides/firefox-gc-interval-in-command-log.jpg %} + +### Configuration + +You can control how often GC cleanup runs via the `firefoxGcInterval` configuration value. + +`firefoxGcInterval` controls whether Cypress forces Firefox to run GC cleanup and how frequently. + +By default, we force GC cleanup between every test during {% url "`cypress run`" command-line#cypress-run %}, but do not run any GC cleanup during {% url "`cypress open`" command-line#cypress-open %} using the configuration value below: + +```json +{ + "firefoxGcInterval": { + "runMode": 1, + "openMode": null + } +} +``` + +You can override how often Cypress runs GC cleanup by setting the `firefoxGcInterval` config value to: + +- `null`, to disable it for both {% url "`cypress run`" command-line#cypress-run %} and {% url "`cypress open`" command-line#cypress-open %} +- a `number`, which sets the interval for both {% url "`cypress run`" command-line#cypress-run %} and {% url "`cypress open`" command-line#cypress-open %} +- an `object` to set different intervals for each mode + +**Examples** + +Turn off GC cleanup all modes + +```json +{ + "firefoxGcInterval": null +} +``` + +Run GC cleanup before every other test during {% url "`cypress run`" command-line#cypress-run %} and {% url "`cypress open`" command-line#cypress-open %} + +```json +{ + "firefoxGcInterval": 2 +} +``` + +Run GC cleanup before every 3rd test during {% url "`cypress run`" command-line#cypress-run %} and disable running GC cleanup during {% url "`cypress open`" command-line#cypress-open %}. + +```json +{ + "firefoxGcInterval": { + "runMode": 3, + "openMode": null + } +} +``` + ## Intelligent Code Completion IntelliSense is available for Cypress while editing your configuration file. {% url "Learn how to set up Intelligent Code Completion." intelligent-code-completion %} diff --git a/source/guides/references/error-messages.md b/source/guides/references/error-messages.md index ce59d7e423..7c5c99f4b3 100644 --- a/source/guides/references/error-messages.md +++ b/source/guides/references/error-messages.md @@ -353,6 +353,10 @@ While this works in practice, it's often indicative of an anti-pattern. You almo `cy` commands themselves are already promise like, and you can likely avoid the use of the separate Promise. +## {% fa fa-exclamation-triangle red %} Cypress detected that you returned a promise in a test, but also invoked a done callback. + +The version of Mocha was upgraded with Cypress 4.0. Mocha 3+ no longer allows returning a promise and invoking a done callback. Read more about it in the {% url "4.0 migration guide" migration-guide#Mocha-upgrade %}. + ## {% fa fa-exclamation-triangle red %} Passing `cy.route({stub: false})` or `cy.server({stub: false})` is now deprecated. You can safely remove: `{stub: false}`. @@ -513,7 +517,7 @@ When your application navigates to a superdomain outside of the current origin-p 2. You are testing a page that uses Single sign-on (SSO). In this case your web server is likely redirecting you between superdomains, so you receive this error message. You can likely get around this redirect problem by using {% url `cy.request()` request %} to manually handle the session yourself. -If you find yourself stuck and can't work around these issues you can set this in your {% url "configuration file (`cypress.json` by default)" configuration %}. But before doing so you should really understand and {% url 'read about the reasoning here' web-security %}. +If you find yourself stuck and can't work around these issues you can set `chromeWebSecurity` to `false` in your {% url "configuration file (`cypress.json` by default)" configuration %} when running in Chrome family browsers (this setting will not work in other browsers). Before doing so you should really understand and {% url 'read about the reasoning here' web-security %}. ```json { diff --git a/source/guides/references/migration-guide.md b/source/guides/references/migration-guide.md new file mode 100644 index 0000000000..5053f91d5c --- /dev/null +++ b/source/guides/references/migration-guide.md @@ -0,0 +1,377 @@ +--- +title: Migration Guide +--- + +# Migrating to Cypress 4.0 + +This guide details the changes and how to change your code to migrate to Cypress 4.0. + +## Mocha upgrade + +Mocha was upgraded from `2.5.3` to `7.0.1`, which includes a number of breaking changes and new features outlined in their {% url "changelog" https://github.com/mochajs/mocha/blob/master/CHANGELOG.md %}. Some changes you might notice are described below. + +### {% fa fa-warning red %} Breaking Change: invoke `done` callback and return a promise + +Starting with [Mocha 3.0.0](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md#300--2016-07-31), invoking a `done` callback *and* returning a promise in a test results in an error. + +This error originates from Mocha and is discussed at length [here](https://github.com/mochajs/mocha/pull/1320) and [here](https://github.com/mochajs/mocha/issues/2407). + +The reason is that using two different ways to signal that a test is finished is usually a mistake and there is always a way to only use one. There is a [proposal to handle this situation without erroring](https://github.com/mochajs/mocha/issues/2509) that may be released in a future version of Mocha. + +In the meantime, you can fix the error by choosing a single way to signal the end of your test's execution. + +#### Example #1 + +{% badge danger Before %} This test has a done callback and a promise + +```javascript +it('uses invokes done and returns promise', function (done) { + return codeUnderTest.doSomethingThatReturnsPromise().then((result) => { + // assertions here + done() + }) +}) +``` + +{% badge success After %} You can remove the `done` callback and return the promise instead: + +```javascript +it('uses invokes done and returns promise', function () { + return codeUnderTest.doSomethingThatReturnsPromise().then((result) => { + // assertions here + }) +}) +``` + +#### Example #2 + +{% badge danger Before %} Sometimes it might make more sense to use the `done` callback and not return a promise: + +```javascript +it('uses invokes done and returns promise', function (done) { + eventEmitter.on('change', () => { + // assertions + done() + }) + + return eventEmitter.doSomethingThatEmitsChange() +}) +``` + +{% badge success After %} In this case, you don't need to return the promise: + +```javascript +it('uses invokes done and returns promise', function (done) { + eventEmitter.on('change', () => { + // assertions + done() + }) + + eventEmitter.doSomethingThatEmitsChange() +}) +``` + +#### Example #3 + +Test functions using `async/await` automatically return a promise, so they need to be refactored to not use a `done` callback. + +{% badge danger Before %} This will cause an overspecified error. + +```javascript +it('uses async/await', async function (done) { + const eventEmitter = await getEventEmitter() + eventEmitter.on('change', () => done()) + eventEmitter.doSomethingThatEmitsChange() +}) +``` + +{% badge success After %} Update to the test code below. + +```javascript +it('uses async/await', async function () { + const eventEmitter = await getEventEmitter() + return new Promise((resolve) => { + eventEmitter.on('change', () => resolve()) + eventEmitter.doSomethingThatEmitsChange() + }) +}) +``` + +## Chai upgrade + +Chai was upgraded from `3.5.0` to `4.2.0`, which includes a number of breaking changes and new features outlined in {% url "Chai's migration guide" https://github.com/chaijs/chai/issues/781 %}. Some changes you might notice are described below. + +### {% fa fa-warning red %} Breaking Change: assertions expecting numbers + +Some assertions will now throw an error if the assertion's target or arguments are not numbers, including `within`, `above`, `least`, `below`, `most`, `increase` and `decrease`. + +```javascript +// These will now throw errors: +expect(null).to.be.within(0, 1) +expect(null).to.be.above(10) +// This will not throw errors: +expect('string').to.have.a.length.of.at.least(3) +``` + +### {% fa fa-warning red %} Breaking Change: `empty` assertions + +The `.empty` assertion will now throw when it is passed non-string primitives and functions. + +```javascript +// These will now throw TypeErrors +expect(Symbol()).to.be.empty +expect(function() {}).to.be.empty +``` + +### {% fa fa-warning red %} Breaking Change: non-existent properties + +An error will throw when a non-existent property is read. If there are typos in property assertions, they will now appear as failures. + +```javascript +// Would pass in Cypress 3 but will fail correctly in 4 +expect(true).to.be.ture +``` + +## Sinon.JS upgrade + +Sinon.JS was upgraded from `3.2.0` to `8.1.1`, which includes a number of breaking changes and new features outlined in {% url "Sinon.JS's migration guide" https://sinonjs.org/releases/latest/#migration-guides %}. Some changes you might notice are described below. + +### {% fa fa-warning red %} Breaking Change: stub non-existent properties + +An error will throw when trying to stub a non-existent property. + +```javascript +// Would pass in Cypress 3 but will fail in 4 +cy.stub(obj, 'nonExistingProperty') +``` + +### {% fa fa-warning red %} Breaking Change: `reset()` replaced by `resetHistory()` + +For spies and stubs, the `reset()` method was replaced by `resetHistory()`. + +{% badge danger Before %} Spies and stubs using `reset()`. + +```javascript +const spy = cy.spy() +const stub = cy.stub() + +spy.reset() +stub.reset() +``` + +{% badge success After %} Update spies and stubs should now use `resetHistory()`. + +```javascript +const spy = cy.spy() +const stub = cy.stub() + +spy.resetHistory() +stub.resetHistory() +``` + +## Plugin Event `before:browser:launch` + +Since we now support more advanced browser launch options, during `before:browser:launch` we no longer yield the second argument as an array of browser arguments and instead yield a `launchOptions` object with an `args` property. + +You can see more examples of the new `launchOptions` in use in the {% url "Browser Launch API doc" browser-launch-api %}. + +{% badge danger Before %} The second argument is no longer an array. + +```js +on('before:browser:launch', (browser, args) => { + // will print a deprecation warning telling you + // to change your code to the new signature + args.push('--another-arg') +}) +``` + +{% badge success After %} Access the `args` property off `launchOptions` + +```js +on('before:browser:launch', (browser, launchOptions) => { + launchOptions.args.push('--another-arg') +}) +``` + +## Electron options in `before:browser:launch` + +Previously, you could pass options to the launched Electron {% url "BrowserWindow" https://www.electronjs.org/docs/api/browser-window#new-browserwindowoptions %} in `before:browser:launch` by modifying the `launchOptions` object. + +Now, you must pass those options as `launchOptions.preferences`: + +{% badge danger Before %} Passing BrowserWindow options on the `launchOptions` object is no longer supported. + +```js +on('before:browser:launch', (browser, args) => { + args.darkTheme = true +}) +``` + +{% badge success After %} Pass BrowserWindow options on the `options.preferences` object instead. + +```js +on('before:browser:launch', (browser, launchOptions) => { + launchOptions.preferences.darkTheme = true +}) +``` + +## Launching Chrome Canary with `--browser` + +Before 4.0, `cypress run --browser canary` would run tests in Chrome Canary. + +Now, you must pass `--browser chrome:canary` to select Chrome Canary. + +See the {% url "docs for `cypress run --browser`" command-line#cypress-run-browser-lt-browser-name-or-path-gt %} for more information. + +{% badge danger Before %} Passing `canary` will no longer find a browser + +```shell +cypress run --browser canary +``` + +{% badge success After %} Pass `chrome:canary` to launch Chrome Canary + +```shell +cypress run --browser chrome:canary +``` + +## Chromium-based browser `family` + +We updated the {% url "Cypress browser objects" browser-launch-api %} of all Chromium-based browsers, including Electron, to have `chromium` set as their `family` field. + +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser = {}, launchOptions) => { + if (browser.family === 'electron') { + // would match Electron in 3.x + // will match no browsers in 4.0.0 + return launchOptions + } + + if (browser.family === 'chromium') { + // would match no browsers in 3.x + // will match any Chromium-based browser in 4.0.0 + // ie Chrome, Canary, Chromium, Electron, Edge (Chromium-based) + return launchOptions + } + }) +} +``` + +### Example #1 (Finding Electron) + +{% badge danger Before %} This will no longer find the Electron browser. + +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser = {}, args) => { + if (browser.family === 'electron') { + // run code for Electron browser in 3.x + return args + } + }) +} +``` + +{% badge success After %} Use `browser.name` to check for Electron + +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser = {}, launchOptions) => { + if (browser.name === 'electron') { + // run code for Electron browser in 4.0.0 + return launchOptions + } + }) +} +``` + +### Example #2 (Finding Chromium-based browsers) + +{% badge danger Before %} This will no longer find any browsers. + +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser = {}, args) => { + if (browser.family === 'chrome') { + // in 4.x, `family` was changed to 'chromium' for all Chromium-based browsers + return args + } + }) +} +``` + +{% badge success After %} Use `browser.name` and `browser.family` to select non-Electron Chromium-based browsers + +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser = {}, launchOptions) => { + if (browser.family === 'chromium' && browser.name !== 'electron') { + // pass launchOptions to Chromium-based browsers in 4.0 + return launchOptions + } + }) +} +``` + +## `cy.writeFile()` yields `null` + +`cy.writeFile()` now yields `null` instead of the `contents` written to the file. This change was made to more closely align with the behavior of Node.js {% url "`fs.writeFile`" https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback %}. + +{% badge danger Before %} This assertion will no longer pass + +```js +cy.writeFile('path/to/message.txt', 'Hello World') + .then((text) => { + // Would pass in Cypress 3 but will fail in 4 + expect(text).to.equal('Hello World') // false + }) +``` + +{% badge success After %} Instead read the contents of the file + +```js +cy.writeFile('path/to/message.txt', 'Hello World') +cy.readFile('path/to/message.txt').then((text) => { + expect(text).to.equal('Hello World') // true +}) +``` + +## cy.contains() ignores invisible whitespaces + +Browsers ignore leading, trailing, duplicate whitespaces. And Cypress now does that, too. + +```html +hello +world +``` + +```javascript +cy.get('p').contains('hello world') // Fail in 3.x. Pass in 4.0.0. +cy.get('p').contains('hello\nworld') // Pass in 3.x. Fail in 4.0.0. +``` + +## Node.js 8+ support + +Cypress comes bundled with it's own {% url "Node.js version" https://github.com/cypress-io/cypress/blob/develop/.node-version %}. However, installing the `cypress` npm package uses the Node.js version installed on your system. + +Node.js 4 reached its end of life on April 30, 2018 and Node.js 6 reached its end of life on April 30, 2019. {% url "See Node's release schedule" https://github.com/nodejs/Release %}. These Node.js versions will no longer be supported when installing Cypress. The minimum Node.js version supported to install Cypress is Node.js 8. + +## CJSX is no longer supported + +Cypress no longer supports CJSX (CoffeeScript + JSX), because the library used to transpile it is no longer maintained. + +If you need CJSX support, you can use a pre-2.x version of the Browserify preprocessor. + +```shell +npm install @cypress/browserify-preprocessor@1.1.2 +``` + +```javascript +// cypress/plugins/index.js +const browserify = require('@cypress/browserify-preprocessor') + +module.exports = (on) => { + on('file:preprocessor', browserify()) +} +``` diff --git a/source/guides/references/roadmap.md b/source/guides/references/roadmap.md index 703eca5528..7e56e5f7f8 100644 --- a/source/guides/references/roadmap.md +++ b/source/guides/references/roadmap.md @@ -10,7 +10,6 @@ Our team is always planning and working on really "big" upcoming features. Prior Status | Feature | Issue | PR ---------------------| -----------------------------------|-------------------|--- -*Work in progress* | **Firefox support** | {% issue 1096 %} | {% PR 1359 %} *Work in progress* | **Full network layer stubbing** | {% issue 687 %} | {% PR 4176 %} *Work in progress* | **Improve Test Runner errors** | {% issue 3762 %} | {% PR 3930 %} *Work in progress* | **Testing Electron Apps** | {% issue 2072 %} | @@ -22,4 +21,4 @@ Status | Feature | Issue | ## Dashboard Service -Please see our official {% url "Dashboard Product Board" https://portal.productboard.com/cypress-io/1-cypress-dashboard %}. \ No newline at end of file +Please see our official {% url "Dashboard Product Board" https://portal.productboard.com/cypress-io/1-cypress-dashboard %}. diff --git a/source/guides/references/trade-offs.md b/source/guides/references/trade-offs.md index 9c86eeda36..c0d696c138 100644 --- a/source/guides/references/trade-offs.md +++ b/source/guides/references/trade-offs.md @@ -29,7 +29,6 @@ Many of these issues are currently being worked on or are on our {% url "Roadmap - {% issue 170#issuecomment-340012621 "Testing file uploads is application specific." %} - {% issue 433#issuecomment-280465552 "Testing file downloads is application specific." %} - {% issue 685 "iframe support is somewhat limited, but does work." %} -- {% issue 310 "There is no cross browser support other than Chrome and Electron." %} - {% issue 95#issuecomment-281273126 "You cannot use `cy.route()` on `window.fetch` but there is a workaround." %} See the implementation in {% url "this recipe." https://github.com/cypress-io/cypress-example-recipes/tree/master/examples/stubbing-spying__window-fetch/cypress/integration %} - {% issue 144 "There is no shadow DOM support, but there are workarounds." %} See {% url "this comment." https://github.com/cypress-io/cypress/issues/830#issuecomment-449411701 %} diff --git a/source/guides/tooling/plugins-guide.md b/source/guides/tooling/plugins-guide.md index 01ee240078..5914d3ed9b 100644 --- a/source/guides/tooling/plugins-guide.md +++ b/source/guides/tooling/plugins-guide.md @@ -79,7 +79,7 @@ You can use the `task` event to do things like: - Manipulating a database (seeding, reading, writing, etc.) - Storing state in Node that you want persisted (since the driver is fully refreshed on visits) - Performing parallel tasks (like making multiple http requests outside of Cypress) -- Running an external process (like spinning up a Webdriver instance of another browser like Firefox, Safari, or puppeteer) +- Running an external process (like spinning up a Webdriver instance of another browser like Safari or puppeteer) # List of plugins diff --git a/source/guides/tooling/typescript-support.md b/source/guides/tooling/typescript-support.md index d1b6e7b27a..675efe6f17 100644 --- a/source/guides/tooling/typescript-support.md +++ b/source/guides/tooling/typescript-support.md @@ -113,6 +113,23 @@ it('works', () => { If you extend Cypress assertions, you can extend the assertion types to make the TypeScript compiler understand the new methods. See the {% url "Recipe: Adding Chai Assertions" recipes#Fundamentals %} for instructions. +## Types for plugins + +You can utilize Cypress's type declarations in your {% url "plugins file" plugins-guide %} by annotating it like the following: + +```javascript +// cypress/plugins/index.js + +/// + +/** + * @type {Cypress.PluginConfig} + */ +module.exports = (on, config) => { + +} +``` + ## Additional information See the excellent advice on {% url "setting Cypress using TypeScript" https://basarat.gitbooks.io/typescript/docs/testing/cypress.html %} in the {% url "TypeScript Deep Dive" https://basarat.gitbooks.io/typescript/content/ %} e-book by {% url "Basarat Syed" https://twitter.com/basarat %}. Take a look at {% url "this video" https://www.youtube.com/watch?v=1Vr1cAN_CLA %} Basarat has recorded and the accompanying repo {% url basarat/cypress-ts https://github.com/basarat/cypress-ts %}. diff --git a/themes/cypress/languages/en.yml b/themes/cypress/languages/en.yml index 0bded88fc3..ae05bd3340 100644 --- a/themes/cypress/languages/en.yml +++ b/themes/cypress/languages/en.yml @@ -51,6 +51,7 @@ sidebar: parallelization: Parallelization environment-variables: Environment Variables launching-browsers: Launching Browsers + cross-browser-testing: Cross Browser Testing custom-commands: Custom Commands web-security: Web Security references: References @@ -62,6 +63,7 @@ sidebar: best-practices: Best Practices trade-offs: Trade-offs changelog: Changelog + migration-guide: Migration Guide roadmap: Roadmap tooling: Tooling intelligent-code-completion: Intelligent Code Completion @@ -175,6 +177,7 @@ sidebar: cypress-api: Cypress API config: config env: env + isbrowser: isBrowser iscy: isCy custom-commands: Commands cookies: Cookies diff --git a/themes/cypress/languages/ja.yml b/themes/cypress/languages/ja.yml index a488b93dad..a1b64b25a0 100644 --- a/themes/cypress/languages/ja.yml +++ b/themes/cypress/languages/ja.yml @@ -51,6 +51,7 @@ sidebar: parallelization: Parallelization environment-variables: 環境変数 launching-browsers: ブラウザーを起動する + cross-browser-testing: クロスブラウザテスト custom-commands: カスタムコマンド web-security: ウェブセキュリティー references: 参考 @@ -62,6 +63,7 @@ sidebar: best-practices: ベストプラクティス trade-offs: トレードオフ changelog: 変更履歴 + migration-guide: Migration Guide roadmap: ロードマップ tooling: ツール intelligent-code-completion: コード自動補完 @@ -175,6 +177,7 @@ sidebar: cypress-api: Cypress API config: config env: env + isbrowser: isBrowser iscy: isCy custom-commands: Commands cookies: Cookies diff --git a/themes/cypress/languages/pt-br.yml b/themes/cypress/languages/pt-br.yml index e024c2e5e6..c56d034473 100644 --- a/themes/cypress/languages/pt-br.yml +++ b/themes/cypress/languages/pt-br.yml @@ -51,6 +51,7 @@ sidebar: parallelization: Paralelização environment-variables: Variáveis de Ambiente launching-browsers: Iniciando navegadores + cross-browser-testing: Cross Browser Testing custom-commands: Comandos Customizados web-security: Segurança Web references: Referências @@ -62,6 +63,7 @@ sidebar: best-practices: Boas Práticas trade-offs: Trade-offs changelog: Changelog + migration-guide: Migration Guide roadmap: Roteiro tooling: Ferramentas intelligent-code-completion: Conclusão Inteligente de Código @@ -175,6 +177,7 @@ sidebar: cypress-api: Cypress API config: config env: env + isbrowser: isBrowser iscy: isCy custom-commands: Commands cookies: Cookies diff --git a/themes/cypress/languages/ru.yml b/themes/cypress/languages/ru.yml index fc23c3db41..daf49be6b9 100644 --- a/themes/cypress/languages/ru.yml +++ b/themes/cypress/languages/ru.yml @@ -51,6 +51,7 @@ sidebar: parallelization: Параллелизация environment-variables: Переменные среды launching-browsers: Запуск браузеров + cross-browser-testing: Cross Browser Testing custom-commands: Пользовательские команды web-security: Web-безопасность references: Ссылки @@ -62,6 +63,7 @@ sidebar: best-practices: Лучшие практики trade-offs: Компромиссы changelog: Изменения в продукте + migration-guide: Migration Guide roadmap: Карта проекта tooling: Утилиты intelligent-code-completion: Интеллектуальное завершение кода @@ -175,6 +177,7 @@ sidebar: cypress-api: Cypress API config: config env: env + isbrowser: isBrowser iscy: isCy custom-commands: Commands cookies: Cookies diff --git a/themes/cypress/languages/zh-cn.yml b/themes/cypress/languages/zh-cn.yml index 42c08b97ff..8db469fe9b 100644 --- a/themes/cypress/languages/zh-cn.yml +++ b/themes/cypress/languages/zh-cn.yml @@ -53,6 +53,7 @@ sidebar: parallelization: 并行化 environment-variables: 环境变量 launching-browsers: 启动浏览器 + cross-browser-testing: 跨浏览器测试 custom-commands: 自定义命令 web-security: Web安全 references: 参考 @@ -64,6 +65,7 @@ sidebar: best-practices: 最佳实践 trade-offs: 取舍 changelog: 更新日志 + migration-guide: Migration Guide roadmap: 路线图 tooling: 工具 intelligent-code-completion: 代码智能补全 @@ -177,6 +179,7 @@ sidebar: cypress-api: Cypress API config: config env: env + isbrowser: isBrowser iscy: isCy custom-commands: Commands cookies: Cookies diff --git a/themes/cypress/source/css/_partial/page.scss b/themes/cypress/source/css/_partial/page.scss index 522d4c594e..590cf308f1 100644 --- a/themes/cypress/source/css/_partial/page.scss +++ b/themes/cypress/source/css/_partial/page.scss @@ -101,6 +101,11 @@ a.article-edit-link { margin: 25px 0; word-wrap: break-word; font-family: $font-sans; + + .badge { + position: relative; + top: -2px; + } } ol { @@ -456,6 +461,10 @@ a.article-edit-link { } } + p>img { + margin: 0; + } + &>h1, &>h2, &>h3 { margin-top: 15px; padding-top: 0; diff --git a/themes/cypress/source/img/api/contains/contains-pre-exception.png b/themes/cypress/source/img/api/contains/contains-pre-exception.png new file mode 100644 index 0000000000..beb8dfda63 Binary files /dev/null and b/themes/cypress/source/img/api/contains/contains-pre-exception.png differ diff --git a/themes/cypress/source/img/guides/browser-list-dropdown.png b/themes/cypress/source/img/guides/browser-list-dropdown.png new file mode 100644 index 0000000000..0894b07e63 Binary files /dev/null and b/themes/cypress/source/img/guides/browser-list-dropdown.png differ diff --git a/themes/cypress/source/img/guides/chrome-web-security-stdout-warning.jpg b/themes/cypress/source/img/guides/chrome-web-security-stdout-warning.jpg new file mode 100644 index 0000000000..e8fc202787 Binary files /dev/null and b/themes/cypress/source/img/guides/chrome-web-security-stdout-warning.jpg differ diff --git a/themes/cypress/source/img/guides/cross-browser-testing/cypress-browser-selector.png b/themes/cypress/source/img/guides/cross-browser-testing/cypress-browser-selector.png new file mode 100644 index 0000000000..ac2a494a59 Binary files /dev/null and b/themes/cypress/source/img/guides/cross-browser-testing/cypress-browser-selector.png differ diff --git a/themes/cypress/source/img/guides/firefox-gc-interval-in-command-log.jpg b/themes/cypress/source/img/guides/firefox-gc-interval-in-command-log.jpg new file mode 100644 index 0000000000..36cc647b86 Binary files /dev/null and b/themes/cypress/source/img/guides/firefox-gc-interval-in-command-log.jpg differ diff --git a/themes/cypress/source/img/guides/select-browser.png b/themes/cypress/source/img/guides/select-browser.png deleted file mode 100644 index 6762c40700..0000000000 Binary files a/themes/cypress/source/img/guides/select-browser.png and /dev/null differ diff --git a/themes/cypress/source/img/guides/troubleshooting-cypress-process-profiler-cli.jpg b/themes/cypress/source/img/guides/troubleshooting-cypress-process-profiler-cli.jpg new file mode 100644 index 0000000000..01627b6016 Binary files /dev/null and b/themes/cypress/source/img/guides/troubleshooting-cypress-process-profiler-cli.jpg differ
` doesn't ignore leading, trailing, or duplicate whitespaces as shown below: + +```html + +Other tags + Hello, World ! + +Pre tag + Hello, World ! +``` + +Rendered result: + +{% imgTag /img/api/contains/contains-pre-exception.png "The result of pre tag" %} + +To reflect this behavior, Cypress also doesn't ignore them. + +```js +// test result for above code + +cy.get('p').contains('Hello, World !') // pass +cy.get('p').contains(' Hello, World !') // fail + +cy.get('pre').contains('Hello, World !') // fail +cy.get('pre').contains(' Hello, World !') // pass +``` + ## Single Element ### Only the *first* matched element will be returned @@ -362,6 +405,10 @@ When clicking on the `contains` command within the command log, the console outp {% imgTag /img/api/contains/see-elements-found-from-contains-in-console.png "console.log contains" %} +{% history %} +{% url "4.0.0" changelog#4-0-0 %} | Added support for option `matchCase`. +{% endhistory %} + # See also - {% url `cy.get()` get %} diff --git a/source/api/commands/writefile.md b/source/api/commands/writefile.md index e469b80ef2..7271eabc6f 100644 --- a/source/api/commands/writefile.md +++ b/source/api/commands/writefile.md @@ -73,11 +73,10 @@ To use encoding with other options, have your options object be your third param If the path to the file does not exist, the file and its path will be created. If the file already exists, it will be over-written. ```javascript -cy - .writeFile('path/to/message.txt', 'Hello World') - .then((text) => { - expect(text).to.equal('Hello World') // true - }) +cy.writeFile('path/to/message.txt', 'Hello World') +cy.readFile('path/to/message.txt').then((text) => { + expect(text).to.equal('Hello World') // true +}) ``` `{projectRoot}/path/to/message.txt` will be created with the following contents: @@ -94,9 +93,9 @@ JavaScript arrays and objects are stringified and formatted into text. ```javascript cy.writeFile('path/to/data.json', { name: 'Eliza', email: 'eliza@example.com' }) - .then((user) => { - expect(user.name).to.equal('Eliza') - }) +cy.readFile('path/to/data.json').then((user) => { + expect(user.name).to.equal('Eliza') // true +}) ``` `{projectRoot}/path/to/data.json` will be created with the following contents: @@ -180,6 +179,7 @@ When clicking on the `writeFile` command within the command log, the console out {% imgTag /img/api/writefile/console-log-shows-contents-written-to-file.png "Console Log writeFile" %} {% history %} +{% url "4.0.0" changelog#4-0-0 %} | `cy.writeFile()` now yields `null` instead of `contents` {% url "3.1.1" changelog#3-1-1 %} | Added `flag` option and appending with `a+` {% url "1.0.0" changelog#1.0.0 %} | `cy.writeFile()` command added {% endhistory %} diff --git a/source/api/cypress-api/browser.md b/source/api/cypress-api/browser.md index 0f4cdde617..18ac3253d5 100644 --- a/source/api/cypress-api/browser.md +++ b/source/api/cypress-api/browser.md @@ -10,6 +10,21 @@ title: Cypress.browser Cypress.browser // returns browser object ``` +The object has the following properties: + +Property | Type | Description +--- | --- | --- +`channel` | `string` | Release channel of the browser, such as `stable`, `dev`, or `canary`. +`displayName` | `string` | Human-readable display name for the browser. +`family` | `string` | Rendering engine being used. `chromium` or `firefox`. +`isChosen` | `boolean` | Whether the browser is selected in the browser selector of the Test Runner. +`majorVersion` | `number` | The major version number of the browser. +`name`| `string` | Machine-friendly name, like `chrome`, `electron`, or `firefox`. +`path` | `string` | Path to the browser on disk. Blank for Electron. +`version` | `string` | Full version. +`isHeadless` | `boolean` | Whether the browser is running headlessly. +`isHeaded` | `boolean` | Whether the browser displays headed. + # Examples ## Log browser information @@ -20,11 +35,14 @@ Cypress.browser // returns browser object it('log browser info', function() { console.log(Cypress.browser) // { - // name: 'chrome', + // channel: 'stable', // displayName: 'Chrome', - // version: '67.123.456.90', - // majorVersion: '67', - // path: '/path/to/browser', + // family: 'chromium', + // isChosen: true, + // majorVersion: 80, + // name: 'chrome', + // path: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', + // version: '80.0.3987.87', // isHeaded: true, // isHeadless: false // } @@ -78,6 +96,7 @@ cy.screenshot() # See also -- {% url "Launching Browsers" launching-browsers %} - {% url "Browser Launch API" browser-launch-api %} - +- {% url "Cross Browser Testing" cross-browser-testing %} +- {% url "`Cypress.isBrowser`" isbrowser %} +- {% url "Launching Browsers" launching-browsers %} diff --git a/source/api/cypress-api/isbrowser.md b/source/api/cypress-api/isbrowser.md new file mode 100644 index 0000000000..4e3948b0a3 --- /dev/null +++ b/source/api/cypress-api/isbrowser.md @@ -0,0 +1,99 @@ +--- +title: Cypress.isBrowser +--- + +`Cypress.isBrowser` checks if the current browser matches the given name or filter. + +# Syntax + +```javascript +Cypress.isBrowser(name) +Cypress.isBrowser(filter) +``` + +## Arguments + +**{% fa fa-angle-right %} name** ***(String)*** + +The name of the browser (case-insensitive). + +**{% fa fa-angle-right %} filter** ***(Object)*** + +Filter 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 +--- | --- | --- +`name`| `string` | Machine-friendly name, like `chrome`, `electron`, or `firefox`. +`family` | `string` | Rendering engine being used. `chromium` or `firefox`. +`channel` | `string` | Release channel of the browser, such as `stable`, `dev`, or `canary`. +`displayName` | `string` | Human-readable display name for the browser. +`version` | `string` | Full version. +`path` | `string` | Path to the browser on disk. Blank for Electron. +`majorVersion` | `number` | The major version number of the browser. +`isHeadless` | `boolean` | Whether the browser is running headlessly. +`isHeaded` | `boolean` | Whether the browser displays headed. + +# Examples + +## Name + +### Only run tests in Chrome + +```javascript +// true when running in Chrome +if (Cypress.isBrowser('chrome')) { + it('only runs in chrome', function () { + // test some (hypothetical) issue with chrome + }) +} +``` + +### Skip a test in Firefox + +```javascript +it('a test', function() { + // true when running in Firefox + if (Cypress.isBrowser('firefox')) { + this.skip() + } +}) +``` + +## Filter + +### Only run commands in Chromium-based browser + +```javascript +it('has correct Chromium-based specific css property', function () { + // 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') + } +}) +``` + +### 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', function () { + // test some (hypothetical) issue with chrome + }) +} +``` + +{% history %} +{% url "4.0.0" changelog#4-0-0 %} | Added `isBrowser` command. +{% endhistory %} + +# See also + +- {% url "Browser Launch API" browser-launch-api %} +- {% url "Cross Browser Testing" cross-browser-testing %} +- {% url "`Cypress.browser`" browser %} +- {% url "Launching Browsers" launching-browsers %} diff --git a/source/api/cypress-api/iscy.md b/source/api/cypress-api/iscy.md index ca99414600..7b16255c63 100644 --- a/source/api/cypress-api/iscy.md +++ b/source/api/cypress-api/iscy.md @@ -14,7 +14,7 @@ Cypress.isCy(obj) ## Arguments -**{% fa fa-angle-right %} obj** ***(any)*** +**{% fa fa-angle-right %} obj** ***(Object)*** The object to test. diff --git a/source/api/plugins/browser-launch-api.md b/source/api/plugins/browser-launch-api.md index 5aab1e7ef0..c76ffb0c9c 100644 --- a/source/api/plugins/browser-launch-api.md +++ b/source/api/plugins/browser-launch-api.md @@ -2,55 +2,119 @@ title: Browser Launch API --- -Before Cypress launches a browser, it gives you the ability to modify the arguments used to launch it. +Before Cypress launches a browser, it gives you the opportunity to modify the browser preferences, install extensions, add and remove command-line arguments, and modify other options. -This is helpful to modify, remove, or add your own arguments. +# Syntax -The most common use case is adding your own web extension - [example recipe](https://www.cypress.io/blog/2020/01/07/how-to-load-the-react-devtools-extension-in-cypress/). +```js +on('before:browser:launch', (browser = {}, launchOptions) => { /* ... */ }) +``` + +**{% fa fa-angle-right %} browser** ***(object)*** + +An object describing the browser being launched, with the following properties: + +Property | Type | Description +--- | --- | --- +`name`| `string` | Machine-friendly name, like `chrome`, `electron`, or `firefox`. +`family` | `string` | Rendering engine being used. `chromium` or `firefox`. +`channel` | `string` | Release channel of the browser, such as `stable`, `dev`, or `canary`. +`displayName` | `string` | Human-readable display name for the browser. +`version` | `string` | Full version. +`path` | `string` | Path to the browser on disk. Blank for Electron. +`info` | `string` | *(Optional)* Extra information about the browser (used for display in the browser selector of the Test Runner) +`majorVersion` | `number` | The major version number of the browser. +`isHeadless` | `boolean` | Whether the browser is running headlessly. +`isHeaded` | `boolean` | Whether the browser displays headed. + +**{% fa fa-angle-right %} launchOptions** ***(object)*** + +Options that can be modified to control how the browser is launched, with the following properties: + +Property | Type | Description +--- | --- | --- +`preferences` | `object` | An object describing browser preferences. Differs between browsers. See {% urlHash "Changing browser preferences" Changing-browser-preferences %} for details. +`args` | `string[]` | An array of strings that will be passed as command-line args when the browser is launched. Has no effect on Electron. See {% urlHash "Modify browser launch arguments" Modify-browser-launch-arguments %} for details. +`extensions` | `string[]` | An array of paths to folders containing unpacked WebExtensions to be loaded before the browser starts. Note: Electron currently only supports Chrome DevTools extensions. See {% urlHash "Add browser extensions" Add-browser-extensions %} for details. # Usage -## Modify args based on browser +## Modify browser launch arguments, preferences, and extensions -Using your {% url "`pluginsFile`" plugins-guide %} you can tap into the `before:browser:launch` event and modify the arguments based on the browser that Cypress is launching. +Using your {% url "`pluginsFile`" plugins-guide %} you can tap into the `before:browser:launch` event and modify how Cypress launches the browser (e.g. modify arguments, user preferences, and extensions). -This event will yield you the `browser` as an object, and `args` which are the default arguments used to launch the browser. +This event will yield you the `browser` object, which gives you information about the browser, and the `launchOptions` object, which allows you to modify how the browser is launched. -`args` may be an array or an object (based on the type of browser we're launching). Whatever you return from this event will become the new args for launching the browser. +The returned `launchOptions` object will become the new launch options for the browser. -Here are options for the currently supported browsers: +### Modify browser launch arguments: -* {% url 'Chrome, Chromium, or Canary' "https://peter.sh/experiments/chromium-command-line-switches/" %} -* {% url 'Electron' "https://github.com/electron/electron/blob/master/docs/api/browser-window.md#new-browserwindowoptions" %} +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser = {}, launchOptions) => { + if (browser.family === 'chromium' && browser.name !== 'electron') { + // `args` is an array of all the arguments that will + // be passed to Chromium-based browsers when it launchers + launchOptions.args.push('--start-fullscreen') + + // whatever you return here becomes the launchOptions + return launchOptions + } + + if (browser.family === 'firefox') { + launchOptions.args.push('-some-cli-argument') + + return launchOptions + } + }) +} +``` + +### Add browser extensions: + +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser, launchOptions) => { + // supply the path to an unpacked WebExtension + // NOTE: extensions cannot be loaded in headless Chrome + launchOptions.extensions.push('/path/to/webextension') + + return launchOptions + }) +} +``` + +### Changing browser preferences: ```js module.exports = (on, config) => { - on('before:browser:launch', (browser = {}, args) => { - // browser will look something like this - // { - // name: 'chrome', - // displayName: 'Chrome', - // version: '63.0.3239.108', - // path: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', - // majorVersion: '63' - // } - - if (browser.name === 'chrome') { - // `args` is an array of all the arguments - // that will be passed to Chrome when it launchers - args.push('--start-fullscreen') - - // whatever you return here becomes the new args - return args + on('before:browser:launch', (browser, launchOptions) => { + if (browser.family === 'chromium' && browser.name !== 'electron') { + // in Chromium, preferences can exist in Local State, Preferences, or Secure Preferences + // via launchOptions.preferences, these can be acccssed as `localState`, `default`, and `secureDefault` + + // for example, to set `somePreference: true` in Preferences: + launchOptions.preferences.default.somePreference = true + + // more information about Chromium preferences can be found here: + // https://www.chromium.org/developers/design-documents/preferences + + return launchOptions + } + + if (browser.family === 'firefox') { + // launchOptions.preferences is a map of preference names to values + launchOptions.preferences['browser.startup.homepage'] = 'https://cypress.io' + + return launchOptions } if (browser.name === 'electron') { - // `args` is a `BrowserWindow` options object + // launchOptions.preferences is a `BrowserWindow` `options` object: // https://electronjs.org/docs/api/browser-window#new-browserwindowoptions - args['fullscreen'] = true + launchOptions.preferences.darkTheme = true - // whatever you return here becomes the new args - return args + return launchOptions } }) } @@ -78,7 +142,7 @@ Cypress already sets some the Electron command line switches internally. See fil ## See all Chrome browser switches -If you are running Cypress tests using Chrome browser, you can see ALL currently set command line switches and the browser version information by opening a new tab and typing `chrome://version` url. +If you are running Cypress tests using a Chromium-based browser, you can see ALL currently set command line switches and the browser version information by opening a new tab and typing `chrome://version` url. {% imgTag /img/api/chrome-switches.png "See all Chrome switches" %} @@ -94,16 +158,22 @@ You can however send your own video file for testing by passing a Chrome command ```js module.exports = (on, config) => { - on('before:browser:launch', (browser = {}, args) => { - if (browser.name === 'chrome') { + on('before:browser:launch', (browser = {}, launchOptions) => { + if (browser.family === 'chromium' && browser.name !== 'electron') { // Mac/Linux - args.push('--use-file-for-fake-video-capture=cypress/fixtures/my-video.y4m') + launchOptions.args.push('--use-file-for-fake-video-capture=cypress/fixtures/my-video.y4m') // Windows - // args.push('--use-file-for-fake-video-capture=c:\\path\\to\\video\\my-video.y4m') + // launchOptions.args.push('--use-file-for-fake-video-capture=c:\\path\\to\\video\\my-video.y4m') } - return args + return launchOptions }) } ``` + +{% history %} +{% url "4.0.0" changelog#4-0-0 %} | New `options` object replaces old `args` as second argument to `before:browser:launch` +{% url "4.0.0" changelog#4-0-0 %} | All Chromium-based browsers, including Electron, have `chromium` set as their `family` property. +{% url "4.0.0" changelog#4-0-0 %} | Added `channel` property to browser. +{% endhistory %} diff --git a/source/api/plugins/configuration-api.md b/source/api/plugins/configuration-api.md index 307bfbd2fc..cab6b1b360 100644 --- a/source/api/plugins/configuration-api.md +++ b/source/api/plugins/configuration-api.md @@ -41,7 +41,7 @@ Additionally, Cypress will respect and await promises you return. This enables y ## Customize available browsers -The configuration includes the list of browsers found on your system that are available to Cypress. +The configuration includes the list of browsers found on your system that are available to Cypress. {% note info %} Read our full guide on {% url "Launching Browsers" launching-browsers %} for more information on how this works. @@ -54,8 +54,9 @@ In the plugins file, you can filter the list of browsers passed inside the `conf module.exports = (on, config) => { // inside config.browsers array each object has information like // { - // name: 'canary', - // family: 'chrome', + // name: 'chrome', + // family: 'chromium', + // channel: 'canary', // displayName: 'Canary', // version: '80.0.3966.0', // path: @@ -63,7 +64,7 @@ module.exports = (on, config) => { // majorVersion: 80 // } return { - browsers: config.browsers.filter((b) => b.family === 'chrome') + browsers: config.browsers.filter((b) => b.family === 'chromium') } } ``` diff --git a/source/faq/questions/general-questions-faq.md b/source/faq/questions/general-questions-faq.md index 97ac30ae3d..1ba683d0c8 100644 --- a/source/faq/questions/general-questions-faq.md +++ b/source/faq/questions/general-questions-faq.md @@ -92,7 +92,7 @@ No. In fact Cypress' architecture is very different from Selenium in a few criti ## {% fa fa-angle-right %} If Cypress runs in the browser, doesn't that mean it's sandboxed? -Yes, technically; it's sandboxed and has to follow the same rules as every other browser. That's actually a good thing because it doesn't require a browser extension, and it naturally will work across all browsers (which enables cross-browser testing). +Yes, technically; it's sandboxed and has to follow the same rules as every other browser. That's actually a good thing because it doesn't require a browser extension, and it naturally will work across all browsers (which enables cross browser testing). But Cypress is actually way beyond a basic JavaScript application running in the browser. It is also a desktop application and communicates with back end web services. diff --git a/source/guides/getting-started/installing-cypress.md b/source/guides/getting-started/installing-cypress.md index ddc6764e4b..fd7c763c55 100644 --- a/source/guides/getting-started/installing-cypress.md +++ b/source/guides/getting-started/installing-cypress.md @@ -19,6 +19,10 @@ Cypress is a desktop application that is installed on your computer. The desktop - **Linux** Ubuntu 12.04 and above, Fedora 21 and Debian 8 *(64-bit only)* - **Windows** 7 and above +If using `npm` to install Cypress, we support: + +- **Node.js** 8 and above + # Installing ## {% fa fa-terminal %} `npm install` @@ -122,7 +126,7 @@ After a moment, the Cypress Test Runner will launch. The Cypress Test Runner attempts to find all compatible browsers on the user's machine. The drop down to select a different browser is in the top right corner of the Test Runner. -{% imgTag /img/guides/select-browser.png "Select a different browser" %} +{% imgTag /img/guides/browser-list-dropdown.png "Select a different browser" %} Read {% url "Launching Browsers" launching-browsers %} for more information on how Cypress controls a real browser during end-to-end tests. diff --git a/source/guides/guides/command-line.md b/source/guides/guides/command-line.md index bd48af2f32..6abcafde0d 100644 --- a/source/guides/guides/command-line.md +++ b/source/guides/guides/command-line.md @@ -69,7 +69,7 @@ npx cypress run --record --spec "cypress/integration/my-spec.js" ## `cypress run` -Runs Cypress tests to completion. By default, `cypress run` will run all tests headlessly in the `Electron` browser. +Runs Cypress tests to completion. By default, `cypress run` will run all tests headlessly in the Electron browser. ```shell cypress run [options] @@ -85,8 +85,8 @@ Option | Description `--config-file`, `-C` | {% urlHash "Specify configuration file" cypress-run-config-file-lt-config-file-gt %} `--env`, `-e` | {% urlHash "Specify environment variables" cypress-run-env-lt-env-gt %} `--group` | {% urlHash "Group recorded tests together under a single run" cypress-run-group-lt-name-gt %} -`--headed` | {% urlHash "Displays the browser instead of running headlessly (defaults to true for Chrome-family browsers)" cypress-run-headed %} -`--headless` | {% urlHash "Hide the browser instead of running headed (defaults to true for Electron)" cypress-run-headless %} +`--headed` | {% urlHash "Displays the browser instead of running headlessly (default for Firefox and Chromium-based browsers)" cypress-run-headed %} +`--headless` | {% urlHash "Hide the browser instead of running headed (default for Electron)" cypress-run-headless %} `--help`, `-h` | Output usage information `--key`, `-k` | {% urlHash "Specify your secret record key" cypress-run-record-key-lt-record-key-gt %} `--no-exit` | {% urlHash "Keep Cypress Test Runner open after tests in a spec file run" cypress-run-no-exit %} @@ -105,7 +105,9 @@ Option | Description cypress run --browser chrome ``` -The "browser" argument can be set to "chrome", "canary", "chromium", or "electron" to launch a browser detected on your system. Cypress will attempt to automatically find the installed browser for you. +The "browser" argument can be set to `chrome`, `chromium`, `edge`, `electron`, `firefox` to launch a browser detected on your system. Cypress will attempt to automatically find the installed browser for you. + +To launch non-stable browsers, add a colon and the desired release channel. For example, to launch Chrome Canary, use `chrome:canary`. You can also choose a browser by supplying a path: @@ -113,8 +115,6 @@ You can also choose a browser by supplying a path: cypress run --browser /usr/bin/chromium ``` -Currently, only browsers in the Chrome family are supported. - {% url "Having trouble with browser detection? Check out the debugging guide" debugging#Launching-browsers %} ### `cypress run --ci-build-id ` @@ -195,6 +195,10 @@ Specifying the `--ci-build-id` may also be necessary. ### `cypress run --headed` +{% note warning %} +Video recording is not currently supported in Electron with the `--headed` flag. See {% issue 1767 %} for more details. +{% endnote %} + By default, Cypress will run tests in Electron headlessly. Passing `--headed` will force Electron to be shown. This matches how you run Electron in interactive mode. @@ -205,9 +209,9 @@ cypress run --headed ### `cypress run --headless` -For backwards-compatibility reasons, when using Chrome, Cypress will run tests in headed mode by default. +Cypress will run tests in Chrome and Firefox headed by default. -Passing `--headless` will force Chrome to be hidden. +Passing `--headless` will force the browser to be hidden. ```shell cypress run --headless --browser chrome @@ -325,7 +329,7 @@ Give a run multiple tags. cypress run --record --tag "production,nightly" ``` -The Dashboard will display any tags sent with the appropriate run. +The Dashboard will display any tags sent with the appropriate run. {% imgTag /img/dashboard/dashboard-run-with-tags.png "Cypress run in the Dashboard displaying flags" %} @@ -365,7 +369,7 @@ cypress open --browser /usr/bin/chromium If found, the specified browser will be added to the list of available browsers in the Cypress Test Runner. -Currently, only browsers in the Chrome family are supported. +Currently, only browsers in the Chrome family are supported (including the new Chromium-based Microsoft Edge and Brave). {% url "Having trouble launching a browser? Check out the debugging guide" debugging#Launching-browsers %} diff --git a/source/guides/guides/continuous-integration.md b/source/guides/guides/continuous-integration.md index dac2520d56..f9600f2003 100644 --- a/source/guides/guides/continuous-integration.md +++ b/source/guides/guides/continuous-integration.md @@ -734,9 +734,9 @@ If you want colors to be disabled, you can pass the `NO_COLOR` environment varia NO_COLOR=1 cypress run ``` - # See also - {% url cypress-example-kitchensink https://github.com/cypress-io/cypress-example-kitchensink#ci-status %} is set up to run on multiple CI providers. +- {% url "Cross Browser Testing Guide" cross-browser-testing %} - {% url "Blog: Setting up Bitbucket Pipelines with proper caching of npm and Cypress" https://www.cypress.io/blog/2018/08/30/setting-up-bitbucket-pipelines-with-proper-caching-of-npm-and-cypress/ %} - {% url "Blog: Record Test Artifacts from any Docker CI" https://www.cypress.io/blog/2018/08/28/record-test-artifacts-from-any-ci/ %} diff --git a/source/guides/guides/cross-browser-testing.md b/source/guides/guides/cross-browser-testing.md new file mode 100644 index 0000000000..2549015a07 --- /dev/null +++ b/source/guides/guides/cross-browser-testing.md @@ -0,0 +1,244 @@ +--- +title: Cross Browser Testing +--- + +Cypress has the capability to run tests across multiple browsers. Currently, Cypress has support for {% url "Chrome-family browsers" launching-browsers#Chrome-Browsers %} (including Electron) and beta support for Firefox browsers. + +{% note warning 'Web Security' %} +Tests that require the {% url "`chromeWebSecurity` configuration option to be disabled" web-security#Disabling-Web-Security %} may experience issues in non-Chromium based browsers. +{% endnote %} + +{% note warning 'Firefox Garbage Collection' %} +Cypress triggers Firefox's internal garbage collection (GC) to better manage the browser's memory consumption. {% url "Learn more here" configuration#firefoxGcInterval %}. +{% endnote %} + +Excluding {% url "Electron" launching-browsers#Electron-Browser %}, any browser you want to run Cypress tests in needs to be installed on your local system or CI environment. A full list of detected browsers is displayed within the browser selection menu of the {% url "Test Runner" test-runner %}. + +{% imgTag /img/guides/cross-browser-testing/cypress-browser-selector.png "Cypress Test Runner with Firefox selected as the browser" "no-border" %} + +The desired browser can also specified via the {% url `--browser` command-line#Options %} flag when using {% url `run` command-line#cypress-run %} command to launch Cypress. For example, to run Cypress tests in Firefox: + +```shell +cypress run --browser firefox +``` + +To make launching of Cypress with a specific browser even more convenient, npm scripts can be used as a shortcut: + +```json +"scripts": { + "cy:run:chrome": "cypress run --browser chrome", + "cy:run:firefox": "cypress run --browser firefox" +} +``` + +# Continuous Integration Strategies + +When incorporating testing of multiple browsers within your QA process, you must implement a CI strategy that provides an optimal level of confidence while taking into consideration test duration and infrastructure costs. This optimal strategy will vary by the type and needs of a particular project. This guide we present several strategies to consider when crafting the strategy for your project. + +CI strategies will be demonstrated using the {% url "Circle CI Cypress Orb" https://circleci.com/orbs/registry/orb/cypress-io/cypress %} for its concise and readable configuration, but the same concepts apply for most CI providers. + +{% note info 'Docker Images for Testing' %} +The CI configuration examples within this guide use {% url "Cypress's Docker images" https://github.com/cypress-io/cypress-docker-images/tree/master/browsers %} to provision testing environments with desired versions of Node, Chrome, and Firefox. +{% endnote %} + +## Periodic Basis + +Generally, it is desired to run tests with each pushed commit, but it may not be necessary to do so for all browsers. For example, we can choose to run tests within Chrome for each commit, but only run Firefox on a periodic basis (i.e. nightly). The periodic frequency will depend on the scheduling of your project releases, so consider a test run frequency that is appropriate for the release schedule of your project. + +{% note info 'Cron Scheduling' %} +Typically CI providers allow for the scheduling of CI jobs via {% url "cron expressions" https://en.wikipedia.org/wiki/Cron %}. For example, the expression `0 0 * * *` translates to "everyday at midnight" or nightly. Helpful {% url "online utilities" https://crontab.guru/ %} are available to assist with creation and translation of cron expressions. +{% endnote %} + +The following example demonstrates a nightly CI schedule against production (`master` branch) for Firefox: + +```yaml +version: 2.1 +orbs: + cypress: cypress-io/cypress@1 +workflows: + nightly: + triggers: + - schedule: + cron: "0 0 * * *" + filters: + branches: + only: + - master + jobs: + - cypress/run: + executor: cypress/browsers-chrome73-ff68 + browser: firefox + start: npm start + wait-on: http://localhost:3000 +``` + +## Production Deployment + +For projects that exhibit consistently stable behavior across browsers, it may be better to run tests against additional browsers only before merging changes in the production deployment branch. + +The following example demonstrates only running Firefox tests when commits are merged into a specific branch (`develop` branch in this case) so any potential Firefox issues can be caught before a production release: + +```yaml +version: 2.1 +orbs: + cypress: cypress-io/cypress@1 +workflows: + test_develop: + jobs: + - filters: + branches: + only: + - develop + - cypress/run: + executor: cypress/browsers-chrome73-ff68 + browser: firefox + start: npm start + wait-on: http://localhost:3000 +``` + +## Subset of Tests + +We can choose to only run a subset of tests against a given browser. For example, we can execute only the happy or critical path related test files, or a directory of specific "smoke" test files. It is not always necessary to have both browsers always running *all* tests. + +In the example below, the Chrome `cypress/run` job runs *all* tests against Chrome and reports results to the {% url "Cypress Dashboard" https://on.cypress.io/dashboard %} using a ({% url "group" parallelization#Grouping-test-runs %}) named `chrome`. + +The Firefox `cypress/run` job runs a subset of tests, defined in the `spec` parameter, against the Firefox browser, and reports the results to the {% url "Cypress Dashboard" https://on.cypress.io/dashboard %} under the group `firefox-critical-path`. + +{% note info %} +**Note:** The `name` under each `cypress/run` job which will be shown in the Circle CI workflow UI to distinguish the jobs. +{% endnote %} + +```yaml +version: 2.1 +orbs: + cypress: cypress-io/cypress@1 +workflows: + build: + jobs: + - cypress/install + - cypress/run: + name: Chrome + requires: + - cypress/install + executor: cypress/browsers-chrome73-ff68 + start: npm start + wait-on: http://localhost:3000 + record: true + group: chrome + browser: chrome + - cypress/run: + name: Firefox + requires: + - cypress/install + executor: cypress/browsers-chrome73-ff68 + start: npm start + wait-on: http://localhost:3000 + record: true + group: firefox-critical-path + browser: firefox + spec: "cypress/integration/signup.spec.js,cypress/integration/login.spec.js" +``` + +## Parallelize per browser + +Execution of test files can be parallelized on a per {% url "group" parallelization#Grouping-test-runs %} basis, where test files can be grouped by the browser under test. This versatility enables the ability to allocate the desired amount of CI resources towards a browser to either improve test duration or to minimize CI costs. + +**You do not have to run all browsers at the same parallelization level.** In the example below, the Chrome dedicated `cypress/run` job runs *all* tests in parallel, across **4 machines**, against Chrome and reports results to the {% url "Cypress Dashboard" https://on.cypress.io/dashboard %} under the group name `chrome`. The Firefox dedicated `cypress/run` job runs a *subset* of tests in parallel, across **2 machines**, defined by the `spec` parameter, against the Firefox browser and reports results to the {% url "Cypress Dashboard" https://on.cypress.io/dashboard %} under the group named `firefox`. + +```yaml +version: 2.1 +orbs: + cypress: cypress-io/cypress@1 +workflows: + build: + jobs: + - cypress/install + - cypress/run: + name: Chrome + requires: + - cypress/install + executor: cypress/browsers-chrome73-ff68 + record: true + start: npm start + wait-on: http://localhost:3000 + parallel: true + parallelism: 4 + group: chrome + browser: chrome + - cypress/run: + name: Firefox + requires: + - cypress/install + executor: cypress/browsers-chrome73-ff68 + record: true + start: npm start + wait-on: http://localhost:3000 + parallel: true + parallelism: 2 + group: firefox + browser: firefox + spec: "cypress/integration/app.spec.js,cypress/integration/login.spec.js,cypress/integration/about.spec.js" +``` + +## 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. + +{% 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. + +```js +const runOn = (browser, fn) => { + if (Cypress.isBrowser(browser) { + fn() + } +} + +const ignoreOn = (browser, fn) => { + if (!Cypress.isBrowser(browser) { + fn() + } +} + +// Run happy path tests if Cypress is run via Firefox +runOn('firefox', () => { + describe('happy path suite', () => { + it('...') + it('...') + it('...') + }) +}) + +// Ignore test if Cypress is running via Firefox +// This test is not recorded to the Cypress Dashboard +ignoreOn('firefox', () => { + it('a test', function() { + // ... 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 +}) +``` + +# See also + +- {% url "Browser Launch API" browser-launch-api %} +- {% url "`Cypress.browser`" browser %} +- {% url "`Cypress.isBrowser`" isbrowser %} +- {% url "Launching Browsers" launching-browsers %} diff --git a/source/guides/guides/debugging.md b/source/guides/guides/debugging.md index 6a2542a844..6cfc273cdc 100644 --- a/source/guides/guides/debugging.md +++ b/source/guides/guides/debugging.md @@ -158,7 +158,9 @@ Browser Name | Expected Bundle Identifier | Expected Executable --- | --- | --- `chrome` | `com.google.Chrome` | `Contents/MacOS/Google Chrome` `chromium` | `org.chromium.Chromium` | `Contents/MacOS/Chromium` -`canary` | `com.google.Chrome.canary` | `Contents/MacOS/Google Chrome Canary` +`chrome:canary` | `com.google.Chrome.canary` | `Contents/MacOS/Google Chrome Canary` + +For the current list, see {% url 'packages/launcher' https://github.com/cypress-io/cypress/blob/develop/packages/launcher/lib/darwin/index.ts %} files. ### Linux @@ -168,7 +170,7 @@ Browser Name | Expected Binary Name(s) --- | --- `chrome` | `google-chrome`, `chrome`, or `google-chrome-stable` `chromium` | `chromium-browser` or `chromium` -`canary` | `google-chrome-canary` +`chrome:canary` | `google-chrome-canary` These binary names should work for most Linux distributions. If your distribution packages browsers under a different binary name, you can add a symlink using the expected binary name so that Cypress can detect it. @@ -186,7 +188,9 @@ Browser Name | Expected Path --- | --- `chrome` | `C:/Program Files (x86)/Google/Chrome/Application/chrome.exe` `chromium` | `C:/Program Files (x86)/Google/chrome-win32/chrome.exe` -`canary` | `%APPDATA%/../Local/Google/Chrome SxS/Application/chrome.exe` +`chrome:canary` | `%APPDATA%/../Local/Google/Chrome SxS/Application/chrome.exe` + +For the current list, see {% url 'packages/launcher' https://github.com/cypress-io/cypress/blob/develop/packages/launcher/lib/windows/index.ts %} files. To make a browser installed at a different path be auto-detected, create a symbolic link using `mklink` in the location that Cypress expects to find your browser. @@ -251,9 +255,6 @@ DEBUG=cypress:* cypress run ```shell set DEBUG=cypress:* -``` - -```shell cypress run ``` @@ -309,6 +310,31 @@ cy.now('task', 123) The `cy.now()` command is an internal command and may change in the future. {% endnote %} +## Log memory and CPU usage + +You can tell Cypress to log out a summary of the memory and CPU usage of itself and any subprocesses at a regular interval by enabling the `cypress:server:util:process_profiler` debug stream, like so: + +**On Mac or Linux:** + +```shell +DEBUG=cypress:server:util:process_profiler cypress run +``` + +**On Windows:** + +```shell +set DEBUG=cypress:server:util:process_profiler +cypress run +``` + +In the resulting output, processes are grouped by their name. + +{% imgTag /img/guides/troubleshooting-cypress-process-profiler-cli.jpg "Process printout of Cypress in CLI" %} + +By default, process information is collected and summarized is printed once every 10 seconds. You can override this interval by setting the `CYPRESS_PROCESS_PROFILER_INTERVAL` environment variable to the desired interval in milliseconds. + +You can also obtain more detailed per-process information by enabling the verbose `cypress-verbose:server:util:process_profiler` debug stream. + ## Additional information ### Write command log to the terminal diff --git a/source/guides/guides/launching-browsers.md b/source/guides/guides/launching-browsers.md index b991b54698..4c9951be90 100644 --- a/source/guides/guides/launching-browsers.md +++ b/source/guides/guides/launching-browsers.md @@ -14,11 +14,18 @@ When Cypress is initially run from the Test Runner, you can choose to run Cypres - {% url "Canary" https://www.google.com/chrome/browser/canary.html %} - {% url "Chrome" https://www.google.com/chrome/browser/desktop/index.html %} - {% url "Chromium" https://www.chromium.org/Home %} +- {% url "Edge" https://www.microsoft.com/edge %} +- {% url "Edge Beta" https://www.microsoftedgeinsider.com/download %} +- {% url "Edge Canary" https://www.microsoftedgeinsider.com/download %} +- {% url "Edge Dev" https://www.microsoftedgeinsider.com/download %} - {% url "Electron" https://electron.atom.io/ %} +- {% url "Firefox" https://www.mozilla.org/firefox/ %} (Beta support) +- {% url "Firefox Developer Edition" https://www.mozilla.org/firefox/developer/ %} (Beta support) +- {% url "Firefox Nightly" https://www.mozilla.org/firefox/nightly/ %} (Beta support) Cypress automatically detects available browsers on your OS. You can switch the browser in the Test Runner by using the drop down in the top right corner: -{% imgTag /img/guides/select-browser.png "Select a different browser" %} +{% imgTag /img/guides/browser-list-dropdown.png "Select a different browser" %} {% partial chromium_download %} @@ -42,7 +49,7 @@ Because Electron is the default browser - it is typically run in CI. If you are All Chrome* flavored browsers will be detected and are supported. -### You can launch Chrome browsers: +You can launch Chrome like this: ```shell cypress run --browser chrome @@ -61,11 +68,44 @@ cypress run --browser chromium Or Chrome Canary: ```shell -cypress run --browser canary +cypress run --browser chrome:canary +``` + +Or Microsoft Edge (Chromium-based): + +```shell +cypress run --browser edge +``` + +Or Microsoft Edge Canary (Chromium-based): + +```shell +cypress run --browser edge:canary ``` {% url 'Having issues launching installed browsers? Read more about debugging browser launching' debugging#Launching-browsers %} +## Firefox Browsers (beta) + +Firefox-family browsers have beta support. + +You can launch Firefox like this: + +```shell +cypress run --browser firefox +``` + +Or Firefox Developer/Nightly Edition: + +```shell +cypress run --browser firefox:dev +cypress run --browser firefox:nightly +``` + +To use this command in CI, you need to install these other browsers - or use one of our {% url 'docker images' docker %}. + +By default, we will launch Firefox in headed mode. To run Firefox headlessly, you can pass the `--headless` argument to `cypress run`. + ## Launching by a path You can launch any supported browser by specifying a path to the binary: @@ -93,8 +133,9 @@ In the plugins file, you can filter the list of browsers passed inside the `conf module.exports = (on, config) => { // inside config.browsers array each object has information like // { - // name: 'canary', - // family: 'chrome', + // name: 'chrome', + // channel: 'canary', + // family: 'chromium', // displayName: 'Canary', // version: '80.0.3966.0', // path: @@ -102,7 +143,7 @@ module.exports = (on, config) => { // majorVersion: 80 // } return { - browsers: config.browsers.filter((b) => b.family === 'chrome') + browsers: config.browsers.filter((b) => b.family === 'chromium') } } ``` @@ -115,7 +156,7 @@ When you open the Test Runner in a project that uses the above modifications to If you return an empty list of browsers or `browsers: null`, the default list will be restored automatically. {% endnote %} -If you have installed a Chromium-based browser like {% url Brave https://brave.com/ %}, {% url Vivaldi https://vivaldi.com/ %} and even the new {% url "Microsoft Edge Beta" https://www.microsoftedgeinsider.com/en-us/ %} you can add them to the list of returned browsers. Here is a plugins file that inserts a local Brave browser into the returned list. +If you have installed a Chromium-based browser like {% url Brave https://brave.com/ %}, {% url Vivaldi https://vivaldi.com/ %} you can add them to the list of returned browsers. Here is a plugins file that inserts a local Brave browser into the returned list. ```javascript // cypress/plugins/index.js @@ -134,7 +175,8 @@ const findBrowser = () => { return { name: 'Brave', - family: 'chrome', + channel: 'stable', + family: 'chromium', displayName: 'Brave', version, path: browserPath, @@ -154,7 +196,7 @@ module.exports = (on, config) => { {% imgTag /img/guides/plugins/brave-browser.png "List of browsers includes Brave browser" %} -Once selected, the Brave browser is detected using the same approach as any other browser of the `chrome` family. +Once selected, the Brave browser is detected using the same approach as any other browser of the `chromium` family. {% imgTag /img/guides/plugins/brave-running-tests.png "Brave browser executing end-to-end tests" %} @@ -162,7 +204,7 @@ If you modify the list of browsers, you can see the {% url "resolved configurati ## Unsupported Browsers -Many browsers such as Firefox, Safari, and Internet Explorer are not currently supported. While it may be possible to modify the list of browsers found and run Cypress within them - we do not guarantee full functionality. Support for more browsers is on our roadmap. You can read an exhaustive explanation about our future cross browser testing strategy {% issue 310 'here' %}. +Many browsers such as Safari and Internet Explorer are not currently supported. Support for more browsers is on our roadmap. You can read an explanation about our future cross browser roadmap {% issue 310 'here' %}. # Browser Environment @@ -174,8 +216,8 @@ When Cypress goes to launch your browser it will give you an opportunity to modi This enables you to do things like: -- Load your own chrome extension -- Enable or disable experimental chrome features +- Load your own extension +- Enable or disable experimental features {% url 'This part of the API is documented here.' browser-launch-api %} @@ -210,16 +252,16 @@ You can see all of the default chrome command line switches we send {% url "here # Browser Icon -You might notice that if you already have the browser open you will see two of the same browser icons in your Dock. +You might notice that if you already have the browser open you will see two of the same browser icons in your dock. {% video local /img/snippets/switching-between-cypress-and-other-chrome-browser.mp4 %} We understand that when Cypress is running in its own profile it can be difficult to tell the difference between your normal browser and Cypress. -For this reason we recommend {% url "downloading Chromium" https://www.chromium.org/Home %} or {% url "downloading Canary" https://www.google.com/chrome/browser/canary.html %}. These browsers both have different icons from the standard Chrome browser, making them more distinguishable. You can also use the bundled {% urlHash "Electron browser" Electron-Browser %}, which does not have a Dock icon. +For this reason you may find downloading and using a browser's release channel versions (Dev, Canary, etc) useful. These browsers have different icons from the standard stable browser, making them more distinguishable. You can also use the bundled {% urlHash "Electron browser" Electron-Browser %}, which does not have a dock icon. {% video local /img/snippets/switching-cypress-browser-and-canary-browser.mp4 %} -Additionally, we've made the browsers spawned by Cypress look different than regular sessions. You'll see a darker theme around the chrome of the browser. You'll always be able to visually distinguish these. +Additionally, in Chrome-based browsers, we've made the browser spawned by Cypress look different than regular sessions. You'll see a darker theme around the chrome of the browser. You'll always be able to visually distinguish these. {% imgTag /img/guides/cypress-browser-chrome.png "Cypress Browser with darker chrome" %} diff --git a/source/guides/guides/module-api.md b/source/guides/guides/module-api.md index 236f9006c9..e5e65f0650 100644 --- a/source/guides/guides/module-api.md +++ b/source/guides/guides/module-api.md @@ -24,8 +24,8 @@ Option | Type | Description `configFile` | *string / boolean* | Path to the config file to be used. If `false` is passed, no config file will be used. `env` | *object* | Specify {% url "environment variables" environment-variables %} `group` | *string* | {% url "Group" parallelization#Grouping-test-runs %} recorded tests together under a single run -`headed` | *boolean* | Displays the browser instead of running headlessly (defaults to true for Chrome-family browsers) -`headless` | *boolean* | Hide the browser instead of running headed (defaults to true for Electron) +`headed` | *boolean* | Displays the browser instead of running headlessly (default Firefox and Chromium-based browsers) +`headless` | *boolean* | Hide the browser instead of running headed (defaults for Electron) `key` | *string* | Specify your secret record key `exit` | *boolean* | Whether to close Cypress after all tests run `parallel` | *boolean* | Run recorded specs in {% url "parallel" parallelization %} across multiple machines @@ -45,7 +45,6 @@ cypress.run({ browser: 'chrome', config: { baseUrl: 'http://localhost:8080', - chromeWebSecurity: false, video: true, }, env: { diff --git a/source/guides/guides/parallelization.md b/source/guides/guides/parallelization.md index 3c208bfde3..6e57fd4518 100644 --- a/source/guides/guides/parallelization.md +++ b/source/guides/guides/parallelization.md @@ -19,7 +19,7 @@ If your project has a large number of tests, it can take a long time for tests t Cypress can run recorded tests in parallel across multiple machines since version {% url "3.1.0" changelog#3-1-0 %}. While parallel tests can also technically run on a single machine, we do not recommend it since this machine would require significant resources to run your tests efficiently. -This guide assumes you already have your project running and {% url "recording" projects#Setup %} within Continuous Integration. If you have not set up your project yet, check out our {% url "Continuous Integration guide" continuous-integration %}. +This guide assumes you already have your project running and {% url "recording" projects#Setup %} within Continuous Integration. If you have not set up your project yet, check out our {% url "Continuous Integration guide" continuous-integration %}. If you are running or planning to run tests across multiple browsers (Firefox, Chrome, or Edge), we also recommend checking out our {% url "Cross Browser Testing guide" cross-browser-testing %} for helpful CI strategies when using parallelization. {% imgTag /img/guides/parallelization/parallelization-diagram.png "Parallelization Diagram" "no-border" %} @@ -147,6 +147,13 @@ For multiple runs to be grouped into a single run, it is required for CI machine {% imgTag /img/guides/parallelization/machines-view-grouping-expanded.png "Machines view grouping expanded" "no-border" %} +{% note info %} +# Cross Browser Testing + +Grouping test runs with or without parallelization is a useful mechanism when implementing a CI strategy for cross browser testing. Check out the {% url "Cross Browser Testing guide" cross-browser-testing %} to learn more. + +{% endnote %} + ## Grouping by browser You can test your application against different browsers and view the results under a single run within the Dashboard. Below, we name our groups the same name as the browser being tested: @@ -287,6 +294,8 @@ The Machines View charts spec files by the machines that executed them. This vie # See also +- {% url "Continuous Integration Guide" continuous-integration %} +- {% url "Cross Browser Testing Guide" cross-browser-testing %} - {% url "Blog: Run Your End-to-end Tests 10 Times Faster with Automatic Test Parallelization" https://www.cypress.io/blog/2018/09/05/run-end-to-end-tests-on-ci-faster/ %} - {% url "Blog: Run and group tests the way you want to" https://glebbahmutov.com/blog/run-and-group-tests/ %} - {% url "CI Configurations in Kitchen Sink Example" https://github.com/cypress-io/cypress-example-kitchensink#ci-status %} diff --git a/source/guides/guides/screenshots-and-videos.md b/source/guides/guides/screenshots-and-videos.md index b380faf4d6..c931b46900 100644 --- a/source/guides/guides/screenshots-and-videos.md +++ b/source/guides/guides/screenshots-and-videos.md @@ -27,7 +27,11 @@ Cypress clears any existing screenshots before `cypress run`. If you do not want # Videos -Cypress also records videos when running tests. +{% note warning %} +Video recording is not currently supported in Electron with the {% url "`--headed` flag" command-line#cypress-run-headed %}. See {% issue 1767 %} for more details. +{% endnote %} + +Cypress records a video for each spec file when running tests. Video recording can be turned off entirely by setting {% url `video` configuration#Videos %} to `false` from within your configuration. diff --git a/source/guides/guides/web-security.md b/source/guides/guides/web-security.md index 51def0f2eb..7a04a8bf85 100644 --- a/source/guides/guides/web-security.md +++ b/source/guides/guides/web-security.md @@ -260,9 +260,17 @@ So if you cannot work around any of the issues using the suggested workarounds a One last thing to consider here is that every once in a while we discover bugs in Cypress that lead to cross-origin errors that can otherwise be fixed. If you think you're experiencing a bug, {% open_an_issue 'open an issue' %}. -To start, you will need to understand that *not all browsers expose a way to turn off web security*. Some do, some don't. If you rely on disabling web security, you will not be able to run tests on browsers that do not support this feature. +{% note warning 'Chrome only' %} +Disabling web security is only supported in Chrome-based browsers. Settings in `chromeWebSecurity` will have no effect in other browsers. We will log a warning in this case. -## Setting `chromeWebSecurity` to `false` allows you to do the following: +{% imgTag /img/guides/chrome-web-security-stdout-warning.jpg 'chromeWebSecurity warning in stdout'%} + +If you rely on disabling web security, you will not be able to run tests on browsers that do not support this feature. +{% endnote %} + +## Set `chromeWebSecurity` to `false` + +Setting `chromeWebSecurity` to `false` in Chrome-based browsers allows you to do the following: - Display insecure content - Navigate to any superdomain without cross-origin errors @@ -272,7 +280,7 @@ One thing you may notice though is that Cypress still enforces visiting a single Still here? That's cool, let's disable web security! -### Set `chromeWebSecurity` to `false` in your {% url "configuration file (`cypress.json` by default)" configuration %}` and we'll take care of the rest +### Set `chromeWebSecurity` to `false` in your {% url "configuration file (`cypress.json` by default)" configuration %}` ```json { diff --git a/source/guides/references/assertions.md b/source/guides/references/assertions.md index acebdae621..cabe0f80e2 100644 --- a/source/guides/references/assertions.md +++ b/source/guides/references/assertions.md @@ -110,6 +110,7 @@ These assertions are available for TDD assertions (`assert`). You can see the en | .isNotString(*value*, *[message]*) | `assert.isNotString(2, 'val not string')` | | .isNumber(*value*, *[message]*) | `assert.isNumber(2, 'val is number')` | | .isNotNumber(*value*, *[message]*) | `assert.isNotNumber('e2e', 'val not number')` | +| .isFinite(*value*, *[message]*) | `assert.isFinite('e2e', 'val is finite')` | | .isBoolean(*value*, *[message]*) | `assert.isBoolean(true, 'val is bool')` | | .isNotBoolean(*value*, *[message]*) | `assert.isNotBoolean('true', 'val not bool')` | | .typeOf(*value*, *name*, *[message]*) | `assert.typeOf('e2e', 'string', 'val is string')` | diff --git a/source/guides/references/configuration.md b/source/guides/references/configuration.md index f1ef4aed44..a79cd4ec7f 100644 --- a/source/guides/references/configuration.md +++ b/source/guides/references/configuration.md @@ -76,10 +76,11 @@ Option | Default | Description Option | Default | Description ----- | ---- | ---- -`chromeWebSecurity` | `true` | Whether Chrome Web Security for same-origin policy and insecure mixed content is enabled. {% url 'Read more about this here' web-security %} -`userAgent` | `null` | Enables you to override the default user agent the browser sends in all request headers. User agent values are typically used by servers to help identify the operating system, browser, and browser version. See {% url "User-Agent MDN Documentation" https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent %} for example user agent values. +`chromeWebSecurity` | `true` | Whether to enable Chromium-based browser's Web Security for same-origin policy and insecure mixed content. {% url 'Read more about Web Security' web-security %}. `blacklistHosts` | `null` | A String or Array of hosts that you wish to block traffic for. {% urlHash 'Please read the notes for examples on using this.' blacklistHosts %} +`firefoxGcInterval` | `{ "runMode": 1, "openMode": null }` | Controls whether Cypress forces Firefox to run garbage collection (GC) cleanup and how frequently. During {% url "`cypress run`" command-line#cypress-run %}, the default value is `1`. During {% url "`cypress open`" command-line#cypress-open %}, the default value is `null`. See full details {% urlHash "here" firefoxGcInterval %}. `modifyObstructiveCode` | `true` | Whether Cypress will search for and replace obstructive JS code in `.js` or `.html` files. {% urlHash 'Please read the notes for more information on this setting.' modifyObstructiveCode %} +`userAgent` | `null` | Enables you to override the default user agent the browser sends in all request headers. User agent values are typically used by servers to help identify the operating system, browser, and browser version. See {% url "User-Agent MDN Documentation" https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent %} for example user agent values. ## Viewport @@ -259,6 +260,72 @@ Cypress modifies these scripts at the network level, and therefore there is a ti You can turn this option off if the application or site you're testing **does not** implement these security measures. Additionally it's possible that the patterns we search for may accidentally rewrite valid JS code. If that's the case, please disable this option. +## firefoxGcInterval + +Firefox has a {% url "known bug" https://bugzilla.mozilla.org/show_bug.cgi?id=1608501 %} where it does not run its internal garbage collection (GC) fast enough, which can lead to consuming all available system memory and crashing. You can progress on this issue {% issue 6187 'here' %}. + +Cypress prevents Firefox from crashing by forcing Firefox to run its GC cleanup routines between tests. + +Running GC is an expensive and **blocking** routine. It adds significant time to the overall run, and causes Firefox to "freeze" for the duration of GC cleanup. This causes the browser not to respond to any user input. + +Cypress runs GC cleanup during {% url "`cypress run`" command-line#cypress-run %} only because we don't expect users to interact with the browser - since this is typically run in CI. We've disabled running GC during {% url "`cypress open`" command-line#cypress-open %} because users typically interact with the browser. + +Because GC adds additional time to the overall run, we've added the amount of time this routine has taken to the bottom of the Command Log in the Test Runner. + +{% imgTag /img/guides/firefox-gc-interval-in-command-log.jpg %} + +### Configuration + +You can control how often GC cleanup runs via the `firefoxGcInterval` configuration value. + +`firefoxGcInterval` controls whether Cypress forces Firefox to run GC cleanup and how frequently. + +By default, we force GC cleanup between every test during {% url "`cypress run`" command-line#cypress-run %}, but do not run any GC cleanup during {% url "`cypress open`" command-line#cypress-open %} using the configuration value below: + +```json +{ + "firefoxGcInterval": { + "runMode": 1, + "openMode": null + } +} +``` + +You can override how often Cypress runs GC cleanup by setting the `firefoxGcInterval` config value to: + +- `null`, to disable it for both {% url "`cypress run`" command-line#cypress-run %} and {% url "`cypress open`" command-line#cypress-open %} +- a `number`, which sets the interval for both {% url "`cypress run`" command-line#cypress-run %} and {% url "`cypress open`" command-line#cypress-open %} +- an `object` to set different intervals for each mode + +**Examples** + +Turn off GC cleanup all modes + +```json +{ + "firefoxGcInterval": null +} +``` + +Run GC cleanup before every other test during {% url "`cypress run`" command-line#cypress-run %} and {% url "`cypress open`" command-line#cypress-open %} + +```json +{ + "firefoxGcInterval": 2 +} +``` + +Run GC cleanup before every 3rd test during {% url "`cypress run`" command-line#cypress-run %} and disable running GC cleanup during {% url "`cypress open`" command-line#cypress-open %}. + +```json +{ + "firefoxGcInterval": { + "runMode": 3, + "openMode": null + } +} +``` + ## Intelligent Code Completion IntelliSense is available for Cypress while editing your configuration file. {% url "Learn how to set up Intelligent Code Completion." intelligent-code-completion %} diff --git a/source/guides/references/error-messages.md b/source/guides/references/error-messages.md index ce59d7e423..7c5c99f4b3 100644 --- a/source/guides/references/error-messages.md +++ b/source/guides/references/error-messages.md @@ -353,6 +353,10 @@ While this works in practice, it's often indicative of an anti-pattern. You almo `cy` commands themselves are already promise like, and you can likely avoid the use of the separate Promise. +## {% fa fa-exclamation-triangle red %} Cypress detected that you returned a promise in a test, but also invoked a done callback. + +The version of Mocha was upgraded with Cypress 4.0. Mocha 3+ no longer allows returning a promise and invoking a done callback. Read more about it in the {% url "4.0 migration guide" migration-guide#Mocha-upgrade %}. + ## {% fa fa-exclamation-triangle red %} Passing `cy.route({stub: false})` or `cy.server({stub: false})` is now deprecated. You can safely remove: `{stub: false}`. @@ -513,7 +517,7 @@ When your application navigates to a superdomain outside of the current origin-p 2. You are testing a page that uses Single sign-on (SSO). In this case your web server is likely redirecting you between superdomains, so you receive this error message. You can likely get around this redirect problem by using {% url `cy.request()` request %} to manually handle the session yourself. -If you find yourself stuck and can't work around these issues you can set this in your {% url "configuration file (`cypress.json` by default)" configuration %}. But before doing so you should really understand and {% url 'read about the reasoning here' web-security %}. +If you find yourself stuck and can't work around these issues you can set `chromeWebSecurity` to `false` in your {% url "configuration file (`cypress.json` by default)" configuration %} when running in Chrome family browsers (this setting will not work in other browsers). Before doing so you should really understand and {% url 'read about the reasoning here' web-security %}. ```json { diff --git a/source/guides/references/migration-guide.md b/source/guides/references/migration-guide.md new file mode 100644 index 0000000000..5053f91d5c --- /dev/null +++ b/source/guides/references/migration-guide.md @@ -0,0 +1,377 @@ +--- +title: Migration Guide +--- + +# Migrating to Cypress 4.0 + +This guide details the changes and how to change your code to migrate to Cypress 4.0. + +## Mocha upgrade + +Mocha was upgraded from `2.5.3` to `7.0.1`, which includes a number of breaking changes and new features outlined in their {% url "changelog" https://github.com/mochajs/mocha/blob/master/CHANGELOG.md %}. Some changes you might notice are described below. + +### {% fa fa-warning red %} Breaking Change: invoke `done` callback and return a promise + +Starting with [Mocha 3.0.0](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md#300--2016-07-31), invoking a `done` callback *and* returning a promise in a test results in an error. + +This error originates from Mocha and is discussed at length [here](https://github.com/mochajs/mocha/pull/1320) and [here](https://github.com/mochajs/mocha/issues/2407). + +The reason is that using two different ways to signal that a test is finished is usually a mistake and there is always a way to only use one. There is a [proposal to handle this situation without erroring](https://github.com/mochajs/mocha/issues/2509) that may be released in a future version of Mocha. + +In the meantime, you can fix the error by choosing a single way to signal the end of your test's execution. + +#### Example #1 + +{% badge danger Before %} This test has a done callback and a promise + +```javascript +it('uses invokes done and returns promise', function (done) { + return codeUnderTest.doSomethingThatReturnsPromise().then((result) => { + // assertions here + done() + }) +}) +``` + +{% badge success After %} You can remove the `done` callback and return the promise instead: + +```javascript +it('uses invokes done and returns promise', function () { + return codeUnderTest.doSomethingThatReturnsPromise().then((result) => { + // assertions here + }) +}) +``` + +#### Example #2 + +{% badge danger Before %} Sometimes it might make more sense to use the `done` callback and not return a promise: + +```javascript +it('uses invokes done and returns promise', function (done) { + eventEmitter.on('change', () => { + // assertions + done() + }) + + return eventEmitter.doSomethingThatEmitsChange() +}) +``` + +{% badge success After %} In this case, you don't need to return the promise: + +```javascript +it('uses invokes done and returns promise', function (done) { + eventEmitter.on('change', () => { + // assertions + done() + }) + + eventEmitter.doSomethingThatEmitsChange() +}) +``` + +#### Example #3 + +Test functions using `async/await` automatically return a promise, so they need to be refactored to not use a `done` callback. + +{% badge danger Before %} This will cause an overspecified error. + +```javascript +it('uses async/await', async function (done) { + const eventEmitter = await getEventEmitter() + eventEmitter.on('change', () => done()) + eventEmitter.doSomethingThatEmitsChange() +}) +``` + +{% badge success After %} Update to the test code below. + +```javascript +it('uses async/await', async function () { + const eventEmitter = await getEventEmitter() + return new Promise((resolve) => { + eventEmitter.on('change', () => resolve()) + eventEmitter.doSomethingThatEmitsChange() + }) +}) +``` + +## Chai upgrade + +Chai was upgraded from `3.5.0` to `4.2.0`, which includes a number of breaking changes and new features outlined in {% url "Chai's migration guide" https://github.com/chaijs/chai/issues/781 %}. Some changes you might notice are described below. + +### {% fa fa-warning red %} Breaking Change: assertions expecting numbers + +Some assertions will now throw an error if the assertion's target or arguments are not numbers, including `within`, `above`, `least`, `below`, `most`, `increase` and `decrease`. + +```javascript +// These will now throw errors: +expect(null).to.be.within(0, 1) +expect(null).to.be.above(10) +// This will not throw errors: +expect('string').to.have.a.length.of.at.least(3) +``` + +### {% fa fa-warning red %} Breaking Change: `empty` assertions + +The `.empty` assertion will now throw when it is passed non-string primitives and functions. + +```javascript +// These will now throw TypeErrors +expect(Symbol()).to.be.empty +expect(function() {}).to.be.empty +``` + +### {% fa fa-warning red %} Breaking Change: non-existent properties + +An error will throw when a non-existent property is read. If there are typos in property assertions, they will now appear as failures. + +```javascript +// Would pass in Cypress 3 but will fail correctly in 4 +expect(true).to.be.ture +``` + +## Sinon.JS upgrade + +Sinon.JS was upgraded from `3.2.0` to `8.1.1`, which includes a number of breaking changes and new features outlined in {% url "Sinon.JS's migration guide" https://sinonjs.org/releases/latest/#migration-guides %}. Some changes you might notice are described below. + +### {% fa fa-warning red %} Breaking Change: stub non-existent properties + +An error will throw when trying to stub a non-existent property. + +```javascript +// Would pass in Cypress 3 but will fail in 4 +cy.stub(obj, 'nonExistingProperty') +``` + +### {% fa fa-warning red %} Breaking Change: `reset()` replaced by `resetHistory()` + +For spies and stubs, the `reset()` method was replaced by `resetHistory()`. + +{% badge danger Before %} Spies and stubs using `reset()`. + +```javascript +const spy = cy.spy() +const stub = cy.stub() + +spy.reset() +stub.reset() +``` + +{% badge success After %} Update spies and stubs should now use `resetHistory()`. + +```javascript +const spy = cy.spy() +const stub = cy.stub() + +spy.resetHistory() +stub.resetHistory() +``` + +## Plugin Event `before:browser:launch` + +Since we now support more advanced browser launch options, during `before:browser:launch` we no longer yield the second argument as an array of browser arguments and instead yield a `launchOptions` object with an `args` property. + +You can see more examples of the new `launchOptions` in use in the {% url "Browser Launch API doc" browser-launch-api %}. + +{% badge danger Before %} The second argument is no longer an array. + +```js +on('before:browser:launch', (browser, args) => { + // will print a deprecation warning telling you + // to change your code to the new signature + args.push('--another-arg') +}) +``` + +{% badge success After %} Access the `args` property off `launchOptions` + +```js +on('before:browser:launch', (browser, launchOptions) => { + launchOptions.args.push('--another-arg') +}) +``` + +## Electron options in `before:browser:launch` + +Previously, you could pass options to the launched Electron {% url "BrowserWindow" https://www.electronjs.org/docs/api/browser-window#new-browserwindowoptions %} in `before:browser:launch` by modifying the `launchOptions` object. + +Now, you must pass those options as `launchOptions.preferences`: + +{% badge danger Before %} Passing BrowserWindow options on the `launchOptions` object is no longer supported. + +```js +on('before:browser:launch', (browser, args) => { + args.darkTheme = true +}) +``` + +{% badge success After %} Pass BrowserWindow options on the `options.preferences` object instead. + +```js +on('before:browser:launch', (browser, launchOptions) => { + launchOptions.preferences.darkTheme = true +}) +``` + +## Launching Chrome Canary with `--browser` + +Before 4.0, `cypress run --browser canary` would run tests in Chrome Canary. + +Now, you must pass `--browser chrome:canary` to select Chrome Canary. + +See the {% url "docs for `cypress run --browser`" command-line#cypress-run-browser-lt-browser-name-or-path-gt %} for more information. + +{% badge danger Before %} Passing `canary` will no longer find a browser + +```shell +cypress run --browser canary +``` + +{% badge success After %} Pass `chrome:canary` to launch Chrome Canary + +```shell +cypress run --browser chrome:canary +``` + +## Chromium-based browser `family` + +We updated the {% url "Cypress browser objects" browser-launch-api %} of all Chromium-based browsers, including Electron, to have `chromium` set as their `family` field. + +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser = {}, launchOptions) => { + if (browser.family === 'electron') { + // would match Electron in 3.x + // will match no browsers in 4.0.0 + return launchOptions + } + + if (browser.family === 'chromium') { + // would match no browsers in 3.x + // will match any Chromium-based browser in 4.0.0 + // ie Chrome, Canary, Chromium, Electron, Edge (Chromium-based) + return launchOptions + } + }) +} +``` + +### Example #1 (Finding Electron) + +{% badge danger Before %} This will no longer find the Electron browser. + +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser = {}, args) => { + if (browser.family === 'electron') { + // run code for Electron browser in 3.x + return args + } + }) +} +``` + +{% badge success After %} Use `browser.name` to check for Electron + +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser = {}, launchOptions) => { + if (browser.name === 'electron') { + // run code for Electron browser in 4.0.0 + return launchOptions + } + }) +} +``` + +### Example #2 (Finding Chromium-based browsers) + +{% badge danger Before %} This will no longer find any browsers. + +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser = {}, args) => { + if (browser.family === 'chrome') { + // in 4.x, `family` was changed to 'chromium' for all Chromium-based browsers + return args + } + }) +} +``` + +{% badge success After %} Use `browser.name` and `browser.family` to select non-Electron Chromium-based browsers + +```js +module.exports = (on, config) => { + on('before:browser:launch', (browser = {}, launchOptions) => { + if (browser.family === 'chromium' && browser.name !== 'electron') { + // pass launchOptions to Chromium-based browsers in 4.0 + return launchOptions + } + }) +} +``` + +## `cy.writeFile()` yields `null` + +`cy.writeFile()` now yields `null` instead of the `contents` written to the file. This change was made to more closely align with the behavior of Node.js {% url "`fs.writeFile`" https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback %}. + +{% badge danger Before %} This assertion will no longer pass + +```js +cy.writeFile('path/to/message.txt', 'Hello World') + .then((text) => { + // Would pass in Cypress 3 but will fail in 4 + expect(text).to.equal('Hello World') // false + }) +``` + +{% badge success After %} Instead read the contents of the file + +```js +cy.writeFile('path/to/message.txt', 'Hello World') +cy.readFile('path/to/message.txt').then((text) => { + expect(text).to.equal('Hello World') // true +}) +``` + +## cy.contains() ignores invisible whitespaces + +Browsers ignore leading, trailing, duplicate whitespaces. And Cypress now does that, too. + +```html +hello +world +``` + +```javascript +cy.get('p').contains('hello world') // Fail in 3.x. Pass in 4.0.0. +cy.get('p').contains('hello\nworld') // Pass in 3.x. Fail in 4.0.0. +``` + +## Node.js 8+ support + +Cypress comes bundled with it's own {% url "Node.js version" https://github.com/cypress-io/cypress/blob/develop/.node-version %}. However, installing the `cypress` npm package uses the Node.js version installed on your system. + +Node.js 4 reached its end of life on April 30, 2018 and Node.js 6 reached its end of life on April 30, 2019. {% url "See Node's release schedule" https://github.com/nodejs/Release %}. These Node.js versions will no longer be supported when installing Cypress. The minimum Node.js version supported to install Cypress is Node.js 8. + +## CJSX is no longer supported + +Cypress no longer supports CJSX (CoffeeScript + JSX), because the library used to transpile it is no longer maintained. + +If you need CJSX support, you can use a pre-2.x version of the Browserify preprocessor. + +```shell +npm install @cypress/browserify-preprocessor@1.1.2 +``` + +```javascript +// cypress/plugins/index.js +const browserify = require('@cypress/browserify-preprocessor') + +module.exports = (on) => { + on('file:preprocessor', browserify()) +} +``` diff --git a/source/guides/references/roadmap.md b/source/guides/references/roadmap.md index 703eca5528..7e56e5f7f8 100644 --- a/source/guides/references/roadmap.md +++ b/source/guides/references/roadmap.md @@ -10,7 +10,6 @@ Our team is always planning and working on really "big" upcoming features. Prior Status | Feature | Issue | PR ---------------------| -----------------------------------|-------------------|--- -*Work in progress* | **Firefox support** | {% issue 1096 %} | {% PR 1359 %} *Work in progress* | **Full network layer stubbing** | {% issue 687 %} | {% PR 4176 %} *Work in progress* | **Improve Test Runner errors** | {% issue 3762 %} | {% PR 3930 %} *Work in progress* | **Testing Electron Apps** | {% issue 2072 %} | @@ -22,4 +21,4 @@ Status | Feature | Issue | ## Dashboard Service -Please see our official {% url "Dashboard Product Board" https://portal.productboard.com/cypress-io/1-cypress-dashboard %}. \ No newline at end of file +Please see our official {% url "Dashboard Product Board" https://portal.productboard.com/cypress-io/1-cypress-dashboard %}. diff --git a/source/guides/references/trade-offs.md b/source/guides/references/trade-offs.md index 9c86eeda36..c0d696c138 100644 --- a/source/guides/references/trade-offs.md +++ b/source/guides/references/trade-offs.md @@ -29,7 +29,6 @@ Many of these issues are currently being worked on or are on our {% url "Roadmap - {% issue 170#issuecomment-340012621 "Testing file uploads is application specific." %} - {% issue 433#issuecomment-280465552 "Testing file downloads is application specific." %} - {% issue 685 "iframe support is somewhat limited, but does work." %} -- {% issue 310 "There is no cross browser support other than Chrome and Electron." %} - {% issue 95#issuecomment-281273126 "You cannot use `cy.route()` on `window.fetch` but there is a workaround." %} See the implementation in {% url "this recipe." https://github.com/cypress-io/cypress-example-recipes/tree/master/examples/stubbing-spying__window-fetch/cypress/integration %} - {% issue 144 "There is no shadow DOM support, but there are workarounds." %} See {% url "this comment." https://github.com/cypress-io/cypress/issues/830#issuecomment-449411701 %} diff --git a/source/guides/tooling/plugins-guide.md b/source/guides/tooling/plugins-guide.md index 01ee240078..5914d3ed9b 100644 --- a/source/guides/tooling/plugins-guide.md +++ b/source/guides/tooling/plugins-guide.md @@ -79,7 +79,7 @@ You can use the `task` event to do things like: - Manipulating a database (seeding, reading, writing, etc.) - Storing state in Node that you want persisted (since the driver is fully refreshed on visits) - Performing parallel tasks (like making multiple http requests outside of Cypress) -- Running an external process (like spinning up a Webdriver instance of another browser like Firefox, Safari, or puppeteer) +- Running an external process (like spinning up a Webdriver instance of another browser like Safari or puppeteer) # List of plugins diff --git a/source/guides/tooling/typescript-support.md b/source/guides/tooling/typescript-support.md index d1b6e7b27a..675efe6f17 100644 --- a/source/guides/tooling/typescript-support.md +++ b/source/guides/tooling/typescript-support.md @@ -113,6 +113,23 @@ it('works', () => { If you extend Cypress assertions, you can extend the assertion types to make the TypeScript compiler understand the new methods. See the {% url "Recipe: Adding Chai Assertions" recipes#Fundamentals %} for instructions. +## Types for plugins + +You can utilize Cypress's type declarations in your {% url "plugins file" plugins-guide %} by annotating it like the following: + +```javascript +// cypress/plugins/index.js + +/// + +/** + * @type {Cypress.PluginConfig} + */ +module.exports = (on, config) => { + +} +``` + ## Additional information See the excellent advice on {% url "setting Cypress using TypeScript" https://basarat.gitbooks.io/typescript/docs/testing/cypress.html %} in the {% url "TypeScript Deep Dive" https://basarat.gitbooks.io/typescript/content/ %} e-book by {% url "Basarat Syed" https://twitter.com/basarat %}. Take a look at {% url "this video" https://www.youtube.com/watch?v=1Vr1cAN_CLA %} Basarat has recorded and the accompanying repo {% url basarat/cypress-ts https://github.com/basarat/cypress-ts %}. diff --git a/themes/cypress/languages/en.yml b/themes/cypress/languages/en.yml index 0bded88fc3..ae05bd3340 100644 --- a/themes/cypress/languages/en.yml +++ b/themes/cypress/languages/en.yml @@ -51,6 +51,7 @@ sidebar: parallelization: Parallelization environment-variables: Environment Variables launching-browsers: Launching Browsers + cross-browser-testing: Cross Browser Testing custom-commands: Custom Commands web-security: Web Security references: References @@ -62,6 +63,7 @@ sidebar: best-practices: Best Practices trade-offs: Trade-offs changelog: Changelog + migration-guide: Migration Guide roadmap: Roadmap tooling: Tooling intelligent-code-completion: Intelligent Code Completion @@ -175,6 +177,7 @@ sidebar: cypress-api: Cypress API config: config env: env + isbrowser: isBrowser iscy: isCy custom-commands: Commands cookies: Cookies diff --git a/themes/cypress/languages/ja.yml b/themes/cypress/languages/ja.yml index a488b93dad..a1b64b25a0 100644 --- a/themes/cypress/languages/ja.yml +++ b/themes/cypress/languages/ja.yml @@ -51,6 +51,7 @@ sidebar: parallelization: Parallelization environment-variables: 環境変数 launching-browsers: ブラウザーを起動する + cross-browser-testing: クロスブラウザテスト custom-commands: カスタムコマンド web-security: ウェブセキュリティー references: 参考 @@ -62,6 +63,7 @@ sidebar: best-practices: ベストプラクティス trade-offs: トレードオフ changelog: 変更履歴 + migration-guide: Migration Guide roadmap: ロードマップ tooling: ツール intelligent-code-completion: コード自動補完 @@ -175,6 +177,7 @@ sidebar: cypress-api: Cypress API config: config env: env + isbrowser: isBrowser iscy: isCy custom-commands: Commands cookies: Cookies diff --git a/themes/cypress/languages/pt-br.yml b/themes/cypress/languages/pt-br.yml index e024c2e5e6..c56d034473 100644 --- a/themes/cypress/languages/pt-br.yml +++ b/themes/cypress/languages/pt-br.yml @@ -51,6 +51,7 @@ sidebar: parallelization: Paralelização environment-variables: Variáveis de Ambiente launching-browsers: Iniciando navegadores + cross-browser-testing: Cross Browser Testing custom-commands: Comandos Customizados web-security: Segurança Web references: Referências @@ -62,6 +63,7 @@ sidebar: best-practices: Boas Práticas trade-offs: Trade-offs changelog: Changelog + migration-guide: Migration Guide roadmap: Roteiro tooling: Ferramentas intelligent-code-completion: Conclusão Inteligente de Código @@ -175,6 +177,7 @@ sidebar: cypress-api: Cypress API config: config env: env + isbrowser: isBrowser iscy: isCy custom-commands: Commands cookies: Cookies diff --git a/themes/cypress/languages/ru.yml b/themes/cypress/languages/ru.yml index fc23c3db41..daf49be6b9 100644 --- a/themes/cypress/languages/ru.yml +++ b/themes/cypress/languages/ru.yml @@ -51,6 +51,7 @@ sidebar: parallelization: Параллелизация environment-variables: Переменные среды launching-browsers: Запуск браузеров + cross-browser-testing: Cross Browser Testing custom-commands: Пользовательские команды web-security: Web-безопасность references: Ссылки @@ -62,6 +63,7 @@ sidebar: best-practices: Лучшие практики trade-offs: Компромиссы changelog: Изменения в продукте + migration-guide: Migration Guide roadmap: Карта проекта tooling: Утилиты intelligent-code-completion: Интеллектуальное завершение кода @@ -175,6 +177,7 @@ sidebar: cypress-api: Cypress API config: config env: env + isbrowser: isBrowser iscy: isCy custom-commands: Commands cookies: Cookies diff --git a/themes/cypress/languages/zh-cn.yml b/themes/cypress/languages/zh-cn.yml index 42c08b97ff..8db469fe9b 100644 --- a/themes/cypress/languages/zh-cn.yml +++ b/themes/cypress/languages/zh-cn.yml @@ -53,6 +53,7 @@ sidebar: parallelization: 并行化 environment-variables: 环境变量 launching-browsers: 启动浏览器 + cross-browser-testing: 跨浏览器测试 custom-commands: 自定义命令 web-security: Web安全 references: 参考 @@ -64,6 +65,7 @@ sidebar: best-practices: 最佳实践 trade-offs: 取舍 changelog: 更新日志 + migration-guide: Migration Guide roadmap: 路线图 tooling: 工具 intelligent-code-completion: 代码智能补全 @@ -177,6 +179,7 @@ sidebar: cypress-api: Cypress API config: config env: env + isbrowser: isBrowser iscy: isCy custom-commands: Commands cookies: Cookies diff --git a/themes/cypress/source/css/_partial/page.scss b/themes/cypress/source/css/_partial/page.scss index 522d4c594e..590cf308f1 100644 --- a/themes/cypress/source/css/_partial/page.scss +++ b/themes/cypress/source/css/_partial/page.scss @@ -101,6 +101,11 @@ a.article-edit-link { margin: 25px 0; word-wrap: break-word; font-family: $font-sans; + + .badge { + position: relative; + top: -2px; + } } ol { @@ -456,6 +461,10 @@ a.article-edit-link { } } + p>img { + margin: 0; + } + &>h1, &>h2, &>h3 { margin-top: 15px; padding-top: 0; diff --git a/themes/cypress/source/img/api/contains/contains-pre-exception.png b/themes/cypress/source/img/api/contains/contains-pre-exception.png new file mode 100644 index 0000000000..beb8dfda63 Binary files /dev/null and b/themes/cypress/source/img/api/contains/contains-pre-exception.png differ diff --git a/themes/cypress/source/img/guides/browser-list-dropdown.png b/themes/cypress/source/img/guides/browser-list-dropdown.png new file mode 100644 index 0000000000..0894b07e63 Binary files /dev/null and b/themes/cypress/source/img/guides/browser-list-dropdown.png differ diff --git a/themes/cypress/source/img/guides/chrome-web-security-stdout-warning.jpg b/themes/cypress/source/img/guides/chrome-web-security-stdout-warning.jpg new file mode 100644 index 0000000000..e8fc202787 Binary files /dev/null and b/themes/cypress/source/img/guides/chrome-web-security-stdout-warning.jpg differ diff --git a/themes/cypress/source/img/guides/cross-browser-testing/cypress-browser-selector.png b/themes/cypress/source/img/guides/cross-browser-testing/cypress-browser-selector.png new file mode 100644 index 0000000000..ac2a494a59 Binary files /dev/null and b/themes/cypress/source/img/guides/cross-browser-testing/cypress-browser-selector.png differ diff --git a/themes/cypress/source/img/guides/firefox-gc-interval-in-command-log.jpg b/themes/cypress/source/img/guides/firefox-gc-interval-in-command-log.jpg new file mode 100644 index 0000000000..36cc647b86 Binary files /dev/null and b/themes/cypress/source/img/guides/firefox-gc-interval-in-command-log.jpg differ diff --git a/themes/cypress/source/img/guides/select-browser.png b/themes/cypress/source/img/guides/select-browser.png deleted file mode 100644 index 6762c40700..0000000000 Binary files a/themes/cypress/source/img/guides/select-browser.png and /dev/null differ diff --git a/themes/cypress/source/img/guides/troubleshooting-cypress-process-profiler-cli.jpg b/themes/cypress/source/img/guides/troubleshooting-cypress-process-profiler-cli.jpg new file mode 100644 index 0000000000..01627b6016 Binary files /dev/null and b/themes/cypress/source/img/guides/troubleshooting-cypress-process-profiler-cli.jpg differ
Hello, World !
hello +world