Merge branch 'v12' of https://github.com/cypress-io/cypress-documentation into v12

Author: emilyrohrbough

assets/img/examples/auth0-origin.mp4

@@ -10,7 +10,13 @@ _Released MM/DD/YYYY_
   `on`.
 - Cypress now throws an error if commands are invoked from inside a `.should()`
   callback. This previously resulted in unusual and undefined behavior; it is
-  now explicitly an error.
+  now explicitly an error. <<<<<<< HEAD =======
+- The [`.within()`](/api/commands/within) command now throws an error if given
+  more than one DOM element as a subject. This is done for consistency - in
+  older versions, some commands inside a `.within()` block would respect all
+  passed in elements, while others silently discarded subjects beyond the first
+  and `.screenshot()` would throw an error.
+  > > > > > > > f2c3c1944ed572fc96b8a8001c53b80a9bdb25de
 - `Cookies.defaults` and `Cookies.preserveOnce` have been removed. Please update
   to use [`cy.session()`](/api/commands/session) to preserve session details
   between tests. Addresses

assets/img/examples/auth0-session-restore.mp4

@@ -20,14 +20,17 @@ chain further commands that rely on the subject after `.within()`.
 **<Icon name="check-circle" color="green"></Icon> Correct Usage**
 
 ```javascript
-cy.get('.list').within(($list) => {}) // Yield the `.list` and scope all commands within it
+cy.get('.list')
+  .first()
+  .within(($list) => {}) // Yield the first `.list` and scope all commands within it
 ```
 
 **<Icon name="exclamation-triangle" color="red"></Icon> Incorrect Usage**
 
 ```javascript
 cy.within(() => {}) // Errors, cannot be chained off 'cy'
 cy.getCookies().within(() => {}) // Errors, 'getCookies' does not yield DOM element
+cy.get('div').within(($divs) => {}) // Probably errors, because get('div') yields multiple elements
 ```
 
 ### Arguments
