āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/guides/development/testing/cypress/overview ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
[!WARNING] Our
@clerk/testingpackage only supports end-to-end testing. Unit tests are not supported.
Testing with Cypress requires the use of Testing Tokens to bypass various bot detection mechanisms that typically safeguard Clerk apps against malicious bots. Without Testing Tokens, you might encounter "Bot traffic detected" errors in your requests.
This guide will help you set up your environment for creating Clerk-authenticated tests with Cypress.
<Steps> ## Install `@clerk/testing`[!IMPORTANT] Check out the demo repo that tests a Clerk-powered application using Testing Tokens.
Clerk's testing package provides integration helpers for popular testing frameworks. Run the following command to install it:
<CodeBlockTabs options={['npm', 'yarn', 'pnpm']}>
sh {{ filename: 'terminal' }} npm install @clerk/testing --save-dev
```sh {{ filename: 'terminal' }}
yarn add -D @clerk/testing
```
```sh {{ filename: 'terminal' }}
pnpm add @clerk/testing -D
```
In your test runner, set your Publishable and Secret Keys as the CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY environment variables, respectively.
To find your keys:
.env file.[!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.
To set up Clerk with Cypress, call the clerkSetup() function in your cypress.config.ts file.
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 retrieve a Testing Token once the test suite starts, making it available for all subsequent tests.
Now that Cypress is configured with Clerk, use the setupClerkTestingToken() function in your tests to integrate the Testing Token. See the following example:
import { setupClerkTestingToken } from '@clerk/testing/cypress'
it('sign up', () => {
setupClerkTestingToken()
cy.visit('/sign-up')
// Add any other actions to test
})
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā