Eclipse Che E2E 测试代码规范指南:ESLint/Prettier 自动化检查与 Page Object/Mocha 编码约定
Eclipse Che E2E 测试代码规范指南:ESLint/Prettier 自动化检查与 Page Object/Mocha 编码约定
本文基于 tests/e2e/CODE_STYLE.md 编写,结合仓库源码与真实测试用例深度验证。Eclipse Che 的端到端(E2E)测试代码库是一套基于 TypeScript、Selenium WebDriver、Mocha 与 Inversify 依赖注入构建的工程,本文将从编码标准的意义、自动化工具链、Page Object 与 Util 类的推荐写法、Mocha 测试组织规范、包管理与注释约定五个维度,完整讲解这套代码库的编码纪律,并逐一对照源码给出可验证的实现依据,帮助你在为 Che 贡献 E2E 测试时写出风格统一、易于维护、可通过 lint 检查的代码。
为什么编码标准如此重要
在 Eclipse Che 的 E2E 测试仓库中,测试代码覆盖 Dashboard、IDE(Che-Code 编辑器)、OpenShift 控制台、Web Terminal 等多个页面对象,单个 Spec 文件动辄上百行,页面对象类的协作关系复杂。此时如果没有统一的编码标准,代码将迅速陷入"每个人风格不同、彼此难以理解"的混乱局面。CODE_STYLE.md 开篇总结了编码标准的六大价值:
- 提升代码质量:遵循编码标准可以让代码更安全、高效、可维护且风格统一,从而减少错误、提升整体性能;
- 改善可读性与可维护性:格式一致的代码帮助其他开发者快速理解与修改,节省时间并降低引入缺陷的概率;
- 加速开发:当开发者遵循既定规则时,可以更快地产出且犯错更少;统一的格式也让问题的定位与解决更加高效;
- 更好的可扩展性:一致的编码实践让新增功能或更新变得简单,随着代码库扩张,维护成本得以控制;
- 提升协作与沟通:统一规范让开发者更容易理解和接手同事编写的代码,促进团队协作与代码共享;
- 跨项目一致性:编码标准的落地保证不同项目间采用一致的编码方式,简化质量把控、任务切换与协作流程。
这六点并非空泛口号——在 tests/e2e/package.json 中可以看到整个测试工程通过 lint、prettier、tsc 等脚本将规范固化为可执行的门禁,下文将逐一展开。
自动化工具链:ESLint、Prettier 与 Husky pre-commit
CODE_STYLE.md 明确指出:每次提交(commit)之前,使用 Husky pre-commit hook 自动执行 ESLint 与 Prettier 进行 lint 检查与代码格式化。完整的规则集定义在以下两个文件中:
ESLint 规则要点
tests/e2e/.eslintrc.js 是一份基于 @typescript-eslint/recommended-type-checked 并叠加 prettier 插件的严格配置,核心规则包括:
| 规则 | 配置值 | 说明 |
|---|---|---|
prettier/prettier |
error |
Prettier 格式问题视为错误,与格式化工具联动 |
@typescript-eslint/member-ordering |
error |
类成员必须按 static-field → public-field → instance-field → constructor → public-method → private-method 顺序声明 |
@typescript-eslint/naming-convention |
error |
变量命名必须为 camelCase 或 UPPER_CASE,禁止前导/尾随下划线 |
@typescript-eslint/typedef |
error |
参数、属性、变量声明、成员变量必须显式声明类型 |
@typescript-eslint/quotes |
error |
字符串必须使用单引号 |
@typescript-eslint/explicit-function-return-type |
error |
函数必须显式标注返回类型 |
@typescript-eslint/member-delimiter-style |
error |
接口成员分隔符风格统一 |
@typescript-eslint/no-unused-vars / no-use-before-define |
error |
禁止未使用变量与先使用后定义 |
header/header |
error |
每个文件头部必须带 EPL-2.0 版权头(如 * copyright (c) 2023 Red Hat, Inc.) |
no-console |
error |
禁止直接使用 console(允许列表外的调用会被拦截,日志统一走 Logger 工具类) |
eqeqeq / curly / no-eval / no-debugger / radix |
error |
严格相等、强制花括号、禁止 eval/debugger、强制进制参数等 |
同时配置中对一些"宽松项"做了显式关闭,例如 @typescript-eslint/no-explicit-any、no-unsafe-member-access、no-unsafe-assignment、restrict-template-expressions 等,说明该工程在测试代码场景下允许一定程度的 any 使用,保持实用主义。
Prettier 格式约定
tests/e2e/.prettierrc.json 定义了最终的格式化输出:
{
"trailingComma": "none",
"tabWidth": 4,
"printWidth": 140,
"semi": true,
"singleQuote": true,
"useTabs": true,
"endOfLine": "lf",
"jsxSingleQuote": true
}
值得注意的几点:useTabs: true 表示使用 Tab 缩进而非空格;tabWidth: 4 规定了 Tab 的视觉宽度;printWidth: 140 允许单行最长 140 字符(与 .eslintrc.js 中 max-len 的 code: 140 呼应);trailingComma: none 表示不添加尾随逗号;字符串统一单引号。
提交前自动执行
在 tests/e2e/package.json 中可以看到相关脚本与依赖:
"scripts": {
"lint": "eslint --fix .",
"prettier": "prettier --config .prettierrc.json . --write",
...
},
"devDependencies": {
"husky": "^8.0.3",
"eslint": "^8.45.0",
"eslint-config-prettier": "^8.10.0",
"eslint-plugin-prettier": "^5.0.0",
...
}
工程通过 husky 注册 pre-commit hook,在每次提交前自动运行 eslint --fix 与 Prettier 格式化,从机制上保证"不合规代码进不了仓库"。
Page Object 与 Util 类的推荐代码风格
CODE_STYLE.md 用最大篇幅规定了 Page Object 与 Util 类的写法,这是本仓库最核心的编码约定,共四条硬性规则。
规则 1:使用 Inversify 依赖注入声明类
所有 Page Object 与 Util 类必须使用 @injectable() 装饰器,并通过构造函数注入依赖,例如 utils/BrowserTabsUtil.ts 中的真实代码:
@injectable()
export class BrowserTabsUtil {
constructor(@inject(CLASSES.DriverHelper) private readonly driverHelper: DriverHelper) { }
其中的 CLASSES 与 TYPES 统一在 configs/inversify.types.ts 中声明(CLASSES 存放类名映射,TYPES 存放 Symbol.for(...) 类型的接口标识),而所有绑定关系集中在 configs/inversify.config.ts 的 e2eContainer 中,例如:
const e2eContainer: Container = new Container({ defaultScope: 'Transient', skipBaseClassChecks: true });
e2eContainer.bind<IDriver>(TYPES.Driver).to(ChromeDriver).inSingletonScope();
e2eContainer.bind<BrowserTabsUtil>(CLASSES.BrowserTabsUtil).to(BrowserTabsUtil);
e2eContainer.bind<DriverHelper>(CLASSES.DriverHelper).to(DriverHelper);
测试或页面对象需要某个类时,统一通过 e2eContainer.get(CLASSES.XXX) 获取实例,而不是 new 一个对象。这也解释了为什么 CODE_STYLE.md 强制要求依赖注入——它让测试依赖关系可管理、可替换(例如根据 TS_PLATFORM 环境变量切换 OpenShift 或 Kubernetes 的登录页实现)。
规则 2:公开方法省略 public 关键字并记录日志
- 公开方法声明时不带
public关键字(TypeScript 默认即 public); - 方法内部第一行调用
Logger.debug()记录方法名(可选附带消息),便于排查测试执行链路。
示例(同样取自 utils/BrowserTabsUtil.ts):
async switchToWindow(windowHandle: string): Promise<void> {
Logger.debug(); // logs BrowserUtils.switchToWindow
await this.driverHelper.getDriver().switchTo().window(windowHandle);
}
Logger.debug() 之所以能自动打印调用者方法名,是因为 utils/Logger.ts 中 getCallerInfo() 通过解析调用栈(Error().stack)提取调用方函数名,并将日志按 ERROR / WARN / INFO / DEBUG / TRACE 分级(每级对应不同的缩进层级与控制台分组),同时支持向 Report Portal 转发日志。实际源码里 OcpMainPage 的每个公开方法都以 Logger.debug(); 开头,例如:
async waitOpenMainPage(): Promise<void> {
Logger.debug();
await this.driverHelper.waitVisibility(OcpMainPage.MAIN_PAGE_HEADER, TIMEOUT_CONSTANTS.TS_SELENIUM_LOAD_PAGE_TIMEOUT);
}
规则 3:定位器(Locator)的两种合法声明方式
- 静态定位器:声明为
private static readonly字段,类型为By:
private static readonly FACTORY_URL_LOCATOR: By = By.xpath('//input[@id="git-repo-url"]');
- 动态定位器:声明为返回
By的private方法(通常用于根据参数拼接 XPath):
private getExpandedActionsLocator(workspaceName: string): By {
return By.xpath(`${this.getWorkspaceListItemLocator(workspaceName)}//button[@aria-label='Actions' and @aria-expanded='true']`);
}
- 反例(✗):避免在方法内部声明常量定位器,例如下面的写法是不推荐的:
async waitTitleContains(expectedText: string, timeout: number = TimeoutConstants.TS_COMMON_DASHBOARD_WAIT_TIMEOUT): Promise<void> {
Logger.debug();
const pageTitleLocator: By = By.xpath(`//h1[contains(text(), '${expectedText}')]`);
await this.driverHelper.waitVisibility(pageTitleLocator, timeout);
}
之所以这样规定,是因为把定位器提升为类的静态字段或私有方法后:其一,可以避免每次方法调用都重新构建 By 对象;其二,定位器集中管理便于统一维护;其三,静态字段还能与 @typescript-eslint/member-ordering 规则中 static-field 置顶的成员顺序约定自然吻合。在 pageobjects/openshift/OcpMainPage.ts 的真实实现中,可以同时看到两种合法写法:
@injectable()
export class OcpMainPage {
private static readonly MAIN_PAGE_HEADER_LOCATOR: By = By.id('page-main-header');
private static readonly SELECT_ROLE_BUTTON_LOCATOR: By = By.xpath('//*[@data-test-id="perspective-switcher-toggle"]');
constructor(
@inject(CLASSES.DriverHelper) private readonly driverHelper: DriverHelper) { }
async waitOpenMainPage(): Promise<void> {
Logger.debug();
await this.driverHelper.waitVisibility(OcpMainPage.MAIN_PAGE_HEADER_LOCATOR, TimeoutConstants.TS_SELENIUM_LOAD_PAGE_TIMEOUT);
}
private getProjectDropdownItemLocator(projectName: string): By {
return By.xpath(`//button//*[text()="${projectName}"]`);
}
}
规则 4:完整的 Page Object 示例
CODE_STYLE.md 给出了一个完整的 Page Object 样例(上文即为其核心片段,原文还包含 SELECT_ROLE_BUTTON 定位器、waitOpenMainPage() 等方法)。对照仓库实际文件 pageobjects/openshift/OcpMainPage.ts,可以看到该类的真实面貌:除了示例中的两个定位器,还定义了 ADD_BUTTON、IMPORT_FROM_GIT_ITEM、SELECT_PROJECT_DROPDOWN、SKIP_TOUR_BUTTON、APP_LAUNCHER_BUTTON、DEVSPACES_MENU_ITEM 等静态定位器,以及 getRoleLocator()、getProjectDropdownItemLocator() 等返回 By 的私有动态定位器方法,每个公开方法(waitOpenMainPage、clickOnSelectRoleButton、selectDeveloperRole、openImportFromGitPage 等)都以 Logger.debug() 开头——这正是本规范在真实代码库中的完整落地。
Mocha 测试框架的组织规范
针对测试用例本身,CODE_STYLE.md 明确了 Mocha 的使用纪律:
- 使用 TDD 接口(
suite()/test()),而不是 BDD 的describe()/it()。这从 configs/mocharc.ts 的ui: 'tdd'配置可以得到印证。 - 在
suite()函数内部注入类实例并声明所有测试数据,避免在 suite 不被执行时产生不必要的代码开销:
suite('name', function(): void {
const webCheCodeLocators: Locators = e2eContainer.get(CLASSES.CheCodeLocatorLoader);
// test specific data
const gitImportReference: string = 'pipeline';
- (✗)不要在测试声明中使用箭头函数,因为 Mocha 的动态
this上下文(如this.timeout()、this.currentTest)在箭头函数中不可用。 - 不使用浏览器的 Spec 应在名称结尾加
API,例如EmptyWorkspaceAPI.spec。这一约定在 specs/api 目录中得到充分体现——该目录下AnsibleDevFileAPI.spec.ts、GoDevFileAPI.spec.ts、PythonDevFileAPI.spec.ts等纯 API 测试均以API.spec.ts结尾。 - 不要在
package.json中为每个测试单独创建脚本,而应使用 configs/mocharc.ts 的动态配置,配合mocha --spec或mocha --grep参数运行指定测试。configs/mocharc.ts 中spec字段会根据TEST_ENVIRONMENT、MOCHA_DIRECTORY、MOCHA_USERSTORY环境变量动态解析出不同的测试文件路径,例如dist/specs/${MOCHA_DIRECTORY}/**.spec.js。 - 使用 tests/e2e/constants 下的常量让测试更灵活,例如
MOCHA_CONSTANTS、TIMEOUT_CONSTANTS、BASE_TEST_CONSTANTS等,均通过环境变量提供默认值(如TIMEOUT_CONSTANTS.TS_SELENIUM_LOAD_PAGE_TIMEOUT默认 20_000 毫秒、TS_IDE_START_TIMEOUT默认 310_000 毫秒)。
以真实用例 specs/miscellaneous/RenameWorkspace.spec.ts 为例,它完整展示了上述规范:在 suite() 内通过 e2eContainer.get(CLASSES.XXX) 注入 WorkspaceHandlingTests、ProjectAndFileTests、Dashboard、Workspaces 等实例,使用 suiteSetup('Login', ...) 与多个 test(...) 组织用例,且全部使用 function 而非箭头函数:
suite(`Rename workspace ${BASE_TEST_CONSTANTS.TEST_ENVIRONMENT}`, function (): void {
const workspaceHandlingTests: WorkspaceHandlingTests = e2eContainer.get(CLASSES.WorkspaceHandlingTests);
const loginTests: LoginTests = e2eContainer.get(CLASSES.LoginTests);
const dashboard: Dashboard = e2eContainer.get(CLASSES.Dashboard);
const workspaces: Workspaces = e2eContainer.get(CLASSES.Workspaces);
const workspaceDetails: WorkspaceDetails = e2eContainer.get(CLASSES.WorkspaceDetails);
suiteSetup('Login', async function (): Promise<void> {
await loginTests.loginIntoChe();
});
test(`Create workspace from sample (${stackName})`, async function (): Promise<void> {
await workspaceHandlingTests.createAndOpenWorkspace(stackName);
await workspaceHandlingTests.obtainWorkspaceNameFromStartingPage();
firstWorkspaceName = WorkspaceHandlingTests.getWorkspaceName();
registerRunningWorkspace(firstWorkspaceName);
await projectAndFileTests.waitWorkspaceReadinessForCheCodeEditor();
});
// ...
});
而在 suites/online-ocp/UITest.suite.ts 这类聚合 suite 中,则是通过 import '../../specs/SmokeTest.spec'; 的方式把多个 Spec 文件汇总成一个可批量执行的测试套件(如 SmokeTest、EmptyWorkspace、Quarkus、DevConsoleIntegration、RenameWorkspace 等),配合 configs/mocharc.ts 中的 MOCHA_SUITE/MOCHA_DIRECTORY 变量按环境执行。
包管理(Packages)约定
- 新依赖一律添加为 devDependencies:E2E 测试代码只服务于测试过程,运行期不需要,因此所有工具链(ESLint、Prettier、Mocha、Selenium、Allure 等)都应进入
devDependencies。tests/e2e/package.json 中可以看到eslint、prettier、mocha、selenium-webdriver、chromedriver、allure-mocha、@typescript-eslint/*等全部位于devDependencies,而dependencies仅保留inversify、reflect-metadata、@eclipse-che/api等运行期必需的最小集合。 - 如有依赖变更,在 push 前重新生成
package-lock.json,保证锁文件与package.json严格一致,避免 CI 环境与本地解析出不同版本的依赖树。
注释(Comments)约定
对于被注释掉的代码或 workaround(绕过性处理),必须标记为 //todo 并附上对应 issue 编号,以便日后快速检索定位:
// todo commented due to issue crw-1010
这保证了"临时处理"不会沉没在代码历史中——任何人都能通过搜索 //todo 找到所有遗留问题及其关联的 issue,从而评估是否可以恢复或清理。
从机制到实践的闭环
纵观整套规范,可以总结出 Eclipse Che E2E 测试代码库的工程质量闭环:
- 提交前:Husky pre-commit hook 自动执行 ESLint(含
@typescript-eslint类型检查、member-ordering成员排序、naming-convention命名规范、EPL 版权头校验)与 Prettier 格式化(Tab 缩进、140 列宽、单引号、无尾随逗号),不合格代码无法提交; - 代码组织:Page Object/Util 通过 Inversify
@injectable()+e2eContainer依赖注入统一管理(configs/inversify.config.ts),定位器以静态字段/私有方法两种合法形态集中声明,公开方法以Logger.debug()自动记录调用链(utils/Logger.ts); - 测试组织:Mocha TDD
suite()/test()+ 常量驱动(constants)+ 动态 mocharc 配置,让测试既可整批执行又可精确筛选; - 长期维护:
//todo + issue 编号标记所有临时处理,依赖锁定通过package-lock.json保证可复现。
这套规范并非孤立的"纸面约定",而是与 tests/e2e/.eslintrc.js、tests/e2e/.prettierrc.json、tests/e2e/package.json 及全部 Page Object、Spec、Suite 源码一一对应的工程实践。无论你是为 Che 贡献新的 E2E 测试,还是打算在自己的大型 TypeScript 测试项目中借鉴这套编码体系,都可以直接以上述规则与源码为模板落地。