āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/guides/development/testing/playwright/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. This helper only supports the following first factor strategies: password, phone code, and email code. Multi-factor authentication is not supported.
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 thesetupClerkTestingToken()helper, so you don't need to call it separately.
clerk.signIn() accepts an object with the following properties:
The Playwright Page object to use for the sign-in operation.
emailAddress?stringThe email address of the user to sign in. This is an alternative to using the signInParams parameter. A secret key is required to be set in the CLERK_SECRET_KEY environment variable to use this parameter.
signInParamsClerkSignInParamsThe parameters to use for the sign-in operation. See ClerkSignInParams.
setupClerkTestingTokenOptions?SetupClerkTestingTokenOptionsOptions to pass to setupClerkTestingToken(). See SetupClerkTestingTokenOptions.
</Properties>
ClerkSignInParamsThe 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:
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.identifierstringThe user's identifier. This could be a username, a phone number, or an email.
passwordstringThe user's password. This is required only if the strategy is set to 'password'.
</Properties>
SetupClerkTestingTokenOptionsThe 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:
The Frontend API URL for your Clerk dev instance, without the protocol. If provided, it overrides the Frontend API URL parsed from the Publishable Key. To retrieve your Frontend API URL, navigate to the Domains page in the Clerk Dashboard. </Properties>
The following example demonstrates how to use clerk.signIn() in a test to sign in a user.
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')
})
If you would prefer to sign a user in directly by email address, you can use the emailAddress parameter instead of the signInParams parameter.
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.TEST_USER_EMAIL,
})
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.
clerk.signOut() accepts an object with the following properties:
The Playwright Page object to use for the sign-in operation.
signOutOptions?SignOutOptionsOptions to pass to clerk.signOut(). See SignOutOptions.
</Properties>
SignOutOptionsThe 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:
The ID of a specific session to sign out of. Useful for multi-session applications.
redirectUrl?stringThe full URL or path to navigate after sign-out is complete. </Properties>
The following example demonstrates how to use clerk.signOut() in a test to sign out a user.
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.
clerk.loaded() accepts an object with the following properties:
The Playwright Page object to use for the sign-in operation.
</Properties>
The following example demonstrates how to use clerk.loaded() in a test to assert that Clerk has been loaded.
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
})
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā