CodeceptJS 测试框架安装指南-优快云博客

CodeceptJS 测试框架安装指南

概述

CodeceptJS 是一个现代化的端到端（End-to-End）测试框架，采用特殊的 BDD（行为驱动开发）风格语法。它通过统一的 API 抽象了不同测试后端的复杂性，支持 Playwright、Puppeteer、WebDriver、TestCafe 等多种测试引擎。

本文将为您提供完整的 CodeceptJS 安装和配置指南，涵盖从环境准备到第一个测试用例运行的全过程。

环境要求

在开始安装之前，请确保您的系统满足以下基本要求：

组件	最低版本	推荐版本
Node.js	16.0+	18.0+
npm	5.6.0+	8.0+
操作系统	Windows 7+ / macOS 10.12+ / Linux	最新稳定版

安装方式对比

CodeceptJS 提供多种安装方式，您可以根据项目需求选择最适合的方案：

mermaid

方法一：使用快速安装器（推荐新手）

这是最简单快捷的安装方式，特别适合初学者：

安装 Playwright 版本

npx create-codeceptjs .

安装 Puppeteer 版本

npx create-codeceptjs . --puppeteer

安装 WebDriver 版本

npx create-codeceptjs . --webdriverio

安装到指定目录

npx create-codeceptjs e2e-tests --webdriverio

快速安装器会自动完成以下操作：

创建 package.json（如不存在）
安装 CodeceptJS 核心包
安装对应的测试引擎（Playwright/Puppeteer/WebDriver）
创建基础配置文件
生成示例测试文件

方法二：标准安装流程

对于现有项目或需要更多控制权的用户，推荐使用标准安装流程：

步骤 1：初始化项目

# 如果目录中没有 package.json，先初始化
npm init -y

步骤 2：安装 CodeceptJS

npm install codeceptjs --save-dev

步骤 3：初始化配置

npx codeceptjs init

初始化过程会交互式地询问以下配置信息：

问题	默认值	说明
是否使用 TypeScript？	No	选择是否启用 TypeScript 支持
测试文件位置	`./*_test.js`	测试文件的匹配模式
使用的 Helper	Playwright	选择测试引擎
输出目录	`./output`	日志、截图、报告的存储位置
是否启用本地化？	English	测试脚本的语言本地化

步骤 4：安装对应 Helper 的依赖

根据选择的 Helper，可能需要额外安装依赖：

# Playwright
npm install @playwright/test --save-dev

# Puppeteer  
npm install puppeteer --save-dev

# WebDriver
npm install webdriverio --save-dev

# TestCafe
npm install testcafe --save-dev

不同 Helper 的额外配置

Playwright 配置

Playwright 是默认推荐的选择，安装简单且功能强大：

// codecept.conf.js
exports.config = {
  helpers: {
    Playwright: {
      url: 'http://localhost',
      show: true, // 显示浏览器窗口
      browser: 'chromium', // chromium, firefox, webkit
      restart: false,
      keepBrowserState: true,
      keepCookies: true
    }
  }
}

WebDriver 配置

WebDriver 需要额外的 Selenium 服务：

# 安装 Selenium Standalone
npm install selenium-standalone --save-dev
npx selenium-standalone install
npx selenium-standalone start

或者使用 Docker：

docker run -d -p 4444:4444 selenium/standalone-chrome

Puppeteer 配置

exports.config = {
  helpers: {
    Puppeteer: {
      url: 'http://localhost',
      show: true,
      chrome: {
        args: ['--no-sandbox', '--disable-setuid-sandbox']
      }
    }
  }
}

项目结构

成功安装后，您的项目结构应该如下所示：

project-root/
├── codecept.conf.js      # 主配置文件
├── jsconfig.json         # JS 配置（如使用 TypeScript）
├── package.json          # 项目依赖
├── steps.d.ts            # TypeScript 定义文件
├── output/               # 测试输出目录
│   ├── logs/            # 日志文件
│   ├── screenshots/     # 失败截图
│   └── reports/         # 测试报告
└── tests/               # 测试文件目录
    ├── *_test.js        # 测试文件
    └── pages/           # 页面对象目录

