Merge pull request #4012 from cypress-io/8.0-release

Author: flotwig

content/_changelogs/8.0.0.md

@@ -0,0 +1,78 @@
+## 8.0.0
+
+_Released 07/19/2021_
+
+**Summary:**
+
+We've made some updates to ensure a consistent run experience across browsers.
+Now all browsers run via `cypress run` run headlessly, with a device pixel ratio
+of 1, and a screen size of 1280x720 by default.
+
+**Breaking Changes:**
+
+**<Icon name="exclamation-triangle" color="red"></Icon> Please read our
+[Migration Guide](/guides/references/migration-guide) which explains the changes
+in more detail and how to change your code to migrate to Cypress 8.0.**
+
+- When running `cypress run` previous to 8.0, some browsers would launch headed
+  while others were launched headless by default. Cypress now runs all browsers
+  during `cypress run` as headless by default. Addresses
+  [#16832](https://github.com/cypress-io/cypress/issues/16832).
+- The default screen size when running a headless browser has been reverted back
+  to 1280x720 pixels (pre 7.0 behavior). Addresses
+  [#16853](https://github.com/cypress-io/cypress/issues/16853).
+- When running the `--headless` Chrome browser via `cypress run`, the device
+  pixel ratio will now be 1 by default, matching the behavior of all other
+  browsers. This behavior can be overridden through the
+  [browser launch API](/api/plugins/browser-launch-api#Override-the-device-pixel-ratio).
+  Addresses [#17375](https://github.com/cypress-io/cypress/issues/17375).
+- Cypress now enforces version checks for browser launching and will error
+  during `cypress run` and not allow opening the browser in `cypress open` when
+  attempting to open unsupported browser versions. Cypress supports Chrome >=
+  64, Firefox >= 86, and Edge >= 79. Addressed in
+  [#17355](https://github.com/cypress-io/cypress/pull/17355).
+- Arguments returned from a chained function will no longer incorrectly be of
+  type `jQuery` and instead have an `any` type. Fixes
+  [#16669](https://github.com/cypress-io/cypress/issues/16669).
+- The `Cypress.ConfigOptions`, `Cypress.ResolvedConfigOptions` and
+  `Cypress.RuntimeConfigOption` types have been updated so that `ConfigOptions`
+  match the JSON schema. Addressed in
+  [#17251](https://github.com/cypress-io/cypress/pull/17251).
+
+**Features:**
+
+- You can now configure certificate authority (CA) and client certificates to
+  use within tests on a per-URL basis via a `clientCertificates` configuration
+  option. See [Client certificates](/guides/references/client-certificates) for
+  more detail.
+- Setting the environment variable `ELECTRON_RUN_AS_NODE` now starts Cypress as
+  a normal Node.js process rather than an Electron process. See
+  [Running headless tests without Xvfb](/guides/continuous-integration/introduction#Running-headless-tests-without-Xvfb)
+  for more details. Addresses
+  [#16505](https://github.com/cypress-io/cypress/issues/16505).
+
+**Bugfixes:**
+
+- `console.log` and `console.error` called within the
+  [plugins file](/guides/core-concepts/writing-and-organizing-tests.html#Plugin-files)
+  will now be captured in the `stdout` sent to the Cypress Dashboard, making it
+  visible in Output logs in the Dashboard. Fixes
+  [#7434](https://github.com/cypress-io/cypress/issues/7434).
+- There are several fixes for [`cy.intercept()`](/api/commands/intercept)
+  including:
+  - The `times` option now works correctly with `req.continue`. Fixes
+    [#16821](https://github.com/cypress-io/cypress/issues/16821).
+  - `localhost` is now accepted as a valid `hostname` in the `RouteMatcher`.
+    Fixes [#17015](https://github.com/cypress-io/cypress/issues/17015).
+  - `delay` now works correctly with a `statusCode` of 204. Fixes
+    [#15188](https://github.com/cypress-io/cypress/issues/15188).
+- When using the experimental
+  [Cypress Studio](/guides/core-concepts/cypress-studio), there should be a
+  reduced occurrence of "Studio failed to save commands" error messages. Fixes
+  [#14767](https://github.com/cypress-io/cypress/issues/14767).
+- [`cy.invoke()`](/api/commands/invoke) now retains the proper `this` context on
+  nested object methods. Fixes
+  [#3871](https://github.com/cypress-io/cypress/issues/3871).
+- We no longer trigger unnecessary snapshot re-renders when hovering over the
+  Command Log. Fixes
+  [#17257](https://github.com/cypress-io/cypress/issues/17257).

content/_data/sidebar.json

@@ -312,6 +312,10 @@
               "title": "Configuration",
               "slug": "configuration"
             },
+            {
+              "title": "Client Certificates",
+              "slug": "client-certificates"
+            },
             {
               "title": "Proxy Configuration",
               "slug": "proxy-configuration"
@@ -768,10 +772,6 @@
               "title": "Cookies",
               "slug": "cookies"
             },
-            {
-              "title": "Keyboard",
-              "slug": "keyboard-api"
-            },
             {
               "title": "Screenshot",
               "slug": "screenshot-api"

content/api/plugins/browser-launch-api.md

@@ -2,13 +2,19 @@
 title: Browser Launch API
 ---
 
-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 from your [pluginsFile](/guides/tooling/plugins-guide).
+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 from your [pluginsFile](/guides/tooling/plugins-guide).
 
 ## Syntax
 
 <Alert type="warning">
 
-⚠️ This code is part of the [plugins file](/guides/core-concepts/writing-and-organizing-tests.html#Plugin-files) and thus executes in the Node environment. You cannot call `Cypress` or `cy` commands in this file, but you do have the direct access to the file system and the rest of the operating system.
+⚠️ This code is part of the
+[plugins file](/guides/core-concepts/writing-and-organizing-tests.html#Plugin-files)
+and thus executes in the Node environment. You cannot call `Cypress` or `cy`
+commands in this file, but you do have the direct access to the file system and
+the rest of the operating system.
 
 </Alert>
 
@@ -37,7 +43,8 @@ An object describing the browser being launched, with the following properties:
 
 **<Icon name="angle-right"></Icon> launchOptions** **_(object)_**
 
-Options that can be modified to control how the browser is launched, with the following properties:
+Options that can be modified to control how the browser is launched, with the
+following properties:
 
 | Property      | Type       | Description                                                                                                                                                                                                                                  |
 | ------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -49,11 +56,16 @@ Options that can be modified to control how the browser is launched, with the fo
 
 ### Modify browser launch arguments, preferences, and extensions
 
-Using your [pluginsFile](/guides/tooling/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).
+Using your [pluginsFile](/guides/tooling/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` object, which gives you information about the browser, and the `launchOptions` object, which allows you to modify how the browser is launched.
+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.
 
-The returned `launchOptions` object will become the new launch options for the browser.
+The returned `launchOptions` object will become the new launch options for the
+browser.
 
 #### Modify browser launch arguments:
 
@@ -114,7 +126,8 @@ Here are preferences available for the currently supported browsers:
 
 - [Chromium-based browsers](https://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/pref_names.cc?view=markup)
 - [Electron](https://github.com/electron/electron/blob/master/docs/api/browser-window.md#new-browserwindowoptions)
-- Firefox: visit `about:config` URL within your Firefox browser to see all available preferences.
+- Firefox: visit `about:config` URL within your Firefox browser to see all
+  available preferences.
 
 ```js
 // cypress/plugins/index.js
@@ -149,9 +162,15 @@ module.exports = (on, config) => {
 
 ### Modify Electron app switches
 
-Cypress Test Runner is an Electron application, and its behavior (and the behavior of the bundled-in Electron browser) can be customized using command line switches. The supported switches depend on the Electron version, see [Electron documentation](https://www.electronjs.org/docs/api/command-line-switches).
+Cypress Test Runner is an Electron application, and its behavior (and the
+behavior of the bundled-in Electron browser) can be customized using command
+line switches. The supported switches depend on the Electron version, see
+[Electron documentation](https://www.electronjs.org/docs/api/command-line-switches).
 
-You can pass Electron-specific launch arguments using the `ELECTRON_EXTRA_LAUNCH_ARGS` environment variable. For example, to disable HTTP browser cache and ignore certificate errors, you can set the environment variables before running Cypress like below:
+You can pass Electron-specific launch arguments using the
+`ELECTRON_EXTRA_LAUNCH_ARGS` environment variable. For example, to disable HTTP
+browser cache and ignore certificate errors, you can set the environment
+variables before running Cypress like below:
 
 #### Linux/OSX
 
@@ -165,23 +184,36 @@ export ELECTRON_EXTRA_LAUNCH_ARGS=--disable-http-cache --lang=es
 set ELECTRON_EXTRA_LAUNCH_ARGS=--disable-http-cache --lang=es
 ```
 
-Cypress already sets some the Electron command line switches internally. See file [packages/server/lib/environment.js](https://github.com/cypress-io/cypress/blob/develop/packages/server/lib/environment.js). There is no way to see all currently set switches after Electron's launch.
+Cypress already sets some the Electron command line switches internally. See
+file
+[packages/server/lib/environment.js](https://github.com/cypress-io/cypress/blob/develop/packages/server/lib/environment.js).
+There is no way to see all currently set switches after Electron's launch.
 
 ### See all Chrome browser switches
 
-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.
+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.
 
 <DocsImage src="/img/api/chrome-switches.png" alt="See all Chrome switches" ></DocsImage>
 
 ## Examples
 
 ### Set screen size when running headless
 
-When a browser runs headless, there is no physical display. You can override the default screen size of 1920x1080 when running headless as shown below. This will affect the size of screenshots and videos taken during the run.
+When a browser runs headless, there is no physical display. You can override the
+default screen size of 1280x720 when running headless as shown below. This will
+affect the size of screenshots and videos taken during the run.
 
 <Alert type="warning">
 
-This setting changes the display size of the screen and does not affect the `viewportWidth` and `viewportHeight` set in the [configuration](/guides/references/configuration). The `viewportWidth` and `viewportHeight` only affect the size of the application under test displayed inside the Test Runner. Read the blog post [Generate High-Resolution Videos and Screenshots](https://www.cypress.io/blog/2021/03/01/generate-high-resolution-videos-and-screenshots/) for details.
+This setting changes the display size of the screen and does not affect the
+`viewportWidth` and `viewportHeight` set in the
+[configuration](/guides/references/configuration). The `viewportWidth` and
+`viewportHeight` only affect the size of the application under test displayed
+inside the Test Runner. Read the blog post
+[Generate High-Resolution Videos and Screenshots](https://www.cypress.io/blog/2021/03/01/generate-high-resolution-videos-and-screenshots/)
+for details.
 
 </Alert>
 
@@ -219,6 +251,24 @@ module.exports = (on, config) => {
 }
 ```
 
+### Override the device pixel ratio
+
+```js
+// cypress/plugins/index.js
+module.exports = (on, config) => {
+  on('before:browser:launch', (browser, launchOptions) => {
+    if (browser.name === 'chrome' && browser.isHeadless) {
+      // force screen to behave like retina
+      // when running Chrome headless browsers
+      // (2560x1440 in size by default)
+      launchOptions.args.push('--force-device-scale-factor=2')
+    }
+
+    return launchOptions
+  })
+}
+```
+
 ### Start fullscreen
 
 ```js
@@ -242,11 +292,14 @@ module.exports = (on, config) => {
 
 ### Use fake video for webcam testing
 
-By default, Cypress passes the Chrome command line switch to enable a fake video for a media stream. This is to better enable testing webcam functionality without having to have the necessary hardware to test.
+By default, Cypress passes the Chrome command line switch to enable a fake video
+for a media stream. This is to better enable testing webcam functionality
+without having to have the necessary hardware to test.
 
 <DocsImage src="/img/api/browser-launch-fake-video.gif" alt="Enable fake video for testing" ></DocsImage>
 
-You can however send your own video file for testing by passing a Chrome command line switch pointing to a video file.
+You can however send your own video file for testing by passing a Chrome command
+line switch pointing to a video file.
 
 ```js
 // cypress/plugins/index.js
@@ -269,7 +322,8 @@ module.exports = (on, config) => {
 
 ### Support unique file download mime types
 
-Cypress supports a myriad of mime types when testing file downloads, but in case you have a unique one, you can add support for it.
+Cypress supports a myriad of mime types when testing file downloads, but in case
+you have a unique one, you can add support for it.
 
 ```js
 module.exports = (on) => {
@@ -299,7 +353,8 @@ module.exports = (on) => {
 
 ### Set a Firefox flag
 
-If we need to set a particular Firefox flag, like `browser.send_pings` we can do it via preferences
+If we need to set a particular Firefox flag, like `browser.send_pings` we can do
+it via preferences
 
 ```js
 module.exports = (on) => {
@@ -313,7 +368,8 @@ module.exports = (on) => {
 }
 ```
 
-The above example comes from the blog post [How to Test Anchor Ping](https://glebbahmutov.com/blog/anchor-ping/).
+The above example comes from the blog post
+[How to Test Anchor Ping](https://glebbahmutov.com/blog/anchor-ping/).
 
 ## History
 

content/guides/continuous-integration/introduction.md

@@ -453,6 +453,16 @@ Cypress internally passes these Xvfb arguments, but if you are spawning your own
 
 </Alert>
 
+### Running headless tests without Xvfb
+
+Chromium based browsers and Firefox can spawn without Xvfb when run via the `--headless` flag. If you're testing against either of those browsers using the `--browser` flag, you can opt out of Cypress spawning an X11 server by setting the environment variable [`ELECTRON_RUN_AS_NODE=1`](https://www.electronjs.org/docs/api/environment-variables#electron_run_as_node).
+
+<Alert type="warning">
+
+Electron cannot be run without an X11 server. Cypress's default browser is Electron and won't be able to launch if you set this environment variable. Likewise, Cypress's interactive mode (running via `cypress open`) is run via Electron and cannot be opened without an X11 server.
+
+</Alert>
+
 ### Colors
 
 If you want colors to be disabled, you can pass the `NO_COLOR` environment variable to disable colors. You may want to do this if ASCII characters or colors are not properly formatted in your CI.