6.3.0 Release

source/_changelogs/6.3.0.md

@@ -0,0 +1,32 @@
+# 6.3.0
+
+*Released 1/19/2021*
+
+**Features:**
+
+- **Cypress Studio** provides a visual way to generate tests within the Test Runner, by *recording interactions* against the application under test. Cypress Studio is an experimental feature that can be enabled by adding the {% url "`experimentalStudio`" experiments %} attribute to your configuration, `cypress.json` by default. Address {% issue 73 %}.
+- **You can now test file downloads in Cypress** without the download prompt displaying. Any files downloaded while testing file downloads will be stored in the {% url "`downloadsFolder`" configuration#Downloads %} which is set to `cypress/downloads` by default. The `downloadsFolder` will be deleted before each run unless {% url "`trashAssetsBeforeRuns`" configuration#Downloads %} is set to `false`. Addresses {% issue 949 %}.
+
+**Bugfixes:**
+
+- When an uncaught exception is thrown outside a suite with an `.only`, the error will now correctly display in the Command Log. Fixes {% issue 14455 %}.
+- Cypress will no longer crash when no record key is provided to the `--key` flag when followed by other CLI flags. Fixed {% issue 14593 %}.
+- Extra screenshots will no longer be taken when tests are retried when there is a failure in an `afterEach` hook. Fixes {% issue 9209 %}.
+- Having `waitForAnimations` set to `false` no longer affects whether Cypress fires actions on inner elements. Fixes {% issue 14370 %}.
+- We fixed a regression in {% url "5.0.0" changelog-5-0-0 %} that would cause string `CYPRESS_` prefixed env variables containing commas to be parsed as multiple values. Fixes {% issue 8818 %}.
+- We fixed a regression in {% url "4.9.0" changelog-4-9-0 %} where asserting `have.value` on an undefined subject would throw an error. Fixes {% issue 14359 %}.
+- We updated the CDP connection to attempt to use the stdio transport first with Chrome 72 and above, before falling back to using TCP. This should remediate issues causing sporadic "Cypress failed to make a connection to the Chrome DevTools Protocol after retrying" errors. Fixes {% issue 6540 %}, {% issue 7450 %}, {% issue 8674 %}, and {% issue 8986 %}.
+
+
+**Misc:**
+
+- We removed several Chrome flags that are no longer supported. Addressed in {% issue 14582 %}.
+
+**Dependency Updates:**
+
+- Replaced deprecated `node-sass` with `sass`. Addressed in {% PR 14415 %}.
+- Upgraded `debug` from `4.1.1` to `4.3.1`. Addressed in {% issue 14583 %}.
+- Upgraded `electron` from `11.0.3` to `11.2.0`. Addressed in {% issue 14567 %}.
+- Upgraded `electron-builder` from `22.8.0` to `22.9.1`. Addressed in {% issue 14493 %}.
+- Upgraded `shell-env` from `3.0.0` to `3.0.1`. Addressed in {% issue 14622 %}.
+- Upgraded `uuid` from `8.2.0` to `8.3.2`. Addressed in {% issue 14170 %}.

source/_data/sidebar.yml

@@ -14,6 +14,7 @@ guides:
     variables-and-aliases: variables-and-aliases.html
     conditional-testing: conditional-testing.html
     test-runner: test-runner.html
+    cypress-studio: cypress-studio.html
   dashboard:
     dashboard-introduction: introduction.html
     projects: projects.html

source/api/events/catalog-of-events.md

@@ -429,6 +429,6 @@ If you'd like to see (the huge) stream of events that Cypress emits you can pop
 localStorage.debug = 'cypress:*'
 ```
 
-After you refresh the page you'll see something that looks like this in your console:
+Reload the browser and turn on 'Verbose' logs to see debug messages within the Developer Tools console.
 
 {% imgTag /img/api/catalog-of-events/console-log-events-debug.png "console log events for debugging" %}

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

@@ -255,30 +255,20 @@ module.exports = (on, config) => {
 }
 ```
 
-## Change download directory
+## Support unique file download mime types
 
-Change the download directory of files downloaded during Cypress tests.
+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
-// cypress/plugins/index.js
-const path = require('path')
-
 module.exports = (on) => {
   on('before:browser:launch', (browser, options) => {
-    const downloadDirectory = path.join(__dirname, '..', 'downloads')
-
-    if (browser.family === 'chromium' && browser.name !== 'electron') {
-      options.preferences.default['download'] = { default_directory: downloadDirectory }
-
-      return options
-    }
-
+    // only Firefox requires all mime types to be listed
     if (browser.family === 'firefox') {
-      options.preferences['browser.download.dir'] = downloadDirectory
-      options.preferences['browser.download.folderList'] = 2
+      const existingMimeTypes = options.preferences['browser.helperApps.neverAsk.saveToDisk']
+      const myMimeType = 'my/mimetype'
 
-      // needed to prevent download prompt for text/csv files.
-      options.preferences['browser.helperApps.neverAsk.saveToDisk'] = 'text/csv'
+      // prevents the browser download prompt
+      options.preferences['browser.helperApps.neverAsk.saveToDisk'] = `${existingMimeTypes},${myMimeType}`
 
       return options
     }

source/guides/core-concepts/cypress-studio.md

@@ -0,0 +1,208 @@
+---
+title: Cypress Studio
+---
+
+{% note info %}
+# {% fa fa-graduation-cap %} What you'll learn
+
+- How to extend tests interactively using the Cypress Studio
+- How to add new tests interactively using the Cypress Studio
+
+{% endnote %}
+
+# Overview
+
+Cypress Studio provides a visual way to generate tests within the Test Runner, by *recording interactions* against the application under test.
+
+The {% url `.click()` click %}, {% url `.type()` type %}, {% url `.check()` check %}{% url `.uncheck()` uncheck %} and {% url `.select()` select %} Cypress commands are supported and will generate test code when interacting with the DOM inside of the Cypress Studio.
+
+## Using Cypress Studio
+
+{% note info %}
+Cypress Studio is an experimental feature and can be enabled by adding the `experimentalStudio` attribute to your `cypress.json`.
+{% endnote %}
+
+```json
+{
+  "experimentalStudio": true,
+}
+```
+
+The Cypress {% fa fa-github %} {% url "Real World App (RWA)" https://github.com/cypress-io/cypress-realworld-app %} is an open source project implementing a payment application to demonstrate real-world usage of Cypress testing methods, patterns, and workflows. It will be used to demonstrate the functionality of Cypress Studio.
+
+### Extending a Test
+
+You can extend any preexisting test or start by creating a new test under `cypress/integration` with the following test scaffolding.
+
+```js
+describe('Cypress Studio Demo', function () {
+  beforeEach(function () {
+    // Seed database with test data
+    cy.task('db:seed')
+
+    // Login test user
+    cy.database('find', 'users').then((user) => {
+      cy.login(user.username, 's3cret', true)
+    })
+  })
+
+  it('create new transaction', function () {
+    // Extend test with Cypress Studio
+  })
+})
+```
+
+{% note info %}
+#### {% fa fa-graduation-cap %} Real World Example
+Clone the {% fa fa-github %} {% url "Real World App (RWA)" https://github.com/cypress-io/cypress-realworld-app %} and refer to the {% url "cypress/tests/demo/cypress-studio.spec.ts" https://github.com/cypress-io/cypress-realworld-app/cypress/tests/demo/cypress-studio.spec.ts %} file.
+{% endnote %}
+
+#### Step 1 - Run the spec
+We will use Cypress Studio to perform a "New Transaction" user journey. First, launch the Test Runner and run the spec created in the previous step.
+
+{% imgTag /img/guides/cypress-studio/run-spec-1.png "Cypress Studio" "no-border" %}
+
+Once the tests complete their run, hover over a test in the Command Log to reveal a "Add Commands to Test" button.
+
+Clicking on "Add Commands to Test" will launch the Cypress Studio.
+
+{% note info %}
+Cypress Studio is directly integrated with the {% url 'Command Log' test-runner#Command-Log %}.
+{% endnote %}
+
+{% imgTag /img/guides/cypress-studio/run-spec-2.png "Cypress Studio" "no-border" %}
+
+#### Step 2 - Launch Cypress Studio
+
+{% note success %}
+Cypress will automatically execute all hooks and currently present test code, and then the test can be extended from that point on (e.g. We are logged into the application inside the `beforeEach` block).
+{% endnote %}
+
+Next, the Test Runner will execute the test in isolation and pause after the last command in the test.
+{% imgTag /img/guides/cypress-studio/extend-new-transaction-ready.png "Cypress Studio Ready" "no-border" %}
+
+Now, we can begin updating the test to create a new transaction between users.
+
+#### Step 3 - Interact with the Application
+
+To record actions, begin interacting with the application.  Here we will click on the first name input and as a result we will see the click recorded in the Command Log.
+
+{% imgTag /img/guides/cypress-studio/extend-new-transaction-user-list.png "Cypress Studio Extend Test" "no-border" %}
+
+Next, we can type the name of a user to pay and click on the user in the results.
+
+{% imgTag /img/guides/cypress-studio/extend-new-transaction-click-user.png "Cypress Studio Extend Test" "no-border" %}
+
+We will complete the transaction form by clicking on and typing in the amount and description inputs.  
+{% imgTag /img/guides/cypress-studio/extend-new-transaction-form.png "Cypress Studio Extend Test" "no-border" %}
+
+{% note success %}
+Notice the commands generated in the command log.
+{% endnote %}
+
+Finally, we will click the "Pay" button.
+{% imgTag /img/guides/cypress-studio/extend-new-transaction-pay.png "Cypress Studio Extend Test" "no-border" %}
+
+We are presented with a confirmation page of our new transaction.
+{% imgTag /img/guides/cypress-studio/extend-new-transaction-confirmation.png "Cypress Studio Extend Test Confirmation" "no-border" %}
+
+To discard the interactions, click the "Cancel" button to exit Cypress Studio. If satisfied with the interactions with the application, click "Save Commands" and the test code will be saved to the file.
+
+#### Generated Test Code
+
+Viewing our test code, we can see that the test is updated after clicking "Save Commands" with the actions we recorded in Cypress Studio.
+
+```js
+describe('Cypress Studio Demo', function () {
+  beforeEach(function () {
+    // Seed database with test data
+    cy.task('db:seed')
+
+    // Login test user
+    cy.database('find', 'users').then((user) => {
+      cy.login(user.username, 's3cret', true)
+    })
+  })
+
+  it('create new transaction', function () {
+    /* ==== Generated with Cypress Studio ==== */
+    cy.get('[data-test=nav-top-new-transaction]').click()
+    cy.get('[data-test=user-list-search-input]').click()
+    cy.get('[data-test=user-list-search-input]').type('dev')
+    cy.get('[data-test=user-list-item-tsHF6_D5oQ]').click()
+    cy.get('#amount').type('$25')
+    cy.get('#transaction-create-description-input').click()
+    cy.get('#transaction-create-description-input').type('Sushi dinner')
+    cy.get('[data-test=transaction-create-submit-payment] > .MuiButton-label').click()
+    /* ==== End Cypress Studio ==== */
+  })
+})
+```
+
+### Adding a New Test
+
+Next, we can add a new test, by clicking "Add New Test" beside the test file header.
+{% imgTag /img/guides/cypress-studio/add-test-1.png "Cypress Studio Add Test" "no-border" %}
+
+We are launched into Cypress Studio and can begin interacting with our application to generate the test.
+
+For this test, we will add a new bank account. Our interactions are as follows:
+
+1. Click "Bank Accounts" in left hand navigation
+{% imgTag /img/guides/cypress-studio/add-test-2.png "Cypress Studio Begin Add Test" "no-border" %}
+2. Click the "Create" button on Bank Accounts page
+{% imgTag /img/guides/cypress-studio/add-test-create.png "Cypress Studio Add Test Create Bank Account" "no-border" %}
+3. Fill out the bank account information
+{% imgTag /img/guides/cypress-studio/add-test-form-complete.png "Cypress Studio Add Test Complete Bank Account Form" "no-border" %}
+4. Click the "Save" button
+{% imgTag /img/guides/cypress-studio/add-test-form-saving.png "Cypress Studio Add Test Saving Bank Account" "no-border" %}
+
+To discard the interactions, click the "Cancel" button to exit Cypress Studio.
+
+If satisfied with the interactions with the application, click "Save Commands" and prompt will ask for the name of the test.  Click "Save Test" and the test will be saved to the file.
+
+{% imgTag /img/guides/cypress-studio/add-test-save-test.png "Cypress Studio Add Test Completed Run" "no-border" %}
+
+Once saved, the file will be run again in Cypress.
+
+{% imgTag /img/guides/cypress-studio/add-test-final.png "Cypress Studio Add Test Completed Run" "no-border" %}
+
+Finally, viewing our test code, we can see that the test is updated after clicking "Save Commands" with the actions we recorded in Cypress Studio.
+
+```js
+import { User } from "models";
+
+describe("Cypress Studio Demo", function () {
+  beforeEach(function () {
+    cy.task("db:seed");
+
+    cy.database("find", "users").then((user: User) => {
+      cy.login(user.username, "s3cret", true);
+    });
+  });
+
+  it("create new transaction", function () {
+    // Extend test with Cypress Studio
+  });
+
+  /* === Test Created with Cypress Studio === */
+  it('create bank account', function() {
+    /* ==== Generated with Cypress Studio ==== */
+    cy.get('[data-test=sidenav-bankaccounts]').click();
+    cy.get('[data-test=bankaccount-new] > .MuiButton-label').click();
+    cy.get('#bankaccount-bankName-input').click();
+    cy.get('#bankaccount-bankName-input').type('Test Bank Account');
+    cy.get('#bankaccount-routingNumber-input').click();
+    cy.get('#bankaccount-routingNumber-input').type('987654321');
+    cy.get('#bankaccount-accountNumber-input').click();
+    cy.get('#bankaccount-accountNumber-input').type('123456789');
+    cy.get('[data-test=bankaccount-submit] > .MuiButton-label').click();
+    /* ==== End Cypress Studio ==== */
+  });
+})
+```
+
+{% note info %}
+#### {% fa fa-graduation-cap %} Real World Example
+Clone the {% fa fa-github %} {% url "Real World App (RWA)" https://github.com/cypress-io/cypress-realworld-app %} and refer to the {% url "cypress/tests/demo/cypress-studio.spec.ts" https://github.com/cypress-io/cypress-realworld-app/cypress/tests/demo/cypress-studio.spec.ts %} file.
+{% endnote %}

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

@@ -66,12 +66,6 @@ You can modify the folder configuration in your configuration file. See {% url '
 Cypress will create a {% url `screenshotsFolder` configuration#Screenshots %} and a {% url `videosFolder` configuration#Videos %} to store the screenshots and videos taken during the testing of your application. Many users will opt to add these folders to their `.gitignore` file. Additionally, if you are storing sensitive environment variables in your configuration file (`cypress.json` by default) or {% url `cypress.env.json` environment-variables#Option-2-cypress-env-json %}, these should also be ignored when you check into source control.
 {% endnote %}
 
-## Fixture Files
-
-Fixtures are used as external pieces of static data that can be used by your tests. Fixture files are located in `cypress/fixtures` by default, but can be {% url 'configured' configuration#Folders-Files %} to another directory.
-
-You would typically use them with the {% url `cy.fixture()` fixture %} command and most often when you're stubbing {% url 'Network Requests' network-requests %}.
-
 ## Test files
 
 Test files are located in `cypress/integration` by default, but can be {% url 'configured' configuration#Folders-Files %} to another directory. Test files may be written as:
@@ -91,6 +85,53 @@ To see an example of every command used in Cypress, open the {% url "`example` f
 
 To start writing tests for your app, create a new file like `app_spec.js` within your `cypress/integration` folder. Refresh your tests list in the Cypress Test Runner and your new file should have appeared in the list.
 
+## Fixture Files
+
+Fixtures are used as external pieces of static data that can be used by your tests. Fixture files are located in `cypress/fixtures` by default, but can be {% url 'configured' configuration#Folders-Files %} to another directory.
+
+You would typically use them with the {% url `cy.fixture()` fixture %} command and most often when you're stubbing {% url 'Network Requests' network-requests %}.
+
+## Asset Files
+
+There are some folders that may be generated after a test run, containing assets that were generated during the test run.
+
+You may consider adding these folders to your `.gitignore` file to ignore checking these files into source control.
+
+### Download Files
+
+Any files downloaded while testing an application's file download feature will be stored in the {% url `downloadsFolder` configuration#Downloads %} which is set to `cypress/downloads` by default.
+
+```text
+/cypress
+  /downloads
+    - records.csv
+```
+
+### Screenshot Files
+
+If screenshots were taken via the {% url "`cy.screenshot()`" screenshot %} command or automatically when a test fails, the screenshots are stored in the {% url `screenshotsFolder` configuration#Screenshots %} which is set to `cypress/screenshots` by default.
+
+```text
+/cypress
+  /screenshots
+    /app_spec.js
+      - Navigates to main menu (failures).png
+```
+
+To learn more about screenshots and settings available, see {% url "Screenshots and Videos" screenshots-and-videos#Screenshots %}
+
+### Video Files
+
+Any videos recorded of the run are stored in the {% url `videosFolder` configuration#Videos %} which is set to `cypress/videos` by default.
+
+```text
+/cypress
+  /videos
+    - app_spec.js.mp4
+```
+
+To learn more about videos and settings available, see {% url "Screenshots and Videos" screenshots-and-videos#Screenshots %}
+
 ## Plugin files
 
 By default Cypress will automatically include the plugins file `cypress/plugins/index.js` **before** every single spec file it runs. We do this purely as a convenience mechanism so you don't have to import this file in every single one of your spec files.