codeceptjs-auth

CodeceptJS Auth Plugin

auth 插件会让每个用户登录一次，捕获 Cookie（或通过覆盖项捕获 localStorage／令牌），并为后续测试恢复会话。会话过期时会自动重新登录。

如果项目已配置 auth（fundamentals 的发现结果），请复用现有的 inject 名称和用户键，不要重新配置。

先做决定——询问用户

以下 4 个问题会影响插件配置。不要猜测答案。

1. 是否确实需要会话？ 公共流程（落地页、注册）→ 跳过插件。
2. 一个用户还是多个用户？ 默认一个；只有在确实需要测试时才添加更多用户。
3. 如果有多个用户——他们按什么区分？ 角色、工作区／租户、套餐等级、登录提供方、每个测试的固定数据——实际系统各不相同。请询问用户；根据答案命名 users.<key> 条目。
4. 认证类型是什么？
   • 表单——默认方式；标准结构如下
   • OAuth / SSO——点击提供方按钮，操作 IdP 页面（通常是单独的源）
   • 魔法链接／无密码——UI 流程通常不值得自动化；优先通过 API 生成令牌，或从测试邮箱读取链接
   • API 令牌——跳过表单；通过 executeScript 将令牌写入 localStorage，或使用 I.setCookie(...)
   • 2FA / OTP——使用异步 login；提交前从测试邮箱／后门获取验证码

规则

1. 登录流程绝不能写在 conf 中。 将其放在 steps_file.js（如果有）或页面对象中；conf 只负责引用：login: (I) => I.login()。
2. 凭据只能来自环境变量——通过 process.loadEnvFile() 加载 .env（无需 dotenv 依赖）。密码必须用 secret(...) 包装。任何地方都不得写入明文——conf、步骤文件、测试、Git 历史记录均不例外。
3. .env 必须加入 gitignore；.env.example 必须提交，只写变量名，不写值。也要将 output/*_session.json 加入 gitignore。

标准结构

// codecept.conf.js — first line of the file
process.loadEnvFile()

export const config = {
  include: { I: './steps_file.js' },
  plugins: {
    auth: {
      enabled: true,
      saveToFile: true,
      users: {
        admin: {
          login: (I) => I.login(),
          check: (I) => I.see('Welcome, User', '.navbar'),
        },
      },
    },
  },
}

// steps_file.js
import { secret } from 'codeceptjs'
const { I } = inject()

export default function () {
  return actor({
    login() {
      I.amOnPage('/login')
      I.fillField('Email', process.env.ADMIN_EMAIL)
      I.fillField('Password', secret(process.env.ADMIN_PASSWORD))
      I.click('Sign in')
    },
  })
}

# .env (gitignored)        # .env.example (committed)
USER_EMAIL=...             USER_EMAIL=
USER_PASSWORD=<secret>     USER_PASSWORD=

准备工作（编写配置前）

1. 读取实际登录页——使用 MCP run_code 打开 /login，检查 ARIA 快照（codeceptjs-exploration）。字段标签／name／id／提交控件必须来自实际页面，不能凭猜测。授权机制不明确时，请询问用户。
2. 选择特定角色的登录后标记——选择仅为此用户呈现的内容（导航栏用户名、data-user-role）。
3. 确认会话存储方式——服务端渲染应用默认使用 Cookie；SPA 使用 localStorage／sessionStorage。手动登录后，通过 I.executeScript(() => Object.keys(localStorage)) 验证。对于令牌存储，Cookie 获取／恢复会静默地不执行任何操作。

验证

运行一个只包含一个 Scenario 的文件，调用 login(<role>)，然后断言登录后标记：

npx codeceptjs run --grep '<scenario>' --debug    # real run, not dry — dry-run doesn't init plugins

只有此往返验证成功后，才启用 saveToFile: true——错误的已保存会话会掩盖有问题的 login。

然后将其接入钩子／测试：全套测试共用时使用 Before(({ login }) => login())；也可按需在单个测试中调用。

多角色结构

仅在回答了问题 3 后再配置。键名应反映此系统中区分用户的方式；每个键对应一个 actor 方法：

users: {
  admin:      { login: (I) => I.loginAsAdmin() },
  workspaceB: { login: (I) => I.loginToWorkspaceB() },
}

不要将其参数化为单个 login(key)——插件按名称区分会话，显式方法更易读。在同一个 Scenario 中切换：session('<key>') 会打开并行浏览器上下文（fundamentals § 编写测试）。

令牌／localStorage 认证

当会话存储在 Cookie 以外的位置时，覆盖 fetch／restore：

admin: {
  login: (I) => I.loginAsAdmin(),
  check: (I) => I.see('Admin', '.navbar'),
  fetch: (I) => I.executeScript(() => localStorage.getItem('session_id')),
  restore: (I, session) => {
    I.amOnPage('/')
    I.executeScript((s) => localStorage.setItem('session_id', s), session)
  },
}

check(I, session) 接收 fetch 返回的内容——在 check 中抛出错误即可强制重新登录（例如 /me 端点显示了错误的用户）。

常见问题

• 在 conf／测试中内嵌凭据——始终使用环境变量并通过 secret() 包装。
• 忘记将 .env 和 output/*_session.json 加入 gitignore——二者都会泄露凭据。

相关技能

• codeceptjs-fundamentals——密钥规则、会话、配置修改陷阱
• codeceptjs-exploration——读取实时登录页
• writing-codeceptjs-tests / refactoring-codeceptjs-tests——识别出认证需求时调用此技能
• debugging-codeceptjs-tests——认证相关的故障模式