Setup Cypress

Learn how to set up Cypress for testing applications using Kinde authentication. This guide covers installation, configuration, and basic setup for end-to-end testing.

What you need

A test user and optionally a running test application.
Node.js version 20 or higher.

Installation for new projects

Install Cypress with the following command:
Terminal window
```
npm install cypress --save-dev
```
Run the following command. The Cypress configuration wizard opens:
Terminal window
```
npx cypress open
```
- Select E2E Testing and select Continue.
- Select Start E2E Testing in Chrome. This will open the Cypress Test Runner.
- Select Create new spec. In the pop-up that opens, select Create spec
  - Select Okay, run the spec
This will create a basic test file in the cypress/e2e folder.
Close the Cypress Test Runner.

Configuration

Environment variables

Create or update the Cypress env file:
Terminal window
```
touch cypress.env.json
```

Add the following to the cypress.env.json file using values from your test user and application:

{
  "TEST_APP_URL": "https://your-app-url.com",
  "TEST_USER_EMAIL": "your-test-email",
  "TEST_USER_PASSWORD": "your-test-password",
  "KINDE_ISSUER_URL": "https://your_kinde_domain.kinde.com",
  "KINDE_CLIENT_ID": "your-kinde-client-id",
  "KINDE_CLIENT_SECRET": "your-kinde-client-secret"
}

Create a .gitignore file and add the environment file to it:
Terminal window
```
touch .gitignore
echo "cypress.env.json" >> .gitignore
```

Cypress configuration

Update your cypress.config.js file with the following basic configuration:

const { defineConfig } = require("cypress");

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    setupNodeEvents(on, config) {
      // implement node event listeners here
    },
  },
});

Project structure

After setup, your project should have the following structure:

your-project/
├── cypress.config.js
├── cypress.env.json          # Environment variables (gitignored)
├── cypress/
│   ├── e2e/
│   │   └── spec.cy.js        # Example test file
│   ├── fixtures/             # Test data
│   └── support/
│       ├── commands.js       # Custom commands
│       └── e2e.js            # Support file
└── package.json

Basic test example

Create your first test file to verify the setup:

describe('Authentication', () => {
  it('can visit the application', () => {
    cy.visit(Cypress.env('TEST_APP_URL'))
    cy.url().should('include', new URL(Cypress.env('TEST_APP_URL')).hostname)
  })
})

Running tests

Interactive mode (recommended for development)

Open Cypress in interactive mode:

npx cypress open

This opens the Cypress Test Runner where you can:

Select a browser
See tests run in real-time
Debug tests interactively

Headless mode (for CI/CD)

Run tests in headless mode:

npx cypress run

Troubleshooting

Cypress not found

If you get a “command not found” error, make sure Cypress is installed locally:

npm install cypress --save-dev

Environment variables not loading

Make sure cypress.env.json exists and contains valid JSON. You can also use environment variables directly:

CYPRESS_TEST_APP_URL=https://your-app.com npx cypress open

Cross-origin errors

When testing with Kinde, you’ll need to use cy.origin() for cross-origin requests.

For additional troubleshooting or configuration guidance, refer to the official Cypress documentation.

Next steps

Now that Cypress is set up, you can proceed with:

Test Authentication Flows - Learn how to test sign-up, sign-in, and sign-out flows
Test Passwordless Flows - Test passwordless authentication with email OTP
Test Auth Features - Test authenticated features using session state
Test Backend APIs - Test backend APIs with refresh tokens

Join the community

Get support from the Kinde team and expert users in the Kinde community

Join via Slack or Discord
Contact support

Chat to support through the Kinde help widget, or send a question via email

Send an email