Eclipse Che DevWorkspace Happy Path:基于 Kubernetes Pod 的冒烟测试全流程指南
Eclipse Che DevWorkspace Happy Path:基于 Kubernetes Pod 的冒烟测试全流程指南
导读
本文围绕 Eclipse Che 仓库中 tests/devworkspace-happy-path/ 目录展开,讲解如何在已部署好 Che(启用 DevWorkspace 引擎)的集群上,通过一个名为 happy-path-che 的 Pod 自动完成 DevWorkspace 冒烟测试(Happy Path Test)的完整方案。读完本文,你将掌握本地一键触发(launch.sh)、远程 PR 检查式触发(remote-launch.sh)、OpenShift OAuth 测试用户自动供给、测试 Pod 的资源与环境变量配置,以及测试日志、报告收集与结果判定的全部细节,能够将其直接复用到你自己的集群验证流程中。
一、什么是 Che DevWorkspace Happy Path
在 Eclipse Che 的项目结构中,tests/devworkspace-happy-path/ 是一个相对独立、轻量的冒烟测试模块。与仓库内庞大的 Selenium/Mocha 端到端测试框架(tests/e2e)不同,Happy Path 的思路是:把整个 e2e 测试框架封装进一个容器镜像,然后以 Kubernetes Pod 的形式调度到目标集群上运行,测试对象就是"同一个集群上已经部署好的、启用了 DevWorkspace 引擎的 Che"。
这种"测试即 Pod"的模式带来几个明显的工程收益:
- 无需本地浏览器与 Node 环境:测试运行在集群内,天然接近真实生产拓扑;
- 可复现、可清理:Pod 使用
restartPolicy: Never,测试结束即终止,配合日志收集脚本可沉淀完整产物; - 适合作为 PR 检查:只要集群上有已部署的 Che,就可以远程拉取脚本、注入环境变量,在任意集群上触发同一套冒烟流程。
目录下共包含 5 个脚本和 3 个资源文件,各自职责如下:
| 文件 | 职责 |
|---|---|
| launch.sh | 本地入口,串起后续所有步骤并计时 |
| common.sh | 初始化产物目录、定义日志收集函数 |
| provision-openshift-oauth-user.sh | 在 OpenShift 上自动配置 htpasswd OAuth 测试用户 |
| start-happypath-tests.sh | 核心:渲染测试 Pod 配置、启动 Pod、跟踪日志、判定结果 |
| remote-launch.sh | 远程场景入口,先拉取仓库代码再调用 launch.sh |
| resources/pod-che-happy-path.yaml | 测试 Pod 模板(含两个容器与全部环境变量) |
| resources/cluster-oauth-patch.json | OAuth cluster 的 merge patch 片段 |
| resources/users.htpasswd | 测试用户的 htpasswd 凭据文件 |
二、运行前置条件
Happy Path 测试对目标集群有明确的硬性要求:
- 集群上已经部署好 Che,并且启用了 DevWorkspace 引擎(DevWorkspace Operator)。这是整个测试的前提,因为测试的核心动作就是通过 Che 的 URL 打开一个 DevWorkspace;
- 具备
oc(OpenShift CLI)命令行工具,且当前 kubeconfig 拥有足够的权限:脚本需要创建 namespace、创建/删除 Pod、读取 Route、读写 OAuth 集群配置、收集多 namespace 的日志; - 集群可访问
quay.io,因为测试 Pod 使用的镜像quay.io/eclipse/che-e2e:next(imagePullPolicy: Always)需要从公共仓库拉取; - 若走远程触发方式,还需要能访问仓库源码归档(详见第四节)。
三、本地运行:一条命令触发全部流程
按照 README.md 的说明,只要当前集群上已有启用了 DevWorkspace 的 Che,在 tests/devworkspace-happy-path/ 目录下执行:
./launch.sh
这一条命令背后实际发生了非常多的动作。我们先看 launch.sh 的组织方式:它开启了三个严格的 Shell 防护选项——set -e(任一命令失败立即退出)、set -o pipefail(管道中任一环节失败即视为失败)、set -u(未定义变量视为错误),保证冒烟测试不会在静默出错的情况下继续污染结果。
随后它做了四件事:
- 记录起始时间
START=$(date +%s.%N),并导出两个全局环境变量:CHE_NAMESPACE(默认eclipse-che):Che 与测试 Pod 所在的 namespace;HAPPY_PATH_POD_NAME=happy-path-che:测试 Pod 的固定名称;
source common.sh,准备好产物目录与日志收集函数;- 注册
trap 'collectLogs $?' EXIT SIGINT:无论测试成功、失败还是被中断,都会在退出前自动执行日志收集,避免现场丢失; - 依次
source两个脚本:先provision-openshift-oauth-user.sh(供给测试用户),再start-happypath-tests.sh(启动测试),最后用bc打印总耗时。
由于 launch.sh 中 HAPPY_PATH_POD_NAME 是写死的,同一时间一个集群上只能有一个 Happy Path 测试实例在跑,这也是脚本开头会先删除旧 Pod 的原因之一。
四、远程运行:作为 PR 检查触发
当需要把 Happy Path 作为 PR 检查(例如 CI 中对某个分支的验证)时,README 给出了远程触发方式:预先在集群上部署好启用了 DevWorkspace 的 Che,然后远程获取 remote-launch.sh 并直接执行:
curl -s <raw 形式的 remote-launch.sh 地址> | bash -s
之所以能"一条 curl 走天下",是因为 remote-launch.sh 本身就是自包含的引导器,其内部逻辑为:
- 解析两个可覆盖的环境变量:
CHE_REPO_BRANCH(默认main):指定拉取哪个分支的代码;CHE_REPO_ARCHIVE(默认指向eclipse/che仓库该分支的 zip 归档):指定源码包下载地址;
- 准备代码目录:若设置了自定义的
CODE_BASE_DIR则清空复用,否则使用默认目录/tmp/che-devworkspace-happy-path; - 下载并解压源码:
curl -f -L -sS拉取 zip 到本地,unzip解压,然后cd进入解压出的目录; - 调用本地入口:
./tests/devworkspace-happy-path/launch.sh,从而进入与第三节完全相同的本地流程。
因此远程触发的本质是"远程取码 + 本地执行"两层结构:remote-launch.sh 只负责把仓库代码搬到执行机上,真正的测试逻辑全部收敛在 launch.sh 中。若执行机上已有仓库代码,也可以直接调用 bash tests/devworkspace-happy-path/remote-launch.sh 达到同样效果。
五、核心环境变量速查
整个流程的行为几乎完全由环境变量驱动,默认值分散定义在 start-happypath-tests.sh 与 launch.sh 中,归纳如下:
| 变量 | 默认值 | 作用 |
|---|---|---|
CHE_NAMESPACE |
eclipse-che |
Che 与测试 Pod 所在 namespace |
E2E_TEST_IMAGE |
quay.io/eclipse/che-e2e:next |
承载测试框架的容器镜像 |
HAPPY_PATH_POD_NAME |
happy-path-che |
测试 Pod 名称(固定值) |
HAPPY_PATH_TEST_PROJECT |
che-samples 下的 java-spring-petclinic(devfilev2 分支) |
测试打开的示例项目,用于构造 DevWorkspace URL |
HAPPY_PATH_SUITE |
test-all-devfiles |
传给测试镜像的测试套件名 |
HAPPY_PATH_USERSTORY |
EmptyWorkspace |
传给测试镜像的具体用例名 |
WORKDIR |
脚本所在目录下的 workdir/e2e |
渲染后 Pod 配置等临时文件目录 |
ARTIFACT_DIR(在 common.sh 中定义) |
/tmp/devworkspace-happy-path-artifacts |
日志与测试报告的最终落盘目录 |
其中 HAPPY_PATH_SUITE=test-all-devfiles 与 HAPPY_PATH_USERSTORY=EmptyWorkspace 的组合直接对应 tests/e2e/package.json 中的 test-all-devfiles 脚本,以及 tests/e2e/configs/sh-scripts/initDevfileTests.sh 里 MOCHA_DIRECTORY 的选择逻辑——也就是说,Pod 内运行的正是仓库 tests/e2e 这套 Mocha 测试框架的 EmptyWorkspace 用例。
六、测试 Pod 的组装过程
start-happypath-tests.sh 的核心工作是"渲染并提交测试 Pod",整个过程清晰可复现:
- 清理现场:删除
WORKDIR重建;oc create namespace ${CHE_NAMESPACE} || true(已存在则忽略报错);删除可能残留的旧happy-path-chePod(30 秒优雅退出期); - 解析 Che 地址:从 OpenShift Route 上动态读取 Che 的域名,构造
ECLIPSE_CHE_URL与测试入口TS_SELENIUM_DEVWORKSPACE_URL:ECLIPSE_CHE_URL=${ECLIPSE_CHE_URL:-http://$(oc get route -n "${CHE_NAMESPACE}" che -o jsonpath='{.status.ingress[0].host}')} TS_SELENIUM_DEVWORKSPACE_URL="${ECLIPSE_CHE_URL}/#${HAPPY_PATH_TEST_PROJECT}" - 渲染 Pod 模板:把 resources/pod-che-happy-path.yaml 复制到
WORKDIR/e2e-pod.yaml,用sed依次替换占位符HAPPY_PATH_SUITE、HAPPY_PATH_USERSTORY、CHE_URL、WORKSPACE_ROUTE、CHE-NAMESPACE,以及容器image:字段为实际的E2E_TEST_IMAGE,然后打印完整配置便于排查; - 提交并等待就绪:
oc apply -f创建 Pod,随后进入最长 120 轮 × 5 秒(共 10 分钟)的轮询,直到 Pod 状态变为Running;超时则报错退出。
值得注意的细节:oc get route ... -o jsonpath 读取的是 Route 的 status.ingress[0].host,这意味着该方式面向 OpenShift 集群;而 ECLIPSE_CHE_URL 支持外部覆盖,方便在特殊网络环境下手工指定 Che 入口。
七、测试 Pod 内部结构解析
resources/pod-che-happy-path.yaml 是整条冒烟链路的"最后一公里",它定义了一个包含两个容器、共享两个卷的 Pod:
容器一:happy-path-test(测试主体)
使用 quay.io/eclipse/che-e2e:next,imagePullPolicy: Always,通过环境变量把测试参数注入框架:
| 环境变量 | 值 | 含义 |
|---|---|---|
TEST_SUITE |
渲染自 HAPPY_PATH_SUITE |
Mocha 测试套件 |
USERSTORY |
渲染自 HAPPY_PATH_USERSTORY |
具体用例(默认 EmptyWorkspace) |
TS_SELENIUM_BASE_URL |
渲染自 CHE_URL |
Che Dashboard 地址 |
TS_SELENIUM_DEVWORKSPACE_URL |
渲染自 WORKSPACE_ROUTE |
要打开的 DevWorkspace 地址 |
TS_SELENIUM_MULTIUSER |
true |
多用户模式 |
TS_SELENIUM_LOG_LEVEL |
TRACE |
测试框架日志级别 |
TS_SELENIUM_OCP_USERNAME / TS_SELENIUM_OCP_PASSWORD |
happypath-dev / dev |
OpenShift 登录凭据(由 provisioning 脚本保证可用) |
TS_SELENIUM_VALUE_OPENSHIFT_OAUTH |
true |
走 OpenShift OAuth 登录 |
TS_SELENIUM_USERNAME / TS_SELENIUM_PASSWORD |
admin / admin |
多用户模式下的平台账号 |
TS_OCP_LOGIN_PAGE_PROVIDER_TITLE |
dev-htpasswd |
OAuth 登录页选择的 Identity Provider 名称 |
DELETE_WORKSPACE_ON_FAILED_TEST |
true |
测试失败时自动清理工作区 |
TS_SELENIUM_START_WORKSPACE_TIMEOUT |
540000(9 分钟) |
等待工作区启动的超时 |
TS_IDE_LOAD_TIMEOUT |
40000(40 秒) |
等待 IDE 加载的超时 |
NODE_TLS_REJECT_UNAUTHORIZED |
0 |
关闭 Node 对自签名证书的校验(配合内部集群 CA) |
这些变量与 tests/e2e/constants/BASE_TEST_CONSTANTS.ts、tests/e2e/configs/mocharc.ts 中解析的环境变量一一对应——例如 mocharc.ts 正是根据 MOCHA_DIRECTORY 与 USERSTORY 决定加载 dist/specs/**/EmptyWorkspace.spec.js 还是整个目录的用例。
容器二:download-reports(结果搬运)
使用 eeacms/rsync 镜像,与测试容器共享 test-run-results 卷,挂载到 /tmp/e2e/report/。它以一段 while 循环驻留:轮询 /tmp/done 标记文件,一旦被测试方创建(通过 oc exec ... touch /tmp/done),即退出并释放 Pod。
共享卷与资源配额
test-run-results:空卷,测试报告写入点;dshm:emptyDir且medium: Memory,挂载到测试容器的/dev/shm,为 Chrome 浏览器提供共享内存(Selenium 场景的常见要求);- 资源请求
3Gi内存 /2CPU,上限4Gi内存 /2CPU; restartPolicy: Never:测试失败也不重启,保留现场供日志收集。
八、OpenShift OAuth 测试用户的自动供给
Happy Path 测试需要以真实用户身份登录 Che,因此 provision-openshift-oauth-user.sh 负责在 OpenShift 上"从零造出一个可登录的用户"。其策略非常务实,分四步走:
- 先探测:用
oc login -u che-user -p user尝试登录,若集群上已有该用户则直接复用,跳过全部配置; - 创建凭据 Secret:将 resources/users.htpasswd(内含
happypath-dev用户的 bcrypt 哈希)灌入openshift-confignamespace 下的dev-htpasswd-secret; - 按需配置 OAuth 集群:根据集群当前 OAuth 状态选择不同路径:
oauth/cluster不存在 →oc apply完整创建(脚本引用的cluster-oauth.yaml资源在当前仓库快照中未收录,实际效果以部署侧为准);- 存在但
spec.identityProviders为空 → 使用 resources/cluster-oauth-patch.json 做 merge patch 整体覆盖; - 已有其他 IDP 但没有
dev-htpasswd→ 使用 JSON patch 在/spec/identityProviders/0处插入新条目(name: dev-htpasswd、type: HTPasswd、mappingMethod: add),避免覆盖既有配置; - 已存在
dev-htpasswd→ 直接使用。
- 等待生效并验证:对
openshift-authenticationnamespace 的oauth-openshiftDeployment 执行oc rollout status(对应 eclipse/che#20822 这类 IDP 生效延迟问题),随后最多等待 5 分钟,循环用happypath-dev/dev尝试登录,成功即返回,超时则报错退出。
这套逻辑保证了测试用户供给对"干净集群"与"已有身份体系的集群"都具备幂等性,且不会破坏集群原有 IDP 配置。
九、日志收集与产物沉淀
冒烟测试的价值一半在结果、一半在现场。common.sh 在脚本最早阶段就完成了产物目录初始化:
export ARTIFACT_DIR=${ARTIFACT_DIR:-"/tmp/devworkspace-happy-path-artifacts"}
rm -rf "${ARTIFACT_DIR}" && mkdir -p "${ARTIFACT_DIR}"
随后定义的 collectLogs 函数(被 launch.sh 的 trap 挂接)在测试结束、成功、中断三种情况下都会执行,收集范围覆盖三块:
- 三个关键 namespace 的 Pod 日志与事件,通过
bumpPodsInfo实现:devworkspace-controller:DevWorkspace Operator 控制器;eclipse-che:Che 服务端;che-user-che:测试用户实际创建工作区(DevWorkspace)的 namespace;bumpPodsInfo遍历每个 namespace 下所有 Pod、每个 Pod 的所有容器,把oc logs与oc get events -o=yaml分别落盘为<pod>-<container>.log与events.log;
- DevWorkspace 相关 CRD 的完整快照:
oc get devworkspace / devworkspacetemplate / devworkspacerouting -o=yaml导出到产物目录,且用|| true容忍 CRD 尚未安装的情况; - Che 服务端日志:若执行环境装有
chectl,则调用chectl server:logs --directory=... --telemetry=off抓取服务端日志(|| true保证 chectl 缺失时不中断流程)。
十、结果跟踪与判定
start-happypath-tests.sh 的收尾逻辑同样值得单独拆解:
- 实时跟踪日志:
oc logs -n ${CHE_NAMESPACE} happy-path-che -c happy-path-test -f阻塞跟随测试容器日志,直到测试进程退出; - 下载测试报告:等待 3 秒后创建
${ARTIFACT_DIR}/e2e目录,用oc rsync把测试容器/tmp/e2e/report/的内容同步到本地,再通过oc exec在download-reports容器内touch /tmp/done解除驻留循环、让 Pod 正常退出; - 判定成败:从测试容器日志中抓取
EXIT_CODE行,只有精确匹配+ EXIT_CODE=0才判定成功;否则输出错误提示(指明报告位置或eclipse-chenamespace 中的 Pod 现场)并以非零码退出。
也就是说,Pod 的 Running 只是"测试启动成功",真正的成败以容器内打印的 EXIT_CODE 为准,这也与 restartPolicy: Never 的设计相互配合——失败时 Pod 保持终止态,方便事后 oc logs / oc describe 复查。
十一、与 e2e 测试框架的深层关联
虽然 Happy Path 以 Pod 形式运行,但它驱动的内容正是仓库 tests/e2e 的既有测试体系。从源码可以确认这条调用链:
HAPPY_PATH_SUITE=test-all-devfiles对应 tests/e2e/package.json 的test-all-devfiles脚本(先initDefaultValues.sh再initDevfileTests.sh);- tests/e2e/configs/sh-scripts/initDevfileTests.sh 会导出
MOCHA_DIRECTORY(默认dashboard-samples),进而由 tests/e2e/configs/mocharc.ts 决定 Mocha 加载dist/specs/${MOCHA_DIRECTORY}/EmptyWorkspace.spec.js; - 而
EmptyWorkspace用例(见 tests/e2e/specs/dashboard-samples/EmptyWorkspace.spec.ts)走的正是"创建/启动工作区 → 验证 IDE"的冒烟路径;与之并行的还有 tests/e2e/specs/api/DevfileAcceptanceTestAPI.spec.ts 这类动态生成用例(通过 DynamicallyGeneratingAPITest.suite.ts 引入),用于批量验证各类 devfile 的构建与运行。
因此,Happy Path 可以理解为一层"集群内调度壳":把本就存在的 e2e 框架装进镜像、以 Pod 调度、把结果搬回本地。理解这层关系后,若要扩展 Happy Path 的覆盖面,改动点主要在 resources/pod-che-happy-path.yaml 的环境变量与 HAPPY_PATH_SUITE / HAPPY_PATH_USERSTORY 的组合上,而不需要改动测试框架本身。
十二、常见故障排查要点
结合脚本中的防护逻辑,可总结出几条实用的排查路径:
- Pod 一直无法进入
Running:检查E2E_TEST_IMAGE是否可拉取、CHE_NAMESPACE是否正确、Che 是否真的部署在目标 namespace(脚本会打印渲染后的e2e-pod.yaml,先用oc describe pod happy-path-che看事件); - OAuth 供给超时(5 分钟):确认
oauth-openshiftDeployment 是否完成 rollout,IDP 的生效存在延迟(脚本注释中引用了 eclipse/che#20822 相关案例),必要时手动oc rollout restart deployment/oauth-openshift -n openshift-authentication; - 测试失败但找不到原因:
ARTIFACT_DIR(默认/tmp/devworkspace-happy-path-artifacts)下已自动沉淀devworkspaces.yaml、devworkspace-templates.yaml、devworkspace-routings.yaml以及三个 namespace 的容器日志与事件,优先从这些产物入手; EXIT_CODE判定失败:注意脚本只接受精确的+ EXIT_CODE=0,若容器日志中该行被日志前缀污染或测试进程被信号终止,都会导致误判为失败,此时应结合完整日志确认真实退出原因。
结语
Che DevWorkspace Happy Path 是一套设计克制、工程细节完整的集群内冒烟测试方案:本地一条 ./launch.sh,远程一条 curl 管道,即可在任意已部署 Che 的 OpenShift 集群上完成"供给 OAuth 用户 → 调度测试 Pod → 打开示例 DevWorkspace → 收集日志与报告 → 判定成败"的闭环。对于希望为自己的 Che/DevWorkspace 部署建立持续验证通道的团队,这套脚本(launch.sh、start-happypath-tests.sh、common.sh)本身就是一份可直接借鉴的模板。