@yeepay/e2e-auth

企业级 E2E 测试认证框架

统一 E2E 登录认证，让自动化测试更简单

快速开始 • 核心特性 • 使用文档 • API 文档 • 贡献指南

📖 项目简介

@yeepay/e2e-auth 是一个专为企业级应用设计的 E2E 测试认证框架，提供统一的、可复用的登录认证能力。支持多系统（BOSS 运营后台、Merchant 商户后台）、多环境（SIT、UAT、生产）、多角色的自动化登录流程。

🎯 为什么选择 @yeepay/e2e-auth？

• ✅ 开箱即用：一行代码完成登录，零配置快速开始
• ✅ 类型安全：TypeScript + Zod 双重类型保障
• ✅ 高度可复用：跨项目、跨系统、跨环境复用
• ✅ 企业级架构：分层设计、设计模式、可扩展性
• ✅ 智能重试：内置重试机制，提高测试稳定性
• ✅ 权限管理：基于角色的访问控制（RBAC）

✨ 核心特性

🔐 多种认证策略

| 策略 | 适用场景 | 特点 | |------|---------|------| | SSO 认证 | 单点登录系统 | 跨域认证、Token 管理、会话同步 | | 表单认证 | 传统登录页面 | 多选择器策略、验证码处理、智能等待 | | Token 注入 | 快速测试场景 | 绕过登录流程、直接注入凭证、提升速度 |

🌍 多环境支持

// 支持多种环境配置
const environments = ['sit', 'uat', 'production'];

// 灵活切换环境
await ensureLoggedIn(page, {
  role: 'ADMIN',
  env: 'sit' // 或 'uat', 'production'
});

👤 角色权限体系

内置基于角色的访问控制（RBAC）系统：

| 角色 | 权限级别 | 典型用途 | |------|---------|---------| | ADMIN | 100 | 超级管理员，系统配置 | | DEVELOPER | 80 | 开发人员，功能开发 | | AUDITOR | 70 | 审计人员，合规检查 | | OPERATOR | 60 | 运营人员，日常操作 | | VIEWER | 20 | 只读用户，数据查看 |

🔄 智能重试机制

// 自动重试，提高测试稳定性
await ensureLoggedIn(page, {
  role: 'ADMIN',
  retryCount: 3,      // 重试次数
  retryDelay: 2000,   // 重试延迟（毫秒）
});

🚀 快速开始

安装

# 使用 pnpm（推荐）
pnpm add @yeepay/e2e-auth

# 使用 npm
npm install @yeepay/e2e-auth

# 使用 yarn
yarn add @yeepay/e2e-auth

基础用法

方式一：最简单的方式（推荐新手）

import { test } from '@playwright/test';
import { ensureLoggedIn } from '@yeepay/e2e-auth';

test('访问仪表盘', async ({ page }) => {
  // 一行代码完成登录
  await ensureLoggedIn(page, { role: 'ADMIN' });

  // 开始测试业务逻辑
  await page.goto('/dashboard');
  // ... 你的测试代码
});

方式二：使用 LoginManager（推荐）

import { setupAuth } from '@yeepay/e2e-auth';

test('完整的认证流程', async ({ page }) => {
  // 创建认证管理器
  const auth = setupAuth(page, {
    currentEnv: 'sit',
    provider: 'form',
  });

  // 登录
  await auth.ensureLoggedIn({ role: 'DEVELOPER' });

  // 获取当前用户信息
  const user = auth.getCurrentUser();
  console.log('当前用户:', user?.username);

  // 检查权限
  const roleManager = auth.getRoleManager();
  if (roleManager.hasPermission('datasource:create')) {
    // 执行需要权限的操作
  }

  // 登出
  await auth.logout();
});

方式三：使用 Flow 模式

const { ensureBossLoggedIn } = require('@yeepay/e2e-auth/boss');

test('BOSS 系统登录', async ({ page }) => {
  // BOSS 登录（带重试）
  const success = await ensureBossLoggedIn(page, {
    role: 'DEVELOPER',
    retryCount: 3,
    retryDelay: 2000,
  });

  if (success) {
    // 登录成功，继续测试
  }
});

方式四：使用 Page Object 模式

const { LoginPage, DashboardPage } = require('@yeepay/e2e-auth/boss/pages');

test('使用 Page Object', async ({ page }) => {
  const loginPage = new LoginPage(page);
  const dashboard = new DashboardPage(page);

  await loginPage.goto();
  await loginPage.login('admin', 'password123');
  await expect(dashboard.userInfo).toBeVisible();
});

📚 使用指南

环境配置

1. 使用配置文件（推荐）

创建 config/env.sit.json：

{
  "name": "SIT",
  "description": "系统集成测试环境",
  "boss": {
    "baseUrl": "https://sit-boss.yeepay.com",
    "apiUrl": "https://sit-boss-api.yeepay.com",
    "ssoUrl": "https://sit-sso.yeepay.com"
  },
  "timeout": {
    "navigation": 30000,
    "element": 10000,
    "api": 15000
  },
  "retry": {
    "count": 3,
    "delay": 2000
  }
}

2. 使用环境变量

# .env 文件
BOSS_ADMIN_USERNAME=admin
BOSS_ADMIN_PASSWORD=admin123
BOSS_DEV_USERNAME=developer
BOSS_DEV_PASSWORD=dev123

账号配置支持环境变量：

{
  "sit": {
    "ADMIN": {
      "username": "${BOSS_ADMIN_USERNAME:-admin}",
      "password": "${BOSS_ADMIN_PASSWORD:-admin123}"
    }
  }
}

