How to Handle Authentication and Authorization in Cypress?

With the widespread adoption of Single-Page Applications (SPAs) and microservices architecture, authentication and authorization testing have become critical. Traditional testing frameworks often rely on external tools or manual cookie management, but Cypress simplifies this process through its built-in APIs and plugin ecosystem. According to Cypress official documentation, authentication testing must cover login flows, session persistence, and permission validation, otherwise test results may be unreliable. In actual projects, incorrect authentication handling can lead to test failures or security vulnerabilities, so mastering Cypress's authentication mechanisms is an essential skill for frontend test engineers.

Main Content

The core of authentication is simulating user identity verification. Cypress provides the cy.session() method to manage sessions, avoiding repeated login operations. Its working principle is: when tests execute, Cypress checks the session stored in local storage; if it doesn't exist, it automatically executes the login process and stores session data. This significantly enhances test efficiency.

Key Steps:

Use cy.session() to set authentication sessions: Create a custom session to store authentication tokens.
Handle login flows: Reuse sessions in tests to avoid repeating login steps.

Code Example:

javascript
// Define authentication session: using Cypress Session API
// Note: Enable session functionality in Cypress config (e.g., set 'experimentalSession': true in cypress.config.js)
beforeEach(() => {
  cy.session('authenticated-user', () => {
    // Step 1: Visit login page
    cy.visit('/login');
    // Step 2: Input credentials (use data-testid selectors for maintainability)
    cy.get('[data-testid="username"]', { timeout: 5000 }).type('testuser');
    cy.get('[data-testid="password"]', { timeout: 5000 }).type('securepass');
    // Step 3: Submit form and verify redirection
    cy.get('[data-testid="submit"]', { timeout: 5000 }).click();
    cy.url().should('include', '/dashboard');
    // Step 4: Verify cookies (optional for debugging)
    cy.getCookie('auth_token').should('exist');
  });
});

// Reuse session in tests
it('Access protected dashboard', () => {
  cy.visit('/dashboard');
  cy.get('[data-testid="welcome-message"]', { timeout: 5000 }).should('contain', 'Welcome');
});

Notes:

Session validity: By default, sessions expire when the browser closes; configure persistence using cy.session()'s on option (e.g., using localStorage).
Error handling: Add try/catch for login failures, e.g.:

javascript
try {
  cy.get('[data-testid="error-message"]', { timeout: 5000 }).should('be.visible');
} catch {
  // Handle authentication failure
}

2. Authorization Handling: Verifying User Permissions

Authorization involves checking user roles or permissions to ensure users can only access resources within their scope. Cypress uses cy.request() or cy.intercept() to simulate API requests, combined with response validation, for authorization testing.

Core Strategies:

API Interception: Use cy.intercept() to intercept authentication requests and validate returned permission information.
Status Code Checks: Ensure 403 Forbidden or 200 OK status codes match expectations.

Code Example:

javascript
// Use cy.intercept to verify API permissions
it('Test admin permissions', () => {
  // Step 1: Set authentication session (as above)
  cy.session('admin-user', () => {
    // ... login flow (omitted)
  });

  // Step 2: Intercept permission check request
  cy.intercept('GET', '/api/protected-resource').as('permissionCheck');

  // Step 3: Send request and verify response
  cy.visit('/admin');
  cy.get('[data-testid="admin-content"]', { timeout: 5000 }).should('be.visible');
  cy.wait('@permissionCheck', { timeout: 10000 }).then((interception) => {
    expect(interception.response.statusCode).to.equal(200);
    expect(interception.response.body.role).to.equal('admin');
  });
});

// Use cy.request to directly test authorization
it('Test regular user permissions', () => {
  cy.request({
    url: '/api/protected-resource',
    method: 'GET',
    headers: { Authorization: 'Bearer ' + Cypress.env('token') }
  }).then((response) => {
    expect(response.status).to.equal(403);
  });
});

Best Practices:

Simulate different roles: Create multiple sessions (e.g., user-session, admin-session) and manage role switching with cy.session().
Avoid hardcoding: Use environment variables (e.g., Cypress.env('token')) to store tokens, enhancing test configurability.

3. Handling Cookies and Storage

In authentication, Cookies and localStorage are key storage carriers. Cypress provides flexible APIs to operate on these objects:

Read Cookies: cy.getCookie(name) verifies token existence.
Manage Storage: cy.getCookie() and cy.clearLocalStorage() manage session data.

Code Example:

javascript
// Verify authentication status
it('Check authentication cookies', () => {
  cy.visit('/dashboard');
  cy.getCookie('auth_token').should('exist');
  cy.getCookie('auth_token').then((cookie) => {
    expect(cookie.value).to.include('Bearer');
  });
});

// Clear storage to avoid test pollution
beforeEach(() => {
  cy.clearLocalStorage();
  cy.clearCookies();
});

Security Tips:

Handle sensitive data: Avoid hardcoding passwords in tests; use environment variables (e.g., .env files) or key management services (e.g., AWS Secrets Manager).
Test isolation: Call cy.clearLocalStorage() before each test case to ensure test independence.

4. Integrating Plugins and Advanced Techniques

Cypress's ecosystem provides additional tools for complex scenarios, such as:

cypress-plugin-request: Simplifies API testing.
cypress-auth: Specifically handles authentication flows.

Practical Recommendations:

Install plugins: Run npm install cypress-auth in your project, then configure in cypress.config.js:

javascript
module.exports = {
  plugins: {
    addCypressAuth: {
      // Configure authentication strategy
      provider: 'local',
      url: '/login',
      tokenName: 'auth_token',
    },
  },
};

Handle JWT: For JSON Web Tokens (JWT), use cy.request() to check token validity, e.g.:

javascript
cy.request('/api/validate-token', { method: 'GET' }).then((res) => {
  expect(res.body.valid).to.be.true;
});

Pitfall Guide:

Browser context: Cypress tests run in isolated browsers; ensure cy.visit uses the correct context.
Cross-origin issues: When testing third-party APIs, enable --disable-web-security (only for development) or configure a proxy.

Conclusion

Handling authentication and authorization in Cypress requires systematic test design. By using cy.session() to manage sessions, cy.intercept() to validate permissions, and cy.request() to simulate API calls, developers can build efficient and secure test suites. Key points include:

Automate login flows: Avoid manual repetition.
Validate states: Always check response status codes and bodies.
Test isolation: Use clearLocalStorage and clearCookies to ensure reliability.

Ultimately, authentication and authorization testing is a critical aspect of software quality. We recommend referring to the Cypress official documentation for the latest updates and customizing test strategies based on project needs. Remember: security testing is not optional—it is mandatory!

Note: This article is based on Cypress v13.0+ versions. Adjust code examples according to your project to ensure compatibility with your application architecture.

Main Content

1. Authentication Handling: Simulating User Login

2. Authorization Handling: Verifying User Permissions

3. Handling Cookies and Storage

4. Integrating Plugins and Advanced Techniques

Conclusion

Reference Resources