Token-based authentication in Cypress - Framework Patterns

Framework Mode - Token-based authentication

Folder Structure

  cypress/
  ├── e2e/
  │   ├── login.cy.js          # Tests that use token-based authentication
  │   ├── dashboard.cy.js      # Tests for authenticated pages
  │   └── ...
  ├── fixtures/
  │   └── user.json            # Test data like user credentials
  ├── support/
  │   ├── commands.js          # Custom commands including token login
  │   ├── auth.js              # Helper functions for token handling
  │   └── index.js             # Support file loaded before tests
  ├── plugins/
  │   └── index.js             # Cypress plugins if needed
  cypress.config.js             # Cypress configuration file
  

Test Framework Layers

• Test Layer (cypress/e2e): Contains test files that use tokens to authenticate API or UI requests.
• Support Layer (cypress/support): Holds reusable code like custom commands (commands.js) and authentication helpers (auth.js) to get and store tokens.
• Fixtures Layer (cypress/fixtures): Stores static test data such as user credentials used to request tokens.
• Plugins Layer (cypress/plugins): Optional place for extending Cypress functionality if needed.
• Configuration (cypress.config.js): Defines environment variables, base URLs, and test settings.

Configuration Patterns

Use cypress.config.js to manage environment variables and base URLs for different environments (dev, staging, prod).

Example snippet for environment config:

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

  module.exports = defineConfig({
    e2e: {
      baseUrl: 'https://example.com',
      env: {
        apiUrl: 'https://api.example.com',
        username: 'testuser',
        password: 'testpass'
      },
      setupNodeEvents(on, config) {
        // plugin code
      }
    }
  })
  

Store sensitive data like credentials in environment variables or cypress.env.json (ignored by version control).

Use custom commands to request tokens before tests and save them in Cypress.env() for reuse.

Test Reporting and CI/CD Integration

• Use built-in Cypress reporters or plugins like mochawesome for detailed HTML reports.
• Integrate Cypress tests in CI/CD pipelines (GitHub Actions, Jenkins, GitLab CI) to run tests on each code push.
• Configure environment variables securely in CI to provide credentials for token requests.
• Fail tests if token authentication fails, ensuring early detection of auth issues.
• Publish test reports as artifacts or send notifications on test results.

Best Practices

1. Use Custom Commands: Encapsulate token retrieval and storage in Cypress custom commands for reuse and clarity.
2. Isolate Authentication Logic: Keep token handling code separate in support files to avoid duplication.
3. Secure Credentials: Never hardcode sensitive data in test code; use environment variables or secure files.
4. Use Fixtures for Test Data: Store user info and other static data in fixtures for easy updates.
5. Validate Token Expiry: Refresh tokens or re-authenticate as needed to avoid flaky tests.

Self Check

Where would you add a new helper function to refresh an expired token in this framework structure?

Key Result

Organize token-based authentication by separating token logic in support files, using custom commands, and managing credentials securely.