Docs

Custom commands

The @clerk/testing package provides Cypress custom commands to sign in and 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, as shown in the following example.

cypress/support/e2e.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

Multi-factor authentication is not supported.

Note

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

Prerequisites

  • Before calling this command, you must call cy.visit.
  • Before using this command, navigate to a non-protected page that loads Clerk.

Parameters

cy.clerkSignIn accepts an object with the following properties:

  • Name
    strategy
    Type
    'password' | 'phone_code' | 'email_code'
    Description

    The sign-in strategy. Supported strategies are:

    • 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).
  • Name
    identifier
    Type
    string
    Description

    The user's identifier. This could be a username, a phone number, or an email.

  • Name
    password
    Type
    string
    Description

    The user's password. This is required only if the strategy is set to 'password'.

Example

The following example demonstrates how to use the cy.clerkSignIn() command in a test to sign in a user.

cypress/e2e/my-test.cy.ts
it('sign in', () => {
  cy.visit(`/`)
  cy.clerkSignIn({ strategy: 'phone_code', identifier: '+15555550100' })
  cy.visit('/protected')
  // user is signed in from here on
})

cy.clerkSignOut

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

Prerequisites

  • Before calling this command, yu must call cy.visit.
  • Before using this command, navigate to a page that loads Clerk.

Parameters

cy.clerkSignOut accepts an optional parameter signOutOptions, which includes the following properties:

  • Name
    sessionId?
    Type
    string
    Description

    The ID of a specific session to sign out of. Useful for multi-session applications.

  • Name
    redirectUrl?
    Type
    string
    Description

    The redirect URL to navigate to after sign out is complete.

Example

The following example demonstrates how to use the cy.clerkSignOut() command in a test to sign a user out.

cypress/e2e/my-test.cy.ts
it('sign out', () => {
  cy.visit(`/`)
  cy.clerkSignIn({ strategy: 'phone_code', identifier: '+15555550100' })
  cy.visit('/protected')
  cy.clerkSignOut()
  // user is signed out from here on
})

cy.clerkLoaded

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

Prerequisites

  • Before calling this command, you must call cy.visit.
  • Before using this command, navigate to a page that loads Clerk.

Example

The following example demonstrates how to use the cy.clerkLoaded() command in a test to assert that Clerk has been loaded.

cypress/e2e/my-test.cy.ts
it('check Clerk loaded', () => {
  cy.visit(`/`)
  cy.clerkLoaded()
  // Clerk has been loaded from here on
})

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on