3. 程序化配置

import { setupAuth } from '@yeepay/e2e-auth';

const auth = setupAuth(page, {
  currentEnv: 'sit',
  provider: 'form',
  environments: {
    sit: {
      name: 'SIT',
      baseUrl: 'https://sit-boss.yeepay.com',
      timeout: { navigation: 30000, element: 10000 },
      retry: { count: 3, delay: 2000 },
    },
  },
  accounts: {
    sit: {
      ADMIN: {
        username: 'admin',
        password: 'admin123',
        role: 'ADMIN',
        permissions: ['*'],
      },
    },
  },
});

权限管理

const roleManager = auth.getRoleManager();

// 检查单个权限
if (roleManager.hasPermission('datasource:create')) {
  console.log('有创建数据源的权限');
}

// 检查多个权限（任一）
if (roleManager.hasAnyPermission(['datasource:create', 'datasource:update'])) {
  console.log('有创建或更新数据源的权限');
}

// 检查多个权限（全部）
if (roleManager.hasAllPermissions(['query:read', 'query:execute'])) {
  console.log('有读取和执行查询的权限');
}

// 角色管理
if (roleManager.canManageRole('OPERATOR')) {
  console.log('可以管理 OPERATOR 角色');
}

// 获取可管理的角色列表
const manageableRoles = roleManager.getManageableRoles();
console.log('可管理的角色:', manageableRoles);

🔧 API 文档

核心 API

ensureLoggedIn(page, options)

确保用户已登录，如果未登录则自动登录。

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | page | Page | ✅ | Playwright Page 对象 | | options.role | string | ✅ | 用户角色（ADMIN、DEVELOPER 等） | | options.env | string | ❌ | 环境（默认：sit） | | options.retryCount | number | ❌ | 重试次数（默认：3） | | options.retryDelay | number | ❌ | 重试延迟（默认：2000ms） |

返回值： Promise<boolean> - 登录是否成功

示例：

await ensureLoggedIn(page, {
  role: 'ADMIN',
  env: 'sit',
  retryCount: 3,
  retryDelay: 2000,
});

setupAuth(page, config)

创建认证管理器实例。

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | page | Page | ✅ | Playwright Page 对象 | | config | AuthConfig | ✅ | 认证配置对象 |

返回值： LoginManager - 认证管理器实例

示例：

const auth = setupAuth(page, {
  currentEnv: 'sit',
  provider: 'form',
});

await auth.ensureLoggedIn({ role: 'ADMIN' });
const user = auth.getCurrentUser();
await auth.logout();

LoginManager API

| 方法 | 说明 | 返回值 | |------|------|--------| | ensureLoggedIn(options) | 确保已登录 | Promise<boolean> | | login(options) | 执行登录 | Promise<LoginResult> | | logout() | 执行登出 | Promise<boolean> | | isLoggedIn() | 检查登录状态 | Promise<boolean> | | getCurrentUser() | 获取当前用户 | UserAccount \| null | | getRoleManager() | 获取角色管理器 | RoleManager | | getSession() | 获取会话信息 | Promise<SessionState> |

RoleManager API

| 方法 | 说明 | 返回值 | |------|------|--------| | hasPermission(permission) | 检查单个权限 | boolean | | hasAnyPermission(permissions) | 检查多个权限（任一） | boolean | | hasAllPermissions(permissions) | 检查多个权限（全部） | boolean | | canManageRole(targetRole) | 是否可管理目标角色 | boolean | | getManageableRoles() | 获取可管理的角色列表 | string[] |

🧪 测试命令

# 安装依赖
pnpm install

# 运行所有测试
pnpm test

# 冒烟测试
pnpm test:smoke

# 回归测试
pnpm test:regression

# BOSS 系统测试
pnpm test:boss

# Merchant 系统测试
pnpm test:merchant

# 生成测试报告
pnpm test:report

# 调试模式
pnpm test --debug

# 指定浏览器
pnpm test --project=chromium
pnpm test --project=firefox
pnpm test --project=webkit

📦 项目结构

yeepay-e2e-auth/
├── src/
│   ├── core/              # 核心模块（LoginManager、AuthHelper、RoleManager）
│   ├── providers/         # 认证提供者（SSO、Form、Token）
│   ├── utils/             # 工具函数（Logger、Retry、Storage）
│   ├── types/             # TypeScript 类型定义
│   ├── config/            # 配置管理
│   ├── boss/              # BOSS 系统模块
│   └── merchant/          # Merchant 系统模块
├── config/                # 环境配置
├── data/                  # 测试数据
├── docs/                  # 项目文档
└── tests/                 # 测试用例

🤝 贡献指南

我们欢迎所有形式的贡献！

如何贡献

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

开发规范

• 遵循 代码规范
• 编写单元测试
• 更新相关文档
• 提交前运行 pnpm test

📄 许可证

本项目采用 MIT 许可证。

👥 团队

由易宝支付测试团队维护。

核心贡献者

• 项目负责人: @dreambt
• 架构设计: 测试架构组
• 开发团队: E2E 测试团队

🔗 相关链接

• 环境搭建指南
• 代码规范
• 架构设计文档
• Playwright 官方文档
• GitLab 项目地址

📞 支持与反馈

如果您在使用过程中遇到问题或有任何建议，请通过以下方式联系我们：

• 📧 邮件: [email protected]
• 💬 Issue: 提交 Issue
• 📖 文档: 查看文档

@yeepay/e2e-auth

让 E2E 测试更简单、更可靠、更高效

Built with ❤️ by YeePay Test Team