创建第一个测试

生成测试模板

npx codeceptjs generate:test

编写简单测试

// tests/demo_test.js
Feature('CodeceptJS 演示测试');

Scenario('检查首页欢迎信息', ({ I }) => {
  I.amOnPage('/');
  I.see('欢迎');
  I.seeElement('.header');
  I.click('登录');
  I.seeInCurrentUrl('/login');
});

运行测试

# 运行所有测试
npx codeceptjs run

# 运行特定测试文件
npx codeceptjs run tests/demo_test.js

# 显示详细步骤
npx codeceptjs run --steps

# 调试模式
npx codeceptjs run --debug

常用命令速查表

命令	功能描述	示例
`npx codeceptjs init`	初始化配置	`npx codeceptjs init`
`npx codeceptjs run`	运行所有测试	`npx codeceptjs run`
`npx codeceptjs run-workers`	并行运行测试	`npx codeceptjs run-workers 3`
`npx codeceptjs generate:test`	生成测试文件	`npx codeceptjs generate:test`
`npx codeceptjs generate:pageobject`	生成页面对象	`npx codeceptjs generate:pageobject`
`npx codeceptjs shell`	交互式命令行	`npx codeceptjs shell`
`npx codeceptjs list`	查看可用命令	`npx codeceptjs list`
`npx codeceptjs def`	生成类型定义	`npx codeceptjs def`

配置示例

基础配置文件

// codecept.conf.js
exports.config = {
  tests: './tests/*_test.js',
  output: './output',
  helpers: {
    Playwright: {
      url: 'http://localhost:3000',
      show: true,
      browser: 'chromium',
      waitForTimeout: 5000,
      waitForNavigation: 'load',
      waitForAction: 100
    }
  },
  include: {
    I: './steps_file.js'
  },
  bootstrap: null,
  mocha: {},
  name: 'my-test-project'
}

多环境配置

// codecept.ci.conf.js
const { setHeadlessWhen } = require('@codeceptjs/configure');

setHeadlessWhen(process.env.CI);

exports.config = {
  helpers: {
    Playwright: {
      url: process.env.BASE_URL || 'http://localhost:3000',
      show: !process.env.CI,
      browser: 'chromium'
    }
  }
}

常见问题解决

1. 安装失败

问题: npm 安装过程中出现权限错误 解决方案:

# 使用 nvm 管理 Node.js 版本
nvm install 18
nvm use 18

# 或者使用 sudo（不推荐）
sudo npm install -g codeceptjs

2. WebDriver 连接失败

问题: Selenium 服务器无法连接 解决方案:

# 检查 Selenium 状态
npx selenium-standalone status

# 启动 Selenium
npx selenium-standalone start

# 或者使用 Docker
docker run -d -p 4444:4444 selenium/standalone-chrome

3. 浏览器无法启动

问题: Playwright/Puppeteer 浏览器无法启动 解决方案:

# 安装浏览器依赖
npx playwright install
# 或
npx puppeteer browsers install chrome

最佳实践

1. 使用 TypeScript（可选）

npm install typescript ts-node --save-dev
npx codeceptjs init # 选择 TypeScript

2. 配置 Git 忽略

# .gitignore
output/
node_modules/
*.log
.DS_Store

3. 添加 npm 脚本

{
  "scripts": {
    "test": "codeceptjs run",
    "test:headless": "HEADLESS=true codeceptjs run",
    "test:ui": "codeceptjs ui",
    "test:workers": "codeceptjs run-workers 2"
  }
}

总结

CodeceptJS 提供了一个强大而简单的端到端测试解决方案。通过本指南，您应该能够：

✅ 正确安装和配置 CodeceptJS
✅ 选择适合项目的测试引擎（Helper）
✅ 创建并运行第一个测试用例
✅ 理解基本的项目结构和配置
✅ 解决常见的安装问题

无论您是选择快速的 create-codeceptjs 安装器还是标准的手动安装流程，CodeceptJS 都能为您提供一致的、开发者友好的测试体验。开始编写您的第一个测试，体验 CodeceptJS 带来的测试便利吧！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考