Merge pull request #2783 from cypress-io/4.6.0-release

source/_changelogs/4.2.0.md

@@ -9,7 +9,7 @@
 
 **Bugfixes:**
 
-- We fixed a regression in {% url "3.8.3" changelog-3-8-3 %}  where HTTPS requests could experience slowdown. Fixes {% issue 6659 %}.
+- We fixed a regression in {% url "3.8.3" changelog-3-8-3 %} where HTTPS requests could experience slowdown. Fixes {% issue 6659 %}.
 - We now detect some installations of Firefox that were previously undetected. Fixes {% issue 6669 %}.
 - We fixed a race condition where an asynchronous error could fail to be caught when running the plugins file process. Fixes {% issue 6570 %}.
 - We now more thoroughly ensure the parent of an element exists when recursively calling actionability checks in order to prevent some maximum call stack errors. Fixes {% issue 6707 %}.

source/_changelogs/4.6.0.md

@@ -0,0 +1,50 @@
+# 4.6.0
+
+*Released 5/20/2020*
+
+**Features:**
+
+- {% url "Errors" debugging#Errors %} in the Test Runner now display a code frame to preview where the failure occurred with the relevant file, line number, and column number highlighted. Clicking on the file link will open the file in your {% url "preferred file opener" IDE-integration#File-Opener-Preference %} and highlight the line and column in editors that support it. Addresses {% issue 3762 %}.
+- Cypress now utilizes {% url "source maps" debugging#Source-maps %} to enhance the error experience. Stack traces are translated so that your source files are shown instead of the generated file that is loaded by the browser. Cypress will include an inline source map in your spec file. If you {% url "modify the preprocessor" preprocessors-api %}, ensure that inline source maps are enabled to get the same experience. Users of `@cypress/webpack-preprocessor` should upgrade to v5.4.1 or later of the package which will correctly inline source maps. Addresses {% issue 881 %}, {% issue 1761 %} and {% issue 3966 %}.
+- Cypress now enables AST-based JS/HTML rewriting when setting the {% url "`experimentalSourceRewriting`" experiments %} configuration option to `true`. Addresses {% issue 5273 %}.
+- Number arguments passed to `have.text`, `have.id`, `have.data`, `have.value`, and `have.attr` {% url "assertions chainers" assertions#Chai-jQuery %} are now automatically cast to strings for comparison. Addresses {% issue 7314 %}.
+
+**Bugfixes:**
+
+- Default {% url "TypeScript" typescript-support %} options are now set to `module: commonJS` which Node.js and the browser expect. This fixes a situation where setting a different module in a `tsconfig.json` would cause errors to throw if you had `export`, `import` or `async` keywords in your code. Fixes {% issue 7005 %}, {% issue 7011 %}, {% issue 7043 %}, and {% issue 7151 %}.
+- When {% url "`experimentalSourceRewriting`" experiments %} is enabled, setting `location` or `location.href` to a relative href, or using `location.replace` or `location.assign` with a relative href will no longer navigate the AUT to the wrong URL. Fixes {% issue 3975 %} and {% issue 3994 %}.
+- When {% url "`experimentalSourceRewriting`" experiments %} is enabled, the use of `window.top` and `window.parent` will no longer cause the AUT to break out of the Cypress iframe. Fixes {% issue 5271 %} and {% issue 1467 %}.
+- When {% url "`experimentalSourceRewriting`" experiments %} is enabled, calls to `window.frames`, `window.parent.frames`, and other `frames` will no longer point to the wrong reference after being proxied through Cypress. Fixes {% issue 2664 %}.
+- When {% url "`experimentalSourceRewriting`" experiments %} is enabled, scripts using the `integrity` attribute for sub-resource integrity (SRI) will now load after being proxied through Cypress. Fixes {% issue 2393 %}.
+- When {% url "`experimentalSourceRewriting`" experiments %} is enabled, the use of `document.location` to set the URL will no longer navigate the AUT to the wrong URL. Fixes {% issue 7402 %}.
+- Type definitions will no longer conflict when running Cypress in a project with Jest. Fixes {% issue 3536 %}.
+- We increased the timeout for launching Firefox from 2.5 seconds to 50 seconds. Previously, users hitting this limit would encounter a "cannot open socket" error; now, the error will be wrapped. Fixes {% issue 7159 %}.
+- {% url "`.click`" click %} will now click in the correct coordinates when either x or y coordinate options are zero. Fixes {% issue 7319 %}.
+- Cypress no longer displays `onError is not a function` when a browser can't connect. Fixes {% issue 7217 %}.
+- You can now pass the `force: true` option to {% url "`.select()`" select %} to select options within a disabled `<select>`. Addresses {% issue 107 %}.
+- We now throw an error when attempting to {% url "`.select()`" select %} an `<option>` within a disabled `<optgroup>`. Fixes {% issue 7226 %}.
+- We fixed a regression in {% url "4.3.0" changelog-4-3-0 %} where the message output during errors were not formatted correctly. Fixes {% issue 6924 %}.
+- Using {% url "`Cypress._.capitalize`" _ %} now correctly behaves the same as Lodash's capitalize method. Fixes {% issue 7222 %}.
+- When {% url "`experimentalComponentTesting`" experiments#Component-Testing %} is enabled, clicking on a component spec now watches the correct file without assuming it is an integration file. Fixes {% issue 7244 %}.
+- Firefox video recording no longer crashes Cypress when running very short spec files. Fixes {% issue 6408 %}.
+- Applications containing a DOM element with an id attribute containing 'jquery' will no longer throw an error during {% url "`cy.visit()`" visit %}. Fixes {% issue 6193 %}.
+- Long errors generated when compiling or bundling the test file are now horizontally scrollable. Fixes {% issue 6898 %}.
+
+**Misc:**
+
+- Cypress no longer requires write access to the root of the project, it instead will display a warning when no write access is given. Addresses {% issue 1281 %}.
+- We increased the timeout for launching Chrome from 20 seconds to 50 seconds. Addressed in {% PR 7372 %}.
+- We increased the timeout for macOS or Linux to exit from a `--version` command when looking for available browsers from 5 seconds to 30 seconds. Addressed in {% PR 7366 %}.
+- We improved error handling when Cypress launches Chromium-family browsers. Addresses {% issue 6518 %}.
+- We now export `Cypress.ConfigOptions` types as a partial of the full options interface. Addresses {% issue 7238 %}.
+- We're continuing to make progress in converting our codebase from CoffeeScript to JavaScript. Addresses {% issue 2690 %} in {% PR 7162 %}, {% PR 7216 %}, {% PR 7227 %}, {% PR 7320 %}, {% PR 7232 %}, and {% PR 7345 %}.
+
+**Dependency Updates:**
+
+- Upgraded `@cypress/browserify-preprocessor` from `2.2.2` to `2.2.3`. Addressed in {% PR 7291 %}.
+- Upgraded `cookie-parser` from `1.4.4` to `1.4.5`. Addressed in {% PR 7389 %}.
+- Upgraded `cypress-multi-reporters` from `1.2.4` to `1.4.0`. Addressed in {% PR 7431 %}.
+- Upgraded `electron` from `8.2.3` to `8.3.0`. Addressed in {% PR 7236 %} and {% PR 7387 %}.
+- Upgraded `image-size` from `0.7.4` to `0.8.3`. Addressed in {% PR 7236 %}.
+- Upgraded `jimp` from `0.9.3` to `0.12.0`. Addressed in {% PR 7408 %}.
+- Upgraded `return-deep-diff` from `0.3.0` to `0.4.0`. Addressed in {% PR 7292 %}.

source/_partial/errors_anatomy.md

@@ -1,7 +1,9 @@
 1. **Error name**: This is the type of the error (e.g. AssertionError, CypressError)
-2. **Error message**: This generally tells you what went wrong. It can vary in length. Some are short like in the example, while some are long, and may tell you exactly how to fix the error.
-3. **Learn more**: Some error messages contain a **Learn more** link that will take you to relevant Cypress documentation.
-4. **View stack trace**: Clicking this toggles the visibility of the stack trace. Stack traces vary in length.
-5. **Print to console button**: Click this to print the full error to your DevTools console. This will usually allow you to click on lines in the stack trace and open files in your DevTools.
+2. **Error message**: This generally tells you what went wrong. It can vary in length. Some are short like in the example, while some are long, and may tell you exactly how to fix the error. Some also contain a **Learn more** link that will take you to relevant Cypress documentation.
+3. **Learn more:** Some error messages contain a Learn more link that will take you to relevant Cypress documentation.
+4. **View stack trace**: Clicking this toggles the visibility of the stack trace. Stack traces vary in length. Clicking on a blue file path will open the file in your [preferred file opener](https://on.cypress.io/IDE-integration#File-Opener-Preference).
+5. **Code frame file**: This is usually the top line of the stack trace and it shows the file, line number, and column number that is highlighted in the code frame below. Clicking on this link will open the file in your  [preferred file opener](https://on.cypress.io/IDE-integration#File-Opener-Preference) and highlight the line and column in editors that support it.
+6. **Code frame**: This shows a snippet of code where the failure occurred, with the relevant line and column highlighted.
+7. **Print to console button**: Click this to print the full error to your DevTools console. This will usually allow you to click on lines in the stack trace and open files in your DevTools.
 
-{% imgTag /img/guides/command-failure-error.png "example command failure error" width-600 %}
+{% imgTag /img/guides/command-failure-error.png "example command failure error" %}

source/api/commands/select.md

@@ -124,13 +124,53 @@ cy.get('select')
   .should('deep.equal', ['456', '457'])
 ```
 
+## Force select
+
+### Force select a hidden `<select>`
+
+```html
+<select style="display: none;">
+  <optgroup label="Fruits">
+    <option value="banana">Banana</option>
+    <option value="apple">Apple</option>
+  <optgroup>
+</select>
+```
+
+```javascript
+cy.get('select')
+  .select('banana', { force: true })
+  .invoke('val')
+  .should('eq', 'banana')
+```
+
+### Force select a disabled `<select>`
+
+Passing `{ force: true }` to `.select()` will override the actionability checks for selecting a disabled `<select>`. However, it will not override  the actionability checks for selecting a disabled `<option>` or an option within a disabled `<optgroup>`. See {% issue 107 "this issue" %} for more detail.
+
+```html
+<select disabled>
+  <optgroup label="Veggies">
+    <option value="okra">Okra</option>
+    <option value="zucchini">Zucchini</option>
+  <optgroup>
+</select>
+```
+
+```javascript
+cy.get('select')
+  .select('okra', { force: true })
+  .invoke('val')
+  .should('eq', 'okra')
+```
+
 # Notes
 
 ## Actionability
 
 `.select()` is an action command that follows the rules {% url 'defined here' interacting-with-elements %}.
 
-However, passing `{ force: true }` to `.select()` will not override the actionability checks for selecting a disabled `<select>`, a disabled `<option>`, or an option within a disabled `<optgroup>`. See {% issue 107 "this issue" %} for more detail.
+However, passing `{ force: true }` to `.select()` will not override the actionability checks for selecting a disabled `<option>` or an option within a disabled `<optgroup>`. See {% issue 107 "this issue" %} for more detail.
 
 # Rules
 

source/faq/questions/using-cypress-faq.md

@@ -374,7 +374,7 @@ A *Record Key* is a GUID that's generated automatically by Cypress once you've {
 
 You can find your project's record key inside of the *Settings* tab in the Test Runner.
 
-{% imgTag /img/dashboard/record-key-shown-in-desktop-gui-configuration.png "Record Key in Configuration Tab" %}
+{% imgTag /img/dashboard/record-key-shown-in-desktop-gui-configuration.jpg "Record Key in Configuration Tab" %}
 
 For further detail see the {% url Identification projects#Identification %} section of the {% url "Dashboard Service" dashboard-introduction%} docs.
 

source/guides/core-concepts/interacting-with-elements.md

@@ -220,5 +220,5 @@ We will NOT perform these:
 In summary, `{ force: true }` skips the checks, and it will always fire the event at the desired element.
 
 {% note warning "force `.select()` disabled options" %}
-Passing `{ force: true }` to {% url "`.select()`" select %} will not override the actionability checks for selecting a disabled `<select>`, a disabled `<option>`, or an option within a disabled `<optgroup>`. See {% issue 107 "this issue" %} for more detail.
+Passing `{ force: true }` to {% url "`.select()`" select %} will not override the actionability checks for selecting a disabled `<option>` or an option within a disabled `<optgroup>`. See {% issue 107 "this issue" %} for more detail.
 {% endnote %}

source/guides/dashboard/projects.md

@@ -107,7 +107,7 @@ You can create multiple Record Keys for a project, or delete existing ones from
 
 You can also find your Record Key inside of the *Settings* tab in the Test Runner.
 
-{% imgTag /img/dashboard/record-key-shown-in-desktop-gui-configuration.png "Record Key in Configuration Tab" %}
+{% imgTag /img/dashboard/record-key-shown-in-desktop-gui-configuration.jpg "Record Key in Configuration Tab" %}
 
 # Record keys
 

source/guides/getting-started/writing-your-first-test.md

@@ -86,7 +86,7 @@ describe('My First Test', () => {
 
 Once you save again, you'll see Cypress display the failing test in red since `true` does not equal `false`.
 
-Cypress also displays the stack trace where the assertion failed (when available). To read more about the error's display, read about {% url "Debugging Errors" debugging#Errors %}.
+Cypress also displays the stack trace and the code frame where the assertion failed (when available). You can click on the blue file link to open the file where the error occurred in {% url "your preferred file opener" IDE-integration#File-Opener-Preference %}. To read more about the error's display, read about {% url "Debugging Errors" debugging#Errors %}.
 
 <!--
 To reproduce the following screenshot:

source/guides/guides/debugging.md

@@ -115,16 +115,22 @@ Sometimes tests fail. Sometimes we want them to fail, just so we know they're te
 Let's take a look at the anatomy of an error and how it is displayed in Cypress, by way of a failing test.
 
 ```js
-it('failure', () => {
-  // the center of the clicked element is hidden
+it('reroutes on users page', () => {
   cy.contains('Users').click()
+  cy.url().should('include', 'users')
 })
 ```
 
 The center of the `<li>Users</li>` element is hidden from view in our application under test, so the test above will fail. Within Cypress, an error will show on failure that includes the following pieces of information:
 
 {% partial errors_anatomy %}
 
+## Source maps
+
+Cypress utilizes source maps to enhance the error experience. Stack traces are translated so that your source files are shown instead of the generated file that is loaded by the browser. This also enables displaying code frames. Without inline source maps, you will not see code frames.
+
+By default, Cypress will include an inline source map in your spec file, so you will get the most out of the error experience. If you {% url "modify the preprocessor" preprocessors-api %}, ensure that inline source maps are enabled to get the same experience. With webpack and the {% url "webpack preprocessor" https://github.com/cypress-io/cypress-webpack-preprocessor %}, for example, set {% url "the `devtool` option" https://webpack.js.org/configuration/devtool/ %} to `inline-source-map`.
+
 # Log Cypress events
 
 Cypress emits multiple events you can listen to as shown below. {% url 'Read more about logging events in the browser here' catalog-of-events#Logging-All-Events %}.

source/guides/references/error-messages.md

@@ -113,6 +113,24 @@ describe('detachment example', () => {
 })
 -->
 
+<!--
+To reproduce the following screenshot:
+describe('detachment example', () => {
+  beforeEach(() => {
+    cy.get('body').then(($body) => {
+      const $outer = Cypress.$('<div />').appendTo($body)
+      Cypress.$('<button />').on('click', () => { $outer[0].remove() }).appendTo($outer)
+    })
+  })
+  it('detaches from dom', () => {
+    cy.get('button')
+    .click()
+    .parent()
+    .should('have.text', 'Clicked')
+  })
+})
+-->
+
 {% imgTag /img/guides/cy-method-failed-element-is-detached.png "cy.method() failed because element is detached" %}
 
 Cypress errors because it can't interact with "dead" elements - much like a real user could not do this either. Understanding how this happens is very important - and it is often preventable.

source/guides/references/experiments.md

@@ -16,6 +16,7 @@ Option | Default | Description
 ----- | ---- | ----
 `experimentalGetCookiesSameSite` | `false` | If `true`, Cypress will add `sameSite` values to the objects yielded from {% url "`cy.setCookie()`" setcookie %}, {% url "`cy.getCookie()`" getcookie %}, and {% url "`cy.getCookies()`" getcookies %}. This will become the default behavior in Cypress 5.0.
 `experimentalComponentTesting` | `false` | When set to `true`, Cypress allows you to execute component tests using framework-specific adaptors. By default  `cypress/component` is the path for component tests. You can change this setting by setting the `componentFolder` configuration option. For more details see the {% url "cypress-react-unit-test" https://github.com/bahmutov/cypress-react-unit-test %} and {% url "cypress-vue-unit-test" https://github.com/bahmutov/cypress-vue-unit-test %} repos.
+`experimentalSourceRewriting` | `false` | Enables AST-based JS/HTML rewriting. This may fix issues caused by the existing regex-based JS/HTML replacement algorithm. See {% issue 5273 %} for details.
 
 # Component Testing
 
@@ -57,6 +58,7 @@ Code coverage | ✅ / maybe | ✅
 \* Most common libraries: React Testing Library, Enzyme, Vue Testing Library, Vue Test Utils
 
 {% history %}
+{% url "4.6.0" changelog#4-6-0 %} | Added support for `experimentalSourceRewriting`.
 {% url "4.5.0" changelog#4-5-0 %} | Added support for `experimentalComponentTesting`.
 {% url "4.3.0" changelog#4-3-0 %} | Added support for `experimentalGetCookiesSameSite`.
 {% endhistory %}

source/guides/references/proxy-configuration.md

@@ -171,4 +171,4 @@ Your current proxy settings can be viewed from within the Cypress Test Runner. F
 2. Click the "Settings" tab.
 3. Click the "Proxy Settings" section to expand it and view the proxy settings that Cypress is currently using.
 
-{% imgTag /img/guides/proxy-configuration.png "Proxy configuration in the Desktop app" %}
+{% imgTag /img/guides/test-runner-settings-proxy-configuration.jpg "Proxy configuration in the Desktop app" %}

source/guides/tooling/IDE-integration.md

@@ -2,6 +2,26 @@
 title: IDE Integration
 ---
 
+# File Opener Preference
+
+When clicking on a file path from the {% url "Test Runner" test-runner %} in an {% url "error stack trace or a code frame" debugging#Errors %}, Cypress will attempt to open the file on your system. If the editor supports inline highlighting of the file, the file will open with the cursor located on the line and column of interest.
+
+{% imgTag /img/guides/file-opener-ide-go-to-line.gif "Open file at line in VS Code" %}
+
+The first time you click a file path, Cypress will prompt you to select which location you prefer to open the file. You can choose to open it in your:
+
+- File system (e.g. Finder on MacOS, File Explore on Windows)
+- An IDE located on your system
+- A specified application path
+
+{% note warning %}
+Cypress attempts to find available file editors on your system and display those as options. If your preferred editor is not list, you can specify the (full) path to it by selecting **Other**. Cypress will make every effort to open the file, *but it is not guaranteed to work with every application*.
+{% endnote %}
+
+After setting your file opener preference, any files will automatically open in your selected application without prompting you to choose. If you want to change your selection, you can do so in the **Settings** tab of the Cypress Test Runner by clicking under **File Opener Preference**.
+
+{% imgTag /img/guides/file-opener-preference-settings-tab.png "screenshot of Test Runner settings tab with file opener preference panel" %}
+
 # Extensions & Plugins
 
 There are many third-party IDE extensions and plugins to help integrate your IDE with Cypress.