feat(testing): Introduce Cypress Custom commands for sign-in and sign-out

[anagstef]

Description

This PR adds Custom commands on the Cypress integration to better sign-in and sign-out.

Add the custom commands

To use these commands, you must import them in your cypress/support/commands.ts file.

// cypress/support/commands.ts
/// <reference types="cypress" />
import { addClerkCommands } from '@clerk/testing/cypress';
addClerkCommands({ Cypress, cy });

export {};

cy.clerkSignIn

The cy.clerkSignIn command is used to sign in a user using Clerk. This custom command supports only the following first factor strategies:

• Password
• Phone code
• Email code

Note: Multi-factor authentication is not supported.

This helper internally uses the setupClerkTestingToken, so you don't need to call it separately.

Prerequisites

• You must call cy.visit before calling this command.
• Navigate to a non-protected page that loads Clerk before using this command.

Parameters

• signInParams: The sign-in object.
  • strategy: The sign-in strategy. Supported strategies are 'password', 'phone_code', and 'email_code'.
  • identifier: The user's identifier. This could be a username, a phone number, or an email.
  • password: The user's password. This is required only if the strategy is 'password'.

Strategy Specifics

• Password: The command will sign in the user using the provided password and identifier.
• Phone Code: You must have a user with a test phone number as an identifier (e.g., +15555550100).
• Email Code: You must have a user with a test email as an identifier (e.g., your_email+clerk_test@example.com).

Example

it('sign in', () => {
  cy.visit(`/`);
  cy.clerkSignIn({ strategy: 'phone_code', identifier: '+15555550100' });
  cy.visit('/protected');
});

cy.clerkSignOut

The cy.clerkSignOut command is used to sign out the current user using Clerk.

Prerequisites

• You must call cy.visit before calling this command.
• Navigate to a page that loads Clerk before using this command.

Parameters

• signOutOptions: A SignOutOptions object.

Example

it('sign out', () => {
  cy.visit(`/`);
  cy.clerkSignIn({ strategy: 'phone_code', identifier: '+15555550100' });
  cy.visit('/protected');
  cy.clerkSignOut();
});

cy.clerkLoaded

The cy.clerkLoaded command asserts that Clerk has been loaded.

Prerequisites

• You must call cy.visit before calling this command.
• Navigate to a page that loads Clerk before using this command.

Example

it('check Clerk loaded', () => {
  cy.visit(`/`);
  cy.clerkLoaded();
});

Checklist

• npm test runs as expected.
• npm run build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: da55a32

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/testing	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[octoper]

🔥

[LekoArts]

Awesome 🔥

[wobsoriano]

Wow, this removes a lot of boilerplate in userland 🚀

[tmilewski]

💯