Eclipse Che E2E 测试代码规范指南:ESLint/Prettier 自动化检查与 Page Object/Mocha 编码约定

原创2026-10-14 20:12:371,373 阅读
文章标签:开发工具云原生

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 开篇总结了编码标准的六大价值:

  1. 提升代码质量:遵循编码标准可以让代码更安全、高效、可维护且风格统一,从而减少错误、提升整体性能;
  2. 改善可读性与可维护性:格式一致的代码帮助其他开发者快速理解与修改,节省时间并降低引入缺陷的概率;
  3. 加速开发:当开发者遵循既定规则时,可以更快地产出且犯错更少;统一的格式也让问题的定位与解决更加高效;
  4. 更好的可扩展性:一致的编码实践让新增功能或更新变得简单,随着代码库扩张,维护成本得以控制;
  5. 提升协作与沟通:统一规范让开发者更容易理解和接手同事编写的代码,促进团队协作与代码共享;
  6. 跨项目一致性:编码标准的落地保证不同项目间采用一致的编码方式,简化质量把控、任务切换与协作流程。

这六点并非空泛口号——在 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 的使用纪律:

  1. 使用 TDD 接口(suite() / test()),而不是 BDD 的 describe() / it()。这从 configs/mocharc.ts 的 ui: 'tdd' 配置可以得到印证。
  2. 在 suite() 函数内部注入类实例并声明所有测试数据,避免在 suite 不被执行时产生不必要的代码开销:
suite('name', function(): void {
    const webCheCodeLocators: Locators = e2eContainer.get(CLASSES.CheCodeLocatorLoader);
    // test specific data
    const gitImportReference: string = 'pipeline';
  1. (✗)不要在测试声明中使用箭头函数,因为 Mocha 的动态 this 上下文(如 this.timeout()、this.currentTest)在箭头函数中不可用。
  2. 不使用浏览器的 Spec 应在名称结尾加 API,例如 EmptyWorkspaceAPI.spec。这一约定在 specs/api 目录中得到充分体现——该目录下 AnsibleDevFileAPI.spec.ts、GoDevFileAPI.spec.ts、PythonDevFileAPI.spec.ts 等纯 API 测试均以 API.spec.ts 结尾。
  3. 不要在 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。
  4. 使用 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 测试项目中借鉴这套编码体系,都可以直接以上述规则与源码为模板落地。

登录后查看全文
che