@@ -179,7 +182,8 @@ cy.get('form').within(($form) => {
 
 ### Requirements [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Chains-of-Commands)
 
-<List><li>`.within()` requires being chained off a previous command.</li></List>
+- `.within()` requires being chained off a previous command that yields exactly
+  one DOM element.
 
 ### Assertions [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Assertions)
 
@@ -211,10 +215,11 @@ outputs the following:
 
 ## History
 
-| Version                                       | Changes                                                 |
-| --------------------------------------------- | ------------------------------------------------------- |
-| [< 0.3.3](/guides/references/changelog#0-3-3) | `.within()` command added                               |
-| [5.4.0](/guides/references/changelog#5-4-0)   | fixed the yielded value to always be the parent element |
+| Version                                       | Changes                                                                          |
+| --------------------------------------------- | -------------------------------------------------------------------------------- |
+| [12.0.0](/guides/references/changelog#12-0-0) | `.within()` now throws an error when given more than one element as the subject. |
+| [5.4.0](/guides/references/changelog#5-4-0)   | fixed the yielded value to always be the parent element                          |
+| [< 0.3.3](/guides/references/changelog#0-3-3) | `.within()` command added                                                        |
 
 ## See also
 

content/_changelogs/12.0.0.md

@@ -7,25 +7,15 @@ e2eSpecific: true
 
 ## <Icon name="graduation-cap"></Icon> What you'll learn
 
+- Log in to [Auth0](https://auth0.com) through the UI with
+  [`cy.origin()`](/api/commands/origin)
 - Programmatically authenticate with [Auth0](https://auth0.com) via a custom
   Cypress command
-- Adapting your [Auth0](https://auth0.com) application for programmatic
+- Adapt your [Auth0](https://auth0.com) application for programmatic
   authentication during testing
 
 </Alert>
 
-<Alert type="success">
-
-<strong class="alert-header">Why authenticate programmatically?</strong>
-
-Typically, logging in a user within your app by authenticating via a third-party
-provider requires visiting login pages hosted on a different domain. Since each
-Cypress test is limited to visiting domains of the same origin, we can subvert
-visiting and testing third-party login pages by programmatically interacting
-with the third-party authentication API to login a user.
-
-</Alert>
-
 <Alert type="warning">
 
 This guide is setup for testing against an [Auth0](https://auth0.com) Single
@@ -36,6 +26,22 @@ for automated end-to-end testing.
 
 </Alert>
 
+<Alert type="success">
+
+<strong class="alert-header">Authenticate by visiting a different domain with
+[`cy.origin()`](/api/commands/origin)</strong>
+
+Typically, logging in a user within your app by authenticating via a third-party
+provider requires visiting a login page hosted on a different domain. Before
+Cypress [v12.0.0](https://on.cypress.io/changelog#12-0-0), Cypress tests were
+limited to visiting domains of the same origin, making programmatic login the
+only option for authenticating users with a third-party API. As of Cypress
+[v12.0.0](https://on.cypress.io/changelog#12-0-0), Cypress tests are no longer
+limited to visiting domains of a single origin, meaning you can easily
+authenticate with [Auth0](https://auth0.com) via the UI!
+
+</Alert>
+
 ## Auth0 Application Setup
 
 To get started with Auth0, an application needs to be setup within the
@@ -111,23 +117,151 @@ require('dotenv').config()
 }
 ```
 
+Note that `auth0_client_secret` is only needed for
+[programmatic login](#Programmatic-Login).
+
 :::
 
 ## Custom Command for Auth0 Authentication
 
+There are two ways you can authenticate to Auth0:
+
+- [Login with `cy.origin()`](#Login-with-cy-origin)
+- [Programmatic Login](#Programmatic-Login)
+
+### Login with [`cy.origin()`](/api/commands/origin)
+
+Next, we'll write a custom command called `loginToAuth0` to perform a login to
+[Auth0](https://auth0.com). This command will use
+[`cy.origin()`](/api/commands/origin) to
+
+1. Navigate to the Auth0 login
+2. Input user credentials
+3. Sign in and redirect back to the
+   [Cypress Real World App](https://github.com/cypress-io/cypress-realworld-app)
+4. Cache the results with [`cy.session()`](/api/commands/session)
+
+```js
+// cypress/support/auth-provider-commands/auth0.ts
+
+function loginViaAuth0Ui(username: string, password: string) {
+  // App landing page redirects to Auth0.
+  cy.visit('/')
+
+  // Login on Auth0.
+  cy.origin(
+    Cypress.env('auth0_domain'),
+    { args: { username, password } },
+    ({ username, password }) => {
+      cy.get('input#username').type(username)
+      cy.get('input#password').type(password, { log: false })
+      cy.contains('button[value=default]', 'Continue').click()
+    }
+  )
+
+  // Ensure Auth0 has redirected us back to the RWA.
+  cy.url().should('equal', 'http://localhost:3000/')
+}
+
+Cypress.Commands.add('loginToAuth0', (username: string, password: string) => {
+  const log = Cypress.log({
+    displayName: 'AUTH0 LOGIN',
+    message: [`🔐 Authenticating | ${username}`],
+    // @ts-ignore
+    autoEnd: false,
+  })
+  log.snapshot('before')
+
+  loginViaAuth0Ui(username, password)
+
+  log.snapshot('after')
+  log.end()
+})
+```
+
+Now, we can use our `loginToAuth0` command in the test. Below is our test to
+login as a user via Auth0 and run a basic sanity check.
+
+<Alert type="success">
+
+The
+[runnable version of this test](https://github.com/cypress-io/cypress-realworld-app/blob/develop/cypress/tests/ui-auth-providers/auth0.spec.ts)
+is in the
+[Cypress Real World App](https://github.com/cypress-io/cypress-realworld-app).
+
+</Alert>
+
+```js
+describe('Auth0', function () {
+  beforeEach(function () {
+    cy.task('db:seed')
+    cy.intercept('POST', '/graphql').as('createBankAccount')
+    cy.loginToAuth0(
+      Cypress.env('auth0_username'),
+      Cypress.env('auth0_password')
+    )
+    cy.visit('/')
+  })
+
+  it('shows onboarding', function () {
+    cy.contains('Get Started').should('be.visible')
+  })
+})
+```
+
+<DocsVideo src="/img/examples/auth0-origin.mp4"></DocsVideo>
+
+Lastly, we can refactor our login command to take advantage of
+[`cy.session()`](/api/commands/session) to store our logged in user so we don't
+have to reauthenticate before every test.
+
+```js
+Cypress.Commands.add('loginToAuth0', (username: string, password: string) => {
+  const log = Cypress.log({
+    displayName: 'AUTH0 LOGIN',
+    message: [`🔐 Authenticating | ${username}`],
+    // @ts-ignore
+    autoEnd: false,
+  })
+  log.snapshot('before')
+
+  cy.session(
+    `auth0-${username}`,
+    () => {
+      loginViaAuth0Ui(username, password)
+    },
+    {
+      validate: () => {
+        // Validate presence of access token in localStorage.
+        cy.wrap(localStorage)
+          .invoke('getItem', 'authAccessToken')
+          .should('exist')
+      },
+    }
+  )
+
+  log.snapshot('after')
+  log.end()
+})
+```
+
+<DocsVideo src="/img/examples/auth0-session-restore.mp4"></DocsVideo>
+
+### Programmatic Login
+
 Below is a command to programmatically login into [Auth0](https://auth0.com),
 using the
 [/oauth/token endpoint](https://auth0.com/docs/protocols/protocol-oauth2#token-endpoint)
-and set an item in localStorage with the authenticated users details, which we
+and set an item in `localStorage` with the authenticated users details, which we
 will use in our application code to verify we are authenticated under test.
 
 The `loginByAuth0Api` command will execute the following steps:
 
 1. Use the
    [/oauth/token endpoint](https://auth0.com/docs/protocols/protocol-oauth2#token-endpoint)
    to perform the programmatic login.
-2. Finally the `auth0Cypress` localStorage item is set with the `access token`,
-   `id_token` and user profile.
+2. Finally the `auth0Cypress` `localStorage` item is set with the
+   `access token`, `id_token` and user profile.
 
 ```jsx
 // cypress/support/commands.js
@@ -216,17 +350,6 @@ describe('Auth0', function () {
 })
 ```
 
-<Alert type="success">
-
-<strong class="alert-header">Try it out</strong>
-
-The
-[runnable version of this test](https://github.com/cypress-io/cypress-realworld-app/blob/develop/cypress/tests/ui-auth-providers/auth0.spec.ts)
-is in the
-[Cypress Real World App](https://github.com/cypress-io/cypress-realworld-app).
-
-</Alert>
-
 ## Adapting an Auth0 App for Testing
 
 <Alert type="info">
@@ -238,7 +361,11 @@ within Cypress tests. To use this practice it is assumed you are testing an app
 appropriately built or adapted to use Auth0.
 
 The following sections provides guidance on building or adapting an app to use
-Auth0 authentication.
+Auth0 authentication. Please note that if you are
+[logging in with `cy.origin()`](#Login-with-cy-origin) and your app is already
+successfully integrated with Auth0, you do not need to make any further changes
+to your app and the remainder of this guide should be regarded as purely
+informational.
 
 </Alert>
 
@@ -420,7 +547,7 @@ if (process.env.REACT_APP_AUTH0) {
 
 An update to our
 [AppAuth0.tsx component](https://github.com/cypress-io/cypress-realworld-app/blob/develop/src/containers/AppAuth0.tsx)
-is needed to conditionally use the `auth0Cypress` localStorage item.
+is needed to conditionally use the `auth0Cypress` `localStorage` item.
 
 In the code below, we conditionally apply a `useEffect` block based on being
 under test with Cypress (using `window.Cypress`).