Eclipse Che / Dev Spaces E2E 测试统一运行命令 `/run-e2e-test` 全流程解析与实战指南

原创2026-10-14 09:26:471,855 阅读
文章标签:开发工具云原生

Eclipse Che / Dev Spaces E2E 测试统一运行命令 /run-e2e-test 全流程解析与实战指南

本指南围绕仓库中 run-e2e-test.md 这一 Claude 命令定义展开,它是 Eclipse Che / Red Hat OpenShift Dev Spaces E2E 测试的统一入口:只需一个 URL、一组账号与一个测试名,即可在本地 Chrome 浏览器或 Podman 容器两种方式下完成平台自动识别、智能重建判断、环境变量组装与测试执行。读完本文,你将掌握该命令的参数规范、交互式参数收集机制、平台/测试类型的自动适配逻辑,以及本地浏览器与容器两条完整可复制的运行命令,并能结合仓库源码理解其底层执行链(Mocha 配置、环境变量常量、Docker 入口脚本等)。


1. 命令定位:一个入口驱动整套 E2E 测试体系

该命令文件位于 tests/e2e/.claude/commands/run-e2e-test.md,是 Claude Code 生态下的一个斜杠命令(slash command)定义,服务于仓库中 Eclipse Che / Dev Spaces 的 E2E 测试套件。测试套件本体位于 tests/e2e,是一个基于 TypeScript + Mocha(TDD 风格)+ Selenium WebDriver + Inversify(依赖注入)+ Chai(断言)+ Allure(报告) 的完整工程,其结构可参考 e2e-test-developer SKILL。

命令的核心价值在于"统一":

  • 同时支持 Eclipse Che 与 Red Hat OpenShift Dev Spaces 两个产品;
  • 同时支持 本地 Chrome 浏览器(npm 方式,速度快、可实时观察浏览器)与 Podman 容器(隔离环境、自带 VNC、可录制视频)两种运行方式;
  • 自动从 URL 判断被测产品并设置对应平台环境变量;
  • 自动对比 origin/main 检测测试代码变更,仅在必要时重建或全量挂载代码;
  • 根据所选测试类别,自动向用户询问该测试专属的额外环境变量。

命令文件同时以"维护指南"的形式存在:当测试基础设施变化(新增环境变量、执行方式)时,需要同步更新该文件,保持命令与实现一致(见 SKILL.md 的 Maintenance Guidelines 一节)。


2. 参数解析:$ARGUMENTS 的格式与默认值

命令的用法定义为:

/run-e2e-test [URL USERNAME PASSWORD [TESTNAME]]

示例:

  • /run-e2e-test —— 交互模式(推荐),所有参数通过提问收集;
  • /run-e2e-test https://devspaces.apps.cluster.example.com/ admin mypassword SmokeTest npm —— 指定 URL、账号并运行 SmokeTest,使用 npm(本地浏览器)方式;
  • /run-e2e-test https://che.apps.cluster.example.com/ admin mypassword EmptyWorkspace podman —— 指定参数并使用 Podman 容器方式。

解析逻辑如下:

  1. 将 $ARGUMENTS 按空白符拆分为位置参数;
  2. 依次赋给 URL、USERNAME、PASSWORD、TESTNAME、RUN_METHOD;
  3. 若未提供 TESTNAME,默认使用 EmptyWorkspace(与 BASE_TEST_CONSTANTS.ts 中 TS_SELENIUM_HAPPY_PATH_WORKSPACE_NAME 的默认值一致,该常量同时是 Happy Path 场景默认工作区名)。

解析示例:

输入: "https://devspaces.apps.example.com/ admin secret123 SmokeTest npm"
结果:
  - URL       = "https://devspaces.apps.example.com/"
  - USERNAME  = "admin"
  - PASSWORD  = "secret123"
  - TESTNAME  = "SmokeTest"
  - RUN_METHOD = "npm"

