feat(cypress): Restructure and add Account Portal section

docs/manifest.json

@@ -973,7 +973,26 @@
                             ]
                           ]
                         },
-                        { "title": "Cypress", "href": "/docs/testing/cypress" },
+                        {
+                          "title": "Cypress",
+                          "collapse": true,
+                          "items": [
+                            [
+                              {
+                                "title": "Overview",
+                                "href": "/docs/testing/cypress/overview"
+                              },
+                              {
+                                "title": "Custom Commands",
+                                "href": "/docs/testing/cypress/custom-commands"
+                              },
+                              {
+                                "title": "Test Account Portal",
+                                "href": "/docs/testing/cypress/test-account-portal"
+                              }
+                            ]
+                          ]
+                        },
                         {
                           "title": "Postman or Insomnia",
                           "href": "/docs/testing/postman-or-insomnia"

docs/testing/cypress.mdx → docs/testing/cypress/custom-commands.mdx

@@ -1,88 +1,8 @@
 ---
-title: Testing with Cypress
-description: Use Cypress to write end-to-end tests with Clerk.
+title: Custom Commands
+description: Use Custom Commands to sign in/sign out with Clerk in your Cypress tests.
 ---
 
-> [!WARNING]
-> Our `@clerk/testing` package only supports end-to-end testing. Unit tests are not supported.
-
-Testing with Cypress requires the use of Clerk's [Testing Tokens](/docs/testing/overview#testing-tokens) to bypass various bot detection mechanisms that typically safeguard Clerk applications against malicious bots. Without Testing Tokens, you may encounter "Bot traffic detected" errors in your requests.
-
-This guide aims to help you set up your environment for creating Clerk-authenticated tests with Cypress.
-
-> [!IMPORTANT]
-> Check out the [demo repo](https://github.com/clerk/clerk-cypress-nextjs) that tests a Clerk-powered application using [Testing Tokens](/docs/testing/overview#testing-tokens).
-
-<Steps>
-  ### Install `@clerk/testing`
-
-  Clerk's testing package provides integration helpers for popular testing frameworks. Install it by running the following command:
-
-  <CodeBlockTabs options={['npm', 'yarn', 'pnpm']}>
-    ```sh {{ filename: 'terminal' }}
-    npm i @clerk/testing --save-dev
-    ```
-
-    ```sh {{ filename: 'terminal' }}
-    yarn add -D @clerk/testing
-    ```
-
-    ```sh {{ filename: 'terminal' }}
-    pnpm add @clerk/testing -D
-    ```
-  </CodeBlockTabs>
-
-  ### Set your API keys
-
-  In your test runner, set your publishable and secret key as the `CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` environment variables, respectively.
-
-  To find your keys:
-
-  1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys).
-  1. In the navigation sidebar, select **API Keys**.
-  1. In the **Quick Copy** section, copy your Clerk publishable and secret key.
-
-  > [!WARNING]
-  > Ensure you provide the secret key in a secure manner, to avoid leaking it to third parties. For example, if you are using GitHub Actions, refer to [_Using secrets in GitHub Actions_](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
-
-  ### Global setup
-
-  To set up Clerk with Cypress, you must call the `clerkSetup()` function in your [`cypress.config.ts`](https://docs.cypress.io/guides/references/configuration) file.
-
-  ```tsx filename="cypress.config.ts"
-  import { clerkSetup } from '@clerk/testing/cypress'
-  import { defineConfig } from 'cypress'
-
-  export default defineConfig({
-    e2e: {
-      setupNodeEvents(on, config) {
-        return clerkSetup({ config })
-      },
-      baseUrl: 'http://localhost:3000', // your app's URL
-    },
-  })
-  ```
-
-  `clerkSetup` will obtain a [Testing Token](/docs/testing/overview#testing-tokens) when your test suite starts, making it available for all subsequent tests to use.
-
-  ### Use Clerk Testing Tokens
-
-  Now that Cypress is configured with Clerk, you can use the `setupClerkTestingToken()` function in your tests to augment them with the Testing Token. See the following example:
-
-  ```tsx filename="my-test.cy.ts"
-  import { setupClerkTestingToken } from '@clerk/testing/cypress'
-
-  it('sign up', () => {
-    setupClerkTestingToken()
-
-    cy.visit('/sign-up')
-    // ...
-  })
-  ```
-</Steps>
-
-## Custom Commands
-
 The `@clerk/testing` package also provides [Cypress custom commands](https://docs.cypress.io/api/cypress-api/custom-commands) to sign in/sign out with Clerk in your Cypress tests without having to interact with the UI.
 To use these commands, you must import them in your [Cypress E2E support file](https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests#Support-file), as shown in the following example.
 
@@ -215,5 +135,3 @@ it('check Clerk loaded', () => {
   // Clerk has been loaded from here on
 })
 ```
-
-For more information, feedback or issues, visit the [`@clerk/testing`](https://github.com/clerk/javascript/tree/main/packages/testing) package.

docs/testing/cypress/overview.mdx

@@ -0,0 +1,82 @@
+---
+title: Testing with Cypress
+description: Use Cypress to write end-to-end tests with Clerk.
+---
+
+> [!WARNING]
+> Our `@clerk/testing` package only supports end-to-end testing. Unit tests are not supported.
+
+Testing with Cypress requires the use of Clerk's [Testing Tokens](/docs/testing/overview#testing-tokens) to bypass various bot detection mechanisms that typically safeguard Clerk applications against malicious bots. Without Testing Tokens, you may encounter "Bot traffic detected" errors in your requests.
+
+This guide aims to help you set up your environment for creating Clerk-authenticated tests with Cypress.
+
+> [!IMPORTANT]
+> Check out the [demo repo](https://github.com/clerk/clerk-cypress-nextjs) that tests a Clerk-powered application using [Testing Tokens](/docs/testing/overview#testing-tokens).
+
+<Steps>
+  ### Install `@clerk/testing`
+
+  Clerk's testing package provides integration helpers for popular testing frameworks. Install it by running the following command:
+
+  <CodeBlockTabs options={['npm', 'yarn', 'pnpm']}>
+    ```sh {{ filename: 'terminal' }}
+    npm i @clerk/testing --save-dev
+    ```
+
+    ```sh {{ filename: 'terminal' }}
+    yarn add -D @clerk/testing
+    ```
+
+    ```sh {{ filename: 'terminal' }}
+    pnpm add @clerk/testing -D
+    ```
+  </CodeBlockTabs>
+
+  ### Set your API keys
+
+  In your test runner, set your publishable and secret key as the `CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` environment variables, respectively.
+
+  To find your keys:
+
+  1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys).
+  1. In the navigation sidebar, select **API Keys**.
+  1. In the **Quick Copy** section, copy your Clerk publishable and secret key.
+
+  > [!WARNING]
+  > Ensure you provide the secret key in a secure manner, to avoid leaking it to third parties. For example, if you are using GitHub Actions, refer to [_Using secrets in GitHub Actions_](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
+
+  ### Global setup
+
+  To set up Clerk with Cypress, you must call the `clerkSetup()` function in your [`cypress.config.ts`](https://docs.cypress.io/guides/references/configuration) file.
+
+  ```tsx filename="cypress.config.ts"
+  import { clerkSetup } from '@clerk/testing/cypress'
+  import { defineConfig } from 'cypress'
+
+  export default defineConfig({
+    e2e: {
+      setupNodeEvents(on, config) {
+        return clerkSetup({ config })
+      },
+      baseUrl: 'http://localhost:3000', // your app's URL
+    },
+  })
+  ```
+
+  `clerkSetup` will obtain a [Testing Token](/docs/testing/overview#testing-tokens) when your test suite starts, making it available for all subsequent tests to use.
+
+  ### Use Clerk Testing Tokens
+
+  Now that Cypress is configured with Clerk, you can use the `setupClerkTestingToken()` function in your tests to augment them with the Testing Token. See the following example:
+
+  ```tsx filename="my-test.cy.ts"
+  import { setupClerkTestingToken } from '@clerk/testing/cypress'
+
+  it('sign up', () => {
+    setupClerkTestingToken()
+
+    cy.visit('/sign-up')
+    // ...
+  })
+  ```
+</Steps>

docs/testing/cypress/test-account-portal.mdx

@@ -0,0 +1,58 @@
+---
+title: Test Account Portal
+description: Learn how to test the Account Portal flow with Cypress.
+---
+
+When testing with Cypress, navigations that involve redirects to external URLs can be tricky to test. This guide demonstrates how to test the Account Portal flow with Cypress, which involves redirecting to the Account Portal and back to your application.
+
+In order to achieve this you need to use the `cy.origin()` command. More information about this command can be found in the [Cypress documentation](https://docs.cypress.io/api/commands/origin).
+
+Also, you need to know your Account Portal domain to use it in the `cy.origin()` command. You can find your Account Portal domain in the Clerk Dashboard under the **Configure > Account Portal** section (e.g. `https://ready-flea-75.accounts.dev`).
+
+The test should be structured as follows:
+
+```ts
+it('sign in with Account Portal redirects', () => {
+  setupClerkTestingToken()
+
+  // set the origin to the Account Portal domain
+  cy.origin('https://ready-flea-75.accounts.dev', () => {
+    // visit a protected page that redirects to the Account Portal when not signed in
+    cy.visit('http://localhost:3000/protected')
+    // fill the form to sign in
+    // ...
+  })
+
+  // the user should be redirected back to the protected page
+  cy.url().should('include', '/protected')
+})
+```
+
+### Full example
+
+The following snippet showcases a full example of a test that signs in with the Account Portal redirects. It can also be found in the [Clerk Cypress demo repo](https://github.com/clerk/clerk-cypress-nextjs).
+
+```ts
+import { setupClerkTestingToken } from '@clerk/testing/cypress'
+
+describe('Testing Tokens', () => {
+  it('sign in with Account Portal redirects', () => {
+    setupClerkTestingToken()
+
+    cy.origin('https://ready-flea-75.accounts.dev', () => {
+      cy.visit('http://localhost:3000/protected')
+      cy.contains('h1', 'Sign in')
+      cy.get('.cl-signIn-root').should('exist')
+      cy.get('input[name=identifier]').type(Cypress.env('test_user'))
+
+      cy.get('.cl-formButtonPrimary').contains('button', 'Continue').click()
+      cy.get('input[name=password]').type(Cypress.env('test_password'))
+
+      cy.get('.cl-formButtonPrimary').contains('button', 'Continue').click()
+    })
+
+    cy.url().should('include', '/protected')
+    cy.contains('h1', 'This is a PROTECTED page')
+  })
+})
+```

docs/testing/overview.mdx

@@ -14,7 +14,7 @@ To avoid sending an email or SMS message with a one time passcode (OTP) during t
 Testing Tokens allow you to bypass bot detection mechanisms that protect Clerk applications from malicious bots, ensuring your test suites run smoothly. Without Testing Tokens, you may encounter "Bot traffic detected" errors in your requests.
 
 > [!NOTE]
-> While you can manually implement the following logic in your test suite, Clerk provides [Playwright](/docs/testing/playwright/overview) and [Cypress](/docs/testing/cypress) integrations that handle this automatically.
+> While you can manually implement the following logic in your test suite, Clerk provides [Playwright](/docs/testing/playwright/overview) and [Cypress](/docs/testing/cypress/overview) integrations that handle this automatically.
 
 Obtained via the [Backend API](/docs/reference/backend-api/tag/Testing-Tokens){{ target: '_blank' }}, Testing Tokens are short-lived and valid only for the specific instance for which they are issued. Testing Tokens are only available in development instances.