Eclipse Che / Dev Spaces E2E 测试统一运行命令 `/run-e2e-test` 全流程解析与实战指南
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 容器方式。
解析逻辑如下:
- 将
$ARGUMENTS按空白符拆分为位置参数; - 依次赋给
URL、USERNAME、PASSWORD、TESTNAME、RUN_METHOD; - 若未提供
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),应以当前仓库源码与目标部署环境为准,并可将差异反馈给维护流程加以修订。