值得注意:文档示例的 TESTNAME 不含 .spec.ts 后缀,这正是该测试工程的约定——MOCHA_CONSTANTS.ts 将 USERSTORY 环境变量映射为 MOCHA_USERSTORY,再由 mocharc.ts 将其解析为 dist/specs/**/<USERSTORY>.spec.js 与 dist/specs/<USERSTORY>.spec.js 两类路径的 glob,因此只要给出文件名(无扩展名)即可定位到单个 spec 文件。


3. 交互式参数收集:AskUserQuestion 三问

当 $ARGUMENTS 为空或不完整时,命令使用 AskUserQuestion 收集缺失参数,共三个选择题:

问题 标题 选项 说明
运行方式 Method Option 1: npm run in local browser (Recommended) 使用本地 Chrome 与 Node.js,更快,可实时看到浏览器
Option 2: Podman container 隔离环境,支持 VNC(localhost:5920)
构建模式 Build Option 1: Build and run (Recommended) 与 origin/main 对比,存在变更则重建
Option 2: Just run 跳过构建,假设代码已编译
测试名称 Test Option 1: EmptyWorkspace (Recommended) 基础工作区创建测试
Option 2: SmokeTest 核心功能快速验证
Option 3: Factory Factory URL 创建工作区并执行 Git 操作
Option 4: EmptyWorkspaceAPI 纯 API 测试(无需浏览器)

URL、用户名、密码则以纯文本方式提问,例如:

What is the dashboard URL? (e.g., https://devspaces.apps.cluster.example.com/ or https://che.apps.cluster.example.com/)

以及用户名/密码组合提示。提问后须等待用户响应再继续后续步骤。

这些推荐测试在仓库中均有对应实现:

  • EmptyWorkspace → EmptyWorkspace.spec.ts:登录后创建并打开 "Empty Workspace" 栈、等待 che-code 编辑器就绪、再通过 API 停止并删除工作区;
  • SmokeTest → SmokeTest.spec.ts:从 factory URL 创建并打开工作区,校验项目导入、信任对话框、项目文件,最后停止并删除工作区;
  • EmptyWorkspaceAPI → 无浏览器依赖,通过 npm run driver-less-test 运行(见下文第 7 节)。

4. 平台自动识别:从 URL 推断被测产品

命令会分析 URL 以确定被测产品并设置合理的默认环境变量:

URL 模式 产品 自动配置的环境变量
包含 devspaces Red Hat OpenShift Dev Spaces TS_SELENIUM_VALUE_OPENSHIFT_OAUTH=true、TS_OCP_LOGIN_PAGE_PROVIDER_TITLE=htpasswd、TS_PLATFORM=openshift
包含 eclipse-che Eclipse Che 视部署而定可能需要 OAuth 配置;若 URL 含 crw-qe.com 则 TS_PLATFORM=openshift,否则向用户询问平台(openshift 或 kubernetes)

对应的检测逻辑:

if [[ "$URL" == *"devspaces"* ]]; then
  PRODUCT="devspaces"
  TS_SELENIUM_VALUE_OPENSHIFT_OAUTH=true
  TS_OCP_LOGIN_PAGE_PROVIDER_TITLE="htpasswd"
elif [[ "$URL" == *"eclipse-che"* ]]; then
  PRODUCT="che"
fi

这一"URL 识别产品"的思路在源码中也有对应实现:BASE_TEST_CONSTANTS.ts 的 TESTING_APPLICATION_NAME() 会依据 TS_SELENIUM_BASE_URL 是否包含 devspaces/che 返回 devspaces/che/default,该值随后被用于 ReportPortal 报告的项目名与属性(见 reporters.config.js)。

平台相关配置还有两种形态:

OpenShift:

export TS_PLATFORM=openshift
export TS_SELENIUM_VALUE_OPENSHIFT_OAUTH=true
export TS_OCP_LOGIN_PAGE_PROVIDER_TITLE="htpasswd"

Kubernetes:

export TS_PLATFORM=kubernetes
export TS_SELENIUM_K8S_USERNAME=che@eclipse.org
export TS_SELENIUM_K8S_PASSWORD=admin
export TS_SELENIUM_VALUE_OPENSHIFT_OAUTH=false

底层语义可参考 OAUTH_CONSTANTS.ts:TS_SELENIUM_VALUE_OPENSHIFT_OAUTH 决定登录方式(false 表示以应用用户登录,true 表示以 OCP 普通用户登录);TS_OCP_LOGIN_PAGE_PROVIDER_TITLE 用于匹配 OCP 登录页上的认证提供者标题。TS_PLATFORM 的默认值为 openshift(见 BASE_TEST_CONSTANTS.ts),与 tests/e2e/README.md 中"OpenShift 为默认平台"的说明一致。

另外,initDefaultValues.sh 会在每次 npm run test 前为这些关键变量设置默认值:TS_SELENIUM_VALUE_OPENSHIFT_OAUTH 默认为 false、TS_OCP_LOGIN_PAGE_PROVIDER_TITLE 默认为 htpasswd(若 E2E_OCP_CLUSTER_VERSION=3.x 则将其 unset)、TS_SELENIUM_LOG_LEVEL 默认为 DEBUG、NODE_TLS_REJECT_UNAUTHORIZED 默认为 0、TS_SELENIUM_EDITOR 默认为 che-code。


5. 智能变更检测:对比 origin/main 决定是否重建/挂载

命令在执行前会检查 git 状态,判断测试代码是否需要重新构建(本地浏览器方式)或全量挂载(Podman 方式)。

关键规则:忽略文档与 Claude 配置文件——CLAUDE.md、.claude/**/*、所有 *.md 均不视为代码变更。

5.1 本地浏览器方式:智能重建

逻辑为:将工作区与 origin/main 对比,检测全部变更(含已提交、已暂存、未暂存),若存在测试代码变更则重建;仅变更文档/配置则跳过:

NEEDS_REBUILD=false

# 获取当前分支名(仅用于信息展示)
CURRENT_BRANCH=$(git branch --show-current)
echo "Current branch: $CURRENT_BRANCH"

# 对比 origin/main,排除文档与 Claude 配置
CODE_CHANGES=$(git diff --name-only origin/main -- . 2>/dev/null | grep -v -E '(CLAUDE\.md|\.claude/|README\.md|\.md$)')

if [[ -n "$CODE_CHANGES" ]]; then
  echo "Code changes detected compared to origin/main:"
  echo "$CODE_CHANGES"
  NEEDS_REBUILD=true
else
  echo "No test code changes compared to origin/main - no rebuild needed"
fi

echo "Rebuild needed: $NEEDS_REBUILD"

5.2 Podman 方式:智能挂载

逻辑一致,但决策结果是"挂载策略":

E2E_IMAGE="quay.io/eclipse/che-e2e:next"
MOUNT_FULL_CODE=false

CURRENT_BRANCH=$(git branch --show-current)
echo "Current branch: $CURRENT_BRANCH"

CODE_CHANGES=$(git diff --name-only origin/main -- . 2>/dev/null | grep -v -E '(CLAUDE\.md|\.claude/|README\.md|\.md$)')

if [[ -n "$CODE_CHANGES" ]]; then
  echo "Code changes detected compared to origin/main:"
  echo "$CODE_CHANGES"
  MOUNT_FULL_CODE=true
  PODMAN_MOUNT="-v $(pwd):/tmp/e2e:Z"
else
  echo "No test code changes compared to origin/main - using published image code"
  PODMAN_MOUNT="-v $(pwd)/report:/tmp/e2e/report:Z"
fi

echo "Mount strategy: $PODMAN_MOUNT"

即:有变更时挂载整个 tests/e2e 目录测试本地代码;无变更时只挂载 report 目录,直接使用发布镜像中的代码。这一"复用发布镜像 + 按需挂载"的思路与工程早先提供的 npm 脚本一脉相承——package.json 中的 test-docker(仅传 URL)与 test-docker-mount-e2e(-v $(pwd):/tmp/e2e:Z 全量挂载)分别对应"用镜像代码"与"测试本地改动"两种场景,只是命令文档进一步把挂载与否与 origin/main 差异自动绑定。


6. 测试专属参数:按测试类别补充环境变量

选定测试名后,命令会读取对应 spec 文件,识别其所需的额外环境变量。查找逻辑:

# 查找测试文件
SPEC_FILE=$(find specs -name "${USERSTORY}.spec.ts" 2>/dev/null | head -1)

if [[ -n "$SPEC_FILE" ]]; then
  echo "Found test file: $SPEC_FILE"
  # 读取文件,识别所需环境变量
  cat "$SPEC_FILE"
fi

随后按类别向用户询问额外参数,各类别参数在常量文件中均有明确来源:

Factory URL 测试(Factory、RefusedOAuthFactory、NoSetupRepoFactory 等)

此类测试直接导航到 factory URL 创建工作区,需询问:

  • Git 仓库地址(TS_SELENIUM_FACTORY_GIT_REPO_URL)——要克隆的仓库;
  • Git 提供方(TS_SELENIUM_FACTORY_GIT_PROVIDER)——取值 github、gitlab、bitbucket、azure-devops。源码中 FACTORY_TEST_CONSTANTS.ts 的 GitProviderType 枚举提供了更细的取值:github、gitlab、bitbucket-server-oauth1、bitbucket-server-oauth2、bitbucket-org、azure-devops,默认值为 github;
  • OAuth 开关(TS_SELENIUM_GIT_PROVIDER_OAUTH)——true 或 false。

Git 仓库导入表单测试(FactoryWithGitRepoOptions、CreateWorkspaceWithExistingNameFromGitUrl 等)

此类测试使用 Dashboard 的 "Create Workspace" 表单,需询问:

  • Git 仓库地址(TS_SELENIUM_FACTORY_GIT_REPO_URL);
  • 分支名(TS_SELENIUM_FACTORY_GIT_REPO_BRANCH)——可选。命令文档标注默认 main;但从源码看 FACTORY_TEST_CONSTANTS.ts 的默认值为 'master',实际生效值以部署仓库的分支名为准;
  • 项目名(TS_SELENIUM_PROJECT_NAME)——可选,不设置时测试会从 Git URL 自动推导(见 SmokeTest.spec.ts 中 StringUtil.getProjectNameFromGitUrl 的用法)。

API 测试(EmptyWorkspaceAPI、ContainerOverridesAPI 等)

需询问:

  • 命名空间(TS_API_TEST_NAMESPACE)——可选,OpenShift 平台上的 namespace,见 API_TEST_CONSTANTS.ts;
  • UDI 镜像(TS_API_TEST_UDI_IMAGE)——可选,默认由 DevWorkspaceConfigurationHelper.generateDevfileContext() 通过 @eclipse-che/che-devworkspace-generator 指派 quay.io/devfile/universal-developer-image:latest。

示例/Devfile 测试

需询问:

  • 示例列表(TS_SAMPLE_LIST)——例如 Node.js Express。源码默认值为一组逗号分隔的样本名:Node.js MongoDB,Node.js Express,Java Lombok,Quarkus REST API,Python,.NET,C/C++,Go,PHP,Ansible(见 PLUGIN_TEST_CONSTANTS.ts,该变量被 RecommendedExtensions.spec.ts 以 split(',') 消费)。

SSH/PAT 测试(SshUrlNoOauthPatFactory 等)

需询问:

  • SSH 私钥路径或 Personal Access Token。相关变量包括 TS_SELENIUM_SSH_PRIVATE_KEY_PATH(默认 resources/factory/pr-k.txt)、TS_SELENIUM_SSH_PUBLIC_KEY_PATH(默认 resources/factory/pub-k.txt)、TS_GIT_PERSONAL_ACCESS_TOKEN(git 提供方的 PAT,Bitbucket.org 时为 API token),以及可直接以字符串形式注入的 TS_SELENIUM_SSH_PRIVATE_KEY、TS_SELENIUM_SSH_PUBLIC_KEY、TS_SELENIUM_SSH_KEY_PASSPHRASE(见 FACTORY_TEST_CONSTANTS.ts)。

7. 命令生成与执行:本地浏览器与 Podman 两套命令

7.0 强制规则:禁止打印带续行符的命令

命令文件有一条强制性规则:&& \ 或反斜杠 \ 续行形式的命令无法从终端正确复制粘贴,因此一律以独立多行或单行呈现:

# ✅ 正确(独立多行)
cd /path/to/dir
npm ci
npm run test
# ✅ 正确(podman 单行)
podman run -it --shm-size=2g -p 5920:5920 quay.io/eclipse/che-e2e:next
# ❌ 错误(行续接)
cd /path/to/dir && \
npm ci && \
npm run test
# ❌ 错误(反斜杠续行)
podman run -it \
  --shm-size=2g \
  -p 5920:5920 \
  quay.io/eclipse/che-e2e:next

7.1 Option A:本地浏览器方式

先做 Chrome / ChromeDriver 兼容性检查:

# 获取本地 Chrome 版本
CHROME_VERSION=$(google-chrome --version 2>/dev/null | grep -oP '\d+' | head -1)
echo "Local Chrome major version: $CHROME_VERSION"

# 获取 package.json 中的 ChromeDriver 版本
CHROMEDRIVER_VERSION=$(npm list chromedriver --depth=0 2>/dev/null | grep -oP 'chromedriver@\K[\d.]+')
echo "ChromeDriver version in package.json: $CHROMEDRIVER_VERSION"

# 版本不匹配时提示安装对应版本
if [[ "${CHROMEDRIVER_VERSION%%.*}" != "$CHROME_VERSION" ]]; then
  echo "WARNING: ChromeDriver version mismatch!"
  echo "Install compatible version: npm install chromedriver@$CHROME_VERSION"
fi

若不兼容,安装匹配版本:

npm install chromedriver@<chrome-major-version>

仓库当前 package.json 声明的是 chromedriver: ^125.0.0,实际以本机 Chrome 主版本号为准。

完整测试运行(构建 + 运行):

cd tests/e2e

# 使用正确的 Node.js 版本
nvm use v22.10.0

# 获取当前分支名(信息展示)
CURRENT_BRANCH=$(git branch --show-current)
echo "Current branch: $CURRENT_BRANCH"

# 对比 origin/main 检测代码变更(排除文档与 Claude 配置)
CODE_CHANGES=$(git diff --name-only origin/main -- . 2>/dev/null | grep -v -E '(CLAUDE\.md|\.claude/|README\.md|\.md$)')

if [[ -n "$CODE_CHANGES" ]]; then
  echo "Code changes detected compared to origin/main:"
  echo "$CODE_CHANGES"
  NEEDS_REBUILD=true
else
  echo "No test code changes compared to origin/main - skipping rebuild"
  NEEDS_REBUILD=false
fi

# 检查 package.json 是否相对 origin/main 被修改
PACKAGE_JSON_CHANGED=$(git diff --name-only origin/main -- package.json 2>/dev/null)

# 检测到变更时重建
if [[ "$NEEDS_REBUILD" == "true" ]]; then
  echo "Rebuilding TypeScript..."
  rm -rf node_modules dist

  # package.json 变更则用 npm install 更新锁文件,否则用 npm ci
  if [[ -n "$PACKAGE_JSON_CHANGED" ]]; then
    echo "package.json modified - using npm install to update package-lock.json"
    npm install
  else
    npm ci
  fi

  npm run lint
  npm run prettier
  npm run tsc
fi

# 设置环境变量
export TS_SELENIUM_BASE_URL="<URL>"
export TS_SELENIUM_OCP_USERNAME="<USERNAME>"
export TS_SELENIUM_OCP_PASSWORD="<PASSWORD>"
export USERSTORY="<TESTNAME>"
export TS_SELENIUM_VALUE_OPENSHIFT_OAUTH=true
export NODE_TLS_REJECT_UNAUTHORIZED=0

# 运行测试
npm run test

其中 npm run test 的底层链路可从 package.json 拆解:

./configs/sh-scripts/initDefaultValues.sh npm run lint && npm run tsc && export USERSTORY=$USERSTORY && mocha --config dist/configs/mocharc.js

即:初始化默认环境变量 → ESLint 修复 → 生成索引并编译 TypeScript(generateIndex.sh + tsc -p .,产物进入 dist/)→ 导出 USERSTORY → 以 mocharc.ts 为配置启动 Mocha。该配置使用 TDD 风格的 suite()/test()、默认超时 MOCHA_DEFAULT_TIMEOUT = 840000 ms、mocha-multi-reporters 报告器,并按 MOCHA_USERSTORY 精确匹配单个 spec 文件(详见 MOCHA_CONSTANTS.ts)。

纯 API 测试(无需浏览器):

export USERSTORY=EmptyWorkspaceAPI
npm run driver-less-test

driver-less-test 的本质是 export TS_USE_WEB_DRIVER_FOR_TEST=false && npm run test(见 package.json),跳过 Selenium WebDriver 启动,适用于 specs/api 目录下的 API 测试。

7.2 Option B:Podman 容器方式

重要:使用 --env-host 将宿主机上已导出的全部环境变量传入容器。

有代码变更(挂载全目录)——适用于相对于 origin/main 有测试代码变更的分支或本地 main 存在未推送变更的场景:

cd tests/e2e

# 设置环境变量
export NODE_TLS_REJECT_UNAUTHORIZED=0
export TS_SELENIUM_BASE_URL=<URL>
export TS_SELENIUM_OCP_USERNAME=<USERNAME>
export TS_SELENIUM_OCP_PASSWORD=<PASSWORD>
export USERSTORY=<TESTNAME>

# 以本地代码运行(测试相对 origin/main 的变更)
podman rm -f selenium-e2e 2>/dev/null
podman run -it --shm-size=2g -p 5920:5920 --env-host -v $(pwd):/tmp/e2e:Z quay.io/eclipse/che-e2e:next

无代码变更(只挂载报告目录)——使用发布镜像内的代码:

cd tests/e2e

# 设置环境变量
export NODE_TLS_REJECT_UNAUTHORIZED=0
export TS_SELENIUM_BASE_URL=<URL>
export TS_SELENIUM_OCP_USERNAME=<USERNAME>
export TS_SELENIUM_OCP_PASSWORD=<PASSWORD>
export USERSTORY=<TESTNAME>

# 仅挂载报告目录(无变更,使用发布镜像代码)
podman rm -f selenium-e2e 2>/dev/null
podman run -it --shm-size=2g -p 5920:5920 --env-host -v $(pwd)/report:/tmp/e2e/report:Z quay.io/eclipse/che-e2e:next

参数说明:

  • --shm-size=2g:扩大 /dev/shm,避免 Chrome 在容器内因共享内存不足而崩溃;
  • -p 5920:5920:暴露容器内 VNC 服务端口,用于可视化调试;
  • --env-host:继承宿主机环境变量(含上面 export 的全部 TS_* 变量);
  • -v ...:Z:SELinux 环境下自动修正挂载目录标签;
  • 容器名统一为 selenium-e2e,便于 podman rm -f selenium-e2e 清理。

quay.io/eclipse/che-e2e:next 镜像内含完整的测试环境(Node、Chrome、ChromeDriver、测试代码),其入口脚本见 build/dockerfiles/entrypoint.sh,其中 SCREEN_RECORDING 默认读取 VIDEO_RECORDING 环境变量(默认 true),即在容器内运行测试时会用 ffmpeg 录制屏幕并产出 mp4 录像,可通过 VIDEO_RECORDING=false 关闭(详见 build/dockerfiles/README.md)。

7.3 执行前确认

生成命令后,命令会向用户展示将要执行的命令并请求确认,确认摘要包含:

  • Platform: OpenShift / Kubernetes
  • Product: Eclipse Che / Dev Spaces
  • Test: 测试名
  • Method: Local browser / Podman container
  • URL: 目标地址

确认后:执行命令 → 监控输出 → 汇报成功/失败;若使用 Podman,提醒用户可通过 localhost:5920 的 VNC 观察测试。


8. 调试选项:日志、无头模式、录屏与工作区保留

命令文件提供了四组调试环境变量:

# 详细日志
export TS_SELENIUM_LOG_LEVEL=TRACE
export TS_SELENIUM_PRINT_TIMEOUT_VARIABLES=true
export TS_DEBUG_MODE=true
# 无头模式(CI 环境)
export TS_SELENIUM_HEADLESS=true
# 视频录制
export VIDEO_RECORDING=true
# 测试失败时保留工作区(便于排查)
export TS_DELETE_WORKSPACE_ON_FAILED_TEST=false

这些变量在源码中均有对应实现:

  • TS_SELENIUM_LOG_LEVEL:日志级别,取值 INFO(默认)、DEBUG、TRACE(见 REPORTER_CONSTANTS.ts);
  • TS_SELENIUM_PRINT_TIMEOUT_VARIABLES:启动时打印全部超时变量(同文件 L69),与 tests/e2e/README.md 中"设置该变量为 true 可查看超时变量清单"的说明一致;
  • TS_DEBUG_MODE:延长本地调试超时(见 BASE_TEST_CONSTANTS.ts);
  • TS_SELENIUM_HEADLESS:无头模式开关,由 ChromeDriver.ts 读取并作用于 Chrome 启动参数,CI 脚本 runFunctionalTests.sh 默认设为 'false';
  • VIDEO_RECORDING:容器入口脚本中的录屏开关(见上文 7.2);
  • 工作区保留:注意命令文档写作 TS_DELETE_WORKSPACE_ON_FAILED_TEST,而源码 BASE_TEST_CONSTANTS.ts 中实际读取的变量名是 DELETE_WORKSPACE_ON_FAILED_TEST(=== 'true' 时失败后停止并删除工作区),使用时可两者对照确认;成功删除开关为 DELETE_WORKSPACE_ON_SUCCESSFUL_TEST(默认 true)。

9. VNC 可视化调试(Podman 方式)

容器内测试运行时可连接 localhost:5920 的 VNC 服务实时观察浏览器操作。命令文档推荐以下客户端:

  • TigerVNC(推荐):sudo dnf install tigervnc,然后 vncviewer localhost:5920
  • Remmina:sudo dnf install remmina remmina-plugins-vnc(GUI 界面)
  • Vinagre:sudo dnf install vinagre,然后 vinagre localhost:5920

这一能力在 tests/e2e/README.md 的 "Debug docker launch" 一节也有印证:quay.io/eclipse/che-e2e 镜像内已安装 VNC 服务器,地址为 0.0.0.0:5920。


10. 查看测试报告

测试执行完成后,可生成本地 Allure 报告:

npm run open-allure-dasboard

该脚本实际执行 allure generate .allure-results --clean -o .allure-report && allure open .allure-report(见 package.json)。报告数据的来源是 reporters.config.js 中配置的 mocha-multi-reporters:

  • CheReporter(dist/utils/CheReporter.js)——始终启用,负责日志、失败截图/录屏等(见 REPORTER_CONSTANTS.ts);
  • allure-mocha——写入 .allure-results,需设置 SAVE_ALLURE_REPORT_DATA=true;
  • mocha-junit-reporter——输出 report/junit/test-results.xml,需设置 SAVE_JUNIT_DATA=true;
  • @reportportal/agent-js-mocha——上报 ReportPortal,需设置 SAVE_RP_REPORT_DATA=true 及 RP_API_KEY、RP_ENDPOINT 等。

11. 常见问题排查

命令文件收录了四类高频问题及其对策:

证书错误:

export NODE_TLS_REJECT_UNAUTHORIZED=0

(该值也是 initDefaultValues.sh 的默认值,自签名证书环境开箱即用。)

工作区启动缓慢:

export TS_SELENIUM_START_WORKSPACE_TIMEOUT=600000
export TS_SELENIUM_DEFAULT_ATTEMPTS=3

源码默认值:工作区启动超时 360000 ms(TIMEOUT_CONSTANTS.ts),默认尝试次数 5 次、轮询间隔 1000 ms(同文件 L35-L40)。

OAuth 登录问题: 确认登录提供者标题与登录页显示完全一致:

export TS_OCP_LOGIN_PAGE_PROVIDER_TITLE="htpasswd"

容器清理:

podman rm -f selenium-e2e

12. 在 VS Code 中调试 TypeScript 测试

如需在断点模式下调试 E2E 测试,可参考 VS Code 官方 TypeScript 调试文档(https://code.visualstudio.com/docs/typescript/typescript-debugging)配置 launch.json。结合本工程,一个实用的组合是:先 npm run tsc 编译出 dist/ 产物,再以 Mocha 调试配置(--config dist/configs/mocharc.js)附加调试器,配合 TS_DEBUG_MODE=true 延长超时,即可逐步跟踪 pageobjects 与 tests-library 中的调用链。注意 settings.local.json 中为 Claude 会话预先放行了 npm run lint、npm run prettier、npm run tsc、nvm use:*、export:* 等命令,说明这些是 E2E 开发调试的高频操作。


13. 底层机制总览:命令如何与测试工程衔接

将命令文档与源码对照,可以勾勒出完整的执行链:

/run-e2e-test
  ├─ 参数解析 + 交互收集 ──────────────────── URL / 账号 / TESTNAME / RUN_METHOD
  ├─ 平台识别(URL 含 devspaces / eclipse-che)─ TS_PLATFORM / OAuth 相关变量
  ├─ 变更检测(git diff vs origin/main)───── NEEDS_REBUILD / PODMAN_MOUNT
  ├─ 测试专属参数(按 spec 类别询问)───────── FACTORY / API / SAMPLE / SSH 常量
  ├─ 生成命令
  │    ├─ npm 方式:nvm use → 条件重建 → export TS_* → npm run test
  │    │      └─ initDefaultValues.sh → lint → tsc(generateIndex+编译) → mocha --config dist/configs/mocharc.js
  │    │           └─ USERSTORY → MOCHA_USERSTORY → 定位 dist/specs/**/<名>.spec.js
  │    └─ podman 方式:export TS_* → podman run --env-host (-v 全量或仅 report) quay.io/eclipse/che-e2e:next
  │                 └─ 容器 entrypoint:启动测试 + VNC(5920) + ffmpeg 录屏(VIDEO_RECORDING)
  └─ 确认后执行 → 监控 → Allure 报告(npm run open-allure-dasboard)

贯穿全程的环境变量常量层(constants 目录)是这套体系的"字典":BASE_TEST_CONSTANTS(平台、URL、产品名)、OAUTH_CONSTANTS(登录方式)、FACTORY_TEST_CONSTANTS(Git 仓库/分支/PAT/SSH)、API_TEST_CONSTANTS(namespace、UDI 镜像、命令行工具)、PLUGIN_TEST_CONSTANTS(示例列表)、TIMEOUT_CONSTANTS(各类超时与重试)、MOCHA_CONSTANTS(用例选择与执行参数)。命令文档所做的,正是把这些散落的变量按用户意图自动组合成一条可执行命令——这也是它被称为"Unified Command"的原因。


14. 维护提示

命令文件本身是测试基础设施的一部分:e2e-test-developer SKILL 明确要求:当测试基础设施变化(新增环境变量、测试模式或执行方式)时,应同步更新 .claude/commands/run-e2e-test.md;新增或修改需要新环境变量的测试时,应更新命令文件中的 "Test-Specific Parameters" 一节;同时确保文档中的命令示例与当前实现模式一致。这意味着阅读本文时若发现变量默认值有出入(例如文档标注分支默认 main 而源码默认为 master、文档写作 TS_DELETE_WORKSPACE_ON_FAILED_TEST 而源码读取 DELETE_WORKSPACE_ON_FAILED_TEST),应以当前仓库源码与目标部署环境为准,并可将差异反馈给维护流程加以修订。

登录后查看全文
che