Skip to main content
Docs

Test helpers

The @clerk/testing package also provides some helper functions to sign in/sign out with Clerk in your Playwright tests without having to interact with the UI. To use these commands, import the clerk object from the @clerk/testing/playwright package.

clerk.signIn()

The clerk.signIn() function is used to sign in a user using Clerk. There are two ways to use it:

  • emailAddress parameter (recommended): Signs in by creating a server-side token via the Backend API. This bypasses all verification steps, including email verification and multi-factor authentication. Requires CLERK_SECRET_KEY to be set.
  • signInParams parameter: Signs in client-side using the specified strategy (password, phone code, or email code). Only handles verification — is not supported with this approach.

Before calling clerk.signIn(), it is required to call page.goto() and navigate to an unprotected page that loads Clerk. For example, the index (/) page.

Note

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

Parameters

clerk.signIn() accepts an object with the following properties:

ClerkSignInParams

The ClerkSignInParams type is used to define the object that is passed to the signInParams parameter of the clerk.signIn() function. It has 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). Currently only supported in development environments.
    • email_code: You must have a user with a test email as an identifier (e.g., your_email+clerk_test@example.com). Currently only supported in development environments.
  • 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'.

SetupClerkTestingTokenOptions

The SetupClerkTestingTokenOptions type is used to define the object that is passed to the setupClerkTestingTokenOptions parameter of the clerk.signIn() function. It has the following properties:

  • Name
    frontendApiUrl?
    Type
    string
    Description

    The for your Clerk dev instance, without the protocol. If provided, it overrides the Frontend API URL parsed from the .

Example

The following example demonstrates the recommended way to use clerk.signIn() with the emailAddress parameter. This approach works regardless of your instance's verification or MFA settings.

e2e/app.spec.ts
import { clerk } from '@clerk/testing/playwright'

test('sign in', async ({ page }) => {
  // Navigate to an unprotected page that loads Clerk
  await page.goto('/')

  await clerk.signIn({
    page,
    emailAddress: process.env.E2E_CLERK_USER_EMAIL,
  })

  // Navigate to a protected page
  await page.goto('/protected')
})

Alternatively, you can use the signInParams parameter to sign in using a specific strategy. This approach only handles first factor verification — if your instance has email verification or MFA enabled, use the emailAddress parameter instead.

e2e/app.spec.ts
import { clerk } from '@clerk/testing/playwright'

test('sign in', async ({ page }) => {
  // Navigate to an unprotected page that loads Clerk
  await page.goto('/')

  await clerk.signIn({
    page,
    signInParams: { strategy: 'phone_code', identifier: '+15555550100' },
  })

  // Navigate to a protected page
  await page.goto('/protected')
})

clerk.signOut()

clerk.signOut() is used to sign out the current user using Clerk.

Before calling clerk.signOut(), it is required to call page.goto() and navigate to an unprotected page that loads Clerk. For example, the index (/) page.

Parameters

clerk.signOut() accepts an object with the following properties:

SignOutOptions

The SignOutOptions type is used to define the object that is passed to the signOutOptions parameter of the clerk.signOut() function. It has 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 full URL or path to navigate after sign-out is complete.

Example

The following example demonstrates how to use clerk.signOut() in a test to sign out a user.

e2e/app.spec.ts
import { clerk } from '@clerk/testing/playwright'

test('sign out', async ({ page }) => {
  // Navigate to an unprotected page that loads Clerk
  await page.goto('/')

  await clerk.signIn({
    page,
    signInParams: { strategy: 'phone_code', identifier: '+15555550100' },
  })

  await page.goto('/protected')
  await clerk.signOut({ page })
  await page.goto('/protected')
  // should redirect to sign in page
})

clerk.loaded()

clerk.loaded() asserts that Clerk has been loaded.

Before calling clerk.loaded(), it is required to call page.goto() and navigate to an unprotected page that loads Clerk. For example, the index (/) page.

Parameters

clerk.loaded() accepts an object with the following properties:

Example

The following example demonstrates how to use clerk.loaded() in a test to assert that Clerk has been loaded.

e2e/app.spec.ts
import { clerk } from '@clerk/testing/playwright'

test('ensure that clerk has loaded', async ({ page }) => {
  // Navigate to an unprotected page that loads Clerk
  await page.goto('/')

  await clerk.loaded({ page })
  // clerk has loaded
})

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub