如何在 Cypress 中处理认证和授权？

在现代 Web 应用开发中，认证（Authentication）和授权（Authorization）是保障系统安全的核心环节。Cypress 作为一款强大的端到端测试框架，提供了丰富的机制来模拟用户登录、管理会话和验证权限，从而确保测试用例能够准确反映真实用户场景。本文将深入探讨如何在 Cypress 中高效处理认证和授权，涵盖常见模式、代码实践和避坑指南，帮助开发者构建健壮的测试套件。

引言

随着单页应用（SPA）和微服务架构的普及，认证和授权测试变得至关重要。传统测试框架往往依赖外部工具或手动管理 cookies，但 Cypress 通过其内置 API 和插件生态系统，简化了这一过程。根据 Cypress 官方文档，认证测试应覆盖登录流程、会话持久化和权限验证，否则可能导致测试结果不可靠。在实际项目中，错误的认证处理会引发测试失败或安全漏洞，因此掌握 Cypress 的认证机制是前端测试工程师必备技能。

主体内容

1. 认证处理：模拟用户登录

认证的核心是模拟用户身份验证。Cypress 提供 cy.session() 方法管理会话，避免重复登录操作。其工作原理是：当测试执行时，Cypress 会检查本地存储中的会话；若不存在，则自动执行登录流程并存储会话数据。这显著提升了测试效率。

关键步骤：

• 使用 cy.session() 设置认证会话：创建一个自定义会话，用于存储认证令牌。
• 处理登录流程：在测试中重用会话，避免重复执行登录步骤。

代码示例：

javascript
// 定义认证会话：使用 Cypress Session API
// 注意：需在 Cypress 配置中启用 session 功能（如 cypress.config.js 中设置 'experimentalSession': true）
beforeEach(() => {
  cy.session('authenticated-user', () => {
    // 步骤1：访问登录页面
    cy.visit('/login');
    // 步骤2：输入凭据（使用 data-testid 选择器增强可维护性）
    cy.get('[data-testid="username"]', { timeout: 5000 }).type('testuser');
    cy.get('[data-testid="password"]', { timeout: 5000 }).type('securepass');
    // 步骤3：提交表单并验证重定向
    cy.get('[data-testid="submit"]', { timeout: 5000 }).click();
    cy.url().should('include', '/dashboard');
    // 步骤4：验证 cookies（可选，用于调试）
    cy.getCookie('auth_token').should('exist');
  });
});

// 在测试中重用会话
it('访问受保护的仪表盘', () => {
  cy.visit('/dashboard');
  cy.get('[data-testid="welcome-message"]', { timeout: 5000 }).should('contain', 'Welcome');
});

注意事项：

• 会话有效期：默认会话在浏览器关闭时失效，可通过 cy.session() 的 on 选项配置持久化（例如使用 localStorage）。
• 错误处理：添加 try/catch 处理登录失败场景，例如：

javascript
try {
  cy.get('[data-testid="error-message"]', { timeout: 5000 }).should('be.visible');
} catch {
  // 处理认证失败
}

2. 授权处理：验证用户权限

授权涉及检查用户角色或权限，确保用户只能访问其权限范围内的资源。Cypress 通过 cy.request() 或 cy.intercept() 模拟 API 请求，结合响应验证，实现授权测试。

核心策略：

• API 拦截：使用 cy.intercept() 拦截认证请求，验证返回的权限信息。
• 状态码检查：确保 403 Forbidden 或 200 OK 状态码符合预期。

代码示例：

javascript
// 使用 cy.intercept 验证 API 权限
it('测试管理员权限', () => {
  // 步骤1：设置认证会话（同上文）
  cy.session('admin-user', () => {
    // ... 登录流程（略）
  });

  // 步骤2：拦截权限检查请求
  cy.intercept('GET', '/api/protected-resource').as('permissionCheck');

  // 步骤3：发送请求并验证响应
  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');
  });
});

// 使用 cy.request 直接测试授权
it('测试普通用户权限', () => {
  cy.request({
    url: '/api/protected-resource',
    method: 'GET',
    headers: { Authorization: 'Bearer ' + Cypress.env('token') }
  }).then((response) => {
    expect(response.status).to.equal(403);
  });
});

最佳实践：

• 模拟不同角色：创建多个会话（如 user-session, admin-session），通过 cy.session() 管理角色切换。
• 避免硬编码：使用环境变量（如 Cypress.env('token')）存储令牌，增强测试可配置性。

3. 处理 Cookies 和 Storage

在认证过程中，Cookies 和 localStorage 是关键存储载体。Cypress 提供了灵活的 API 来操作这些对象：

• 读取 Cookies：cy.getCookie(name) 验证令牌存在性。
• 操作 Storage：cy.getCookie() 和 cy.clearLocalStorage() 管理会话数据。

代码示例：

javascript
// 验证认证状态
it('检查认证 cookies', () => {
  cy.visit('/dashboard');
  cy.getCookie('auth_token').should('exist');
  cy.getCookie('auth_token').then((cookie) => {
    expect(cookie.value).to.include('Bearer');
  });
});

// 清理存储以避免测试污染
beforeEach(() => {
  cy.clearLocalStorage();
  cy.clearCookies();
});

安全提示：

• 敏感数据处理：在测试中，避免硬编码密码；使用环境变量（如 .env 文件）或密钥管理服务（如 AWS Secrets Manager）。
• 测试隔离：每个测试用例前调用 cy.clearLocalStorage() 确保测试独立性。

4. 集成插件与高级技巧

Cypress 生态系统提供了额外工具处理复杂场景，例如：

• cypress-plugin-request：简化 API 测试。
• cypress-auth：专门处理认证流程。

实践建议：

• 安装插件：在项目中运行 npm install cypress-auth，然后在 cypress.config.js 中配置：

javascript
module.exports = {
  plugins: {
    addCypressAuth: {
      // 配置认证策略
      provider: 'local',
      url: '/login',
      tokenName: 'auth_token',
    },
  },
};

• 处理 JWT：对于 JSON Web Token（JWT），使用 cy.request() 检查令牌有效性，例如：

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

避坑指南：

• 浏览器上下文：Cypress 测试在独立浏览器中运行，确保 cy.visit 使用正确的上下文。
• 跨域问题：当测试涉及第三方 API 时，启用 --disable-web-security（仅限开发环境）或配置代理。

结论

在 Cypress 中处理认证和授权需要系统化的测试设计。通过 cy.session() 管理会话、cy.intercept() 验证权限和 cy.request() 模拟 API，开发者可以构建高效且安全的测试套件。关键在于：

• 自动化登录流程：避免手动重复操作。
• 状态验证：始终检查响应状态码和响应体。
• 测试隔离：使用 clearLocalStorage 和 clearCookies 确保测试可靠性。

最终，认证和授权测试是软件质量的重要一环。建议参考 Cypress 官方文档 获取最新更新，并结合项目需求定制测试策略。记住：安全测试不是可选的，而是必须的！

附注：本文基于 Cypress v13.0+ 版本撰写。请根据实际项目调整代码示例，确保与您的应用架构兼容。

参考资源

• Cypress Session API Documentation
• Cypress Authentication Guide
• Cypress Request API