e2e-ci-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

E2E CI Debug

E2E CI 调试

Debug Playwright E2E test failures from CI with automated artifact downloading, intelligent failure parsing, and local reproduction guidance.

通过自动下载工件、智能解析失败原因以及本地复现指引，调试CI中的Playwright E2E测试失败问题。

Quick Start

快速开始

Full debugging workflow:

bash

undefined

完整调试工作流：

bash

undefined

1. Download artifacts from failing CI run

1. 从失败的CI运行中下载工件

.cursor/skills/e2e-ci-debug/scripts/download-artifacts.sh

2. Parse JUnit results to identify failures

2. 解析JUnit结果以定位失败用例

.cursor/skills/e2e-ci-debug/scripts/parse-junit.py

3. Run local reproduction command (shown by parse-junit.py)

3. 运行本地复现命令（由parse-junit.py输出）

cd dap-workspace && nx affected -t e2e --base=origin/main

4. Clean up downloaded artifacts (Important!)

4. 清理已下载的工件（重要！）

.cursor/skills/e2e-ci-debug/scripts/cleanup-artifacts.sh


**Output:** Failing spec name, error message, file location, stack trace, and local reproduction command.

.cursor/skills/e2e-ci-debug/scripts/cleanup-artifacts.sh


**输出内容：** 失败用例名称、错误信息、文件位置、堆栈跟踪以及本地复现命令。

Workflow E2E Test Structure

工作流E2E测试结构

Main Workflow E2E Tests

主工作流E2E测试

Path:

dap-workspace/tests/workflow/typescript/

Config:
```
playwright.config.ts
```
Test Directory:
```
tests/e2e/
```
- ```
builder/
```
  - Workflow builder tests (9 spec files)
- ```
catalog/
```
  - Catalog navigation tests (2 spec files)
- ```
visual-diff/
```
  - Visual regression tests (1 spec file)
Projects:
```
sanity
```
→
```
setup
```
→
```
e2e
```
(dependency chain)

Reports:

reports/typescript-playwright/workflow/

HTML:
```
playwright-report/
```
JUnit:
```
junit.xml
```

Base URL:
```
WORKFLOW_BASE_URL
```
env var or
```
http://localhost:4200
```

路径：

dap-workspace/tests/workflow/typescript/

配置文件：
```
playwright.config.ts
```
测试目录：
```
tests/e2e/
```
- ```
builder/
```
  - 工作流构建器测试（9个测试文件）
- ```
catalog/
```
  - 目录导航测试（2个测试文件）
- ```
visual-diff/
```
  - 视觉回归测试（1个测试文件）
项目依赖链：
```
sanity
```
→
```
setup
```
→
```
e2e
```

报告路径：

reports/typescript-playwright/workflow/

HTML报告：
```
playwright-report/
```
JUnit报告：
```
junit.xml
```

基础URL：环境变量
```
WORKFLOW_BASE_URL
```
或默认值
```
http://localhost:4200
```

Component-Level E2E Tests

组件级E2E测试

Path:

dap-workspace/libs/workflow/workflow-fe/workflow-fe-e2e/

Config:
```
playwright.config.ts
```
Test Directory:
```
src/
```
WebServer: Auto-starts
```
workflow-root-fe
```
on
```
http://localhost:4200
```
Used for component-level testing within workflow libraries

路径：

dap-workspace/libs/workflow/workflow-fe/workflow-fe-e2e/

配置文件：
```
playwright.config.ts
```
测试目录：
```
src/
```
Web服务器：自动在
```
http://localhost:4200
```
启动
```
workflow-root-fe
```
用于工作流库内的组件级测试

CI Workflow Context

CI工作流上下文

PR E2E Tests

PR E2E测试

When they run:

Automatically on pull requests via

dispatcher.yml

→

pr-core.yaml

→

pr-processor.yml

Only affected E2E tests execute (via
```
nx affected -t e2e
```
)

How to find them:

bash

undefined

运行时机：

通过

dispatcher.yml

→

pr-core.yaml

→

pr-processor.yml

在拉取请求时自动运行

仅执行受影响的E2E测试（通过
```
nx affected -t e2e
```
）

查找方式：

bash

undefined

List PR checks

列出PR检查项

gh pr checks

View specific run

查看特定运行记录

gh run view <run_id> --log

Download PR E2E artifacts

下载PR E2E工件

gh run download <run_id> -n <artifact-name>


**Workflow chain:**
1. `.github/workflows/dispatcher.yml` - PR entry point
2. `.github/workflows/pr-core.yaml` - Runs test, lint, docker, deploy jobs
3. `pr-processor.yml` (external) - Handles deployment and E2E execution

gh run download <run_id> -n <artifact-name>


**工作流链：**
1. `.github/workflows/dispatcher.yml` - PR入口
2. `.github/workflows/pr-core.yaml` - 运行测试、代码检查、Docker构建、部署任务
3. `pr-processor.yml`（外部） - 处理部署和E2E测试执行

Local Debugging

本地调试

Run workflow E2E tests locally before pushing to CI:

推送到CI前，先在本地运行工作流E2E测试：

Run Workflow E2E Project

运行工作流E2E项目

bash

cd dap-workspace

bash

cd dap-workspace

Run full workflow E2E suite (with project dependencies)

运行完整工作流E2E套件（包含项目依赖）

nx e2e tests-workflow-typescript --project=e2e

Run only sanity tests

仅运行sanity测试

nx e2e tests-workflow-typescript --project=sanity

undefined

nx e2e tests-workflow-typescript --project=sanity

undefined

Run Affected E2E Tests

运行受影响的E2E测试

bash

cd dap-workspace

bash

cd dap-workspace

Compare against main branch

与main分支对比

nx affected -t e2e --base=origin/main

Compare against specific branch

与特定分支对比

nx affected -t e2e --base=origin/v4.0

undefined

nx affected -t e2e --base=origin/v4.0

undefined

Run Specific Test File

运行特定测试文件

bash

cd dap-workspace/tests/workflow/typescript

bash

cd dap-workspace/tests/workflow/typescript

Run single spec

运行单个测试文件

npx playwright test tests/e2e/builder/workflow-builder.e2e.spec.ts

Run specific suite

运行特定目录下的测试

npx playwright test tests/e2e/builder

Run with UI mode for debugging

以UI模式运行进行调试

npx playwright test --ui

Run with headed browser

以有头浏览器模式运行

npx playwright test --headed

undefined

npx playwright test --headed

undefined

View Local Test Reports

查看本地测试报告

bash

cd dap-workspace

bash

cd dap-workspace

Open HTML report for workflow tests

打开工作流测试的HTML报告

npx playwright show-report reports/typescript-playwright/workflow/playwright-report

undefined

npx playwright show-report reports/typescript-playwright/workflow/playwright-report

undefined

PR Checks Debugging

PR检查项调试

E2E Test Failures

E2E测试失败

Find failing E2E job:

bash

gh pr checks
# Look for "Run E2E Tests" or similar job names

Download artifacts:

bash

# Use the download-artifacts.sh script (auto-detects current PR)
.cursor/skills/e2e-ci-debug/scripts/download-artifacts.sh

# Or manually with run ID
.cursor/skills/e2e-ci-debug/scripts/download-artifacts.sh <run_id>

Parse failures:

bash

.cursor/skills/e2e-ci-debug/scripts/parse-junit.py

Reproduce locally:

bash

cd dap-workspace
nx affected -t e2e --base=origin/<base-branch>

查找失败的E2E任务：

bash

gh pr checks
# 查找名为“Run E2E Tests”或类似的任务

下载工件：

bash

# 自动检测当前PR并下载
.cursor/skills/e2e-ci-debug/scripts/download-artifacts.sh

# 或指定运行ID下载
.cursor/skills/e2e-ci-debug/scripts/download-artifacts.sh <run_id>

解析失败原因：

bash

.cursor/skills/e2e-ci-debug/scripts/parse-junit.py

本地复现：

bash

cd dap-workspace
nx affected -t e2e --base=origin/<base-branch>

Unit Test Failures

单元测试失败

bash

undefined

bash

undefined

View test job logs

查看测试任务日志

gh run view <run_id> --log --job <job_id>

Find the specific test command in logs

在日志中查找具体的测试命令

Usually: nx affected -t test --base=origin/<base-branch>

通常为：nx affected -t test --base=origin/<base-branch>

Run locally

本地运行

cd dap-workspace nx affected -t test --base=origin/main

undefined

cd dap-workspace nx affected -t test --base=origin/main

undefined

Lint Failures

代码检查失败

bash

undefined

bash

undefined

View lint job logs

查看代码检查任务日志

gh run view <run_id> --log --job <job_id>

Run locally

本地运行代码检查

cd dap-workspace nx affected -t lint --base=origin/main

Auto-fix many issues

自动修复多数问题

nx affected -t lint --base=origin/main --fix

undefined

nx affected -t lint --base=origin/main --fix

undefined

Docker Build Failures

Docker构建失败

bash

undefined

bash

undefined

View docker job logs

查看Docker任务日志

gh run view <run_id> --log --job <job_id>

Look for:

排查方向：

- Docker build errors

- Docker构建错误

- Missing dependencies

- 缺失依赖

- Build context issues

- 构建上下文问题

- Registry authentication problems

- 镜像仓库认证问题

undefined

undefined

Utility Scripts

实用脚本

All scripts are located in the skill's

scripts/

directory. After installation via

npx add-skill

, they'll be at

.cursor/skills/e2e-ci-debug/scripts/

所有脚本位于技能的

scripts/

目录下。通过

npx add-skill

安装后，路径为

.cursor/skills/e2e-ci-debug/scripts/

download-artifacts.sh

Downloads Playwright test artifacts from GitHub Actions for the current PR.

Usage:

bash

undefined

从GitHub Actions下载当前PR的Playwright测试工件。

使用方式：

bash

undefined

Auto-detect from current PR

自动检测当前PR

./download-artifacts.sh

Specify run ID

指定运行ID

./download-artifacts.sh <run_id>

Specify run ID and artifact name

指定运行ID和工件名称

./download-artifacts.sh <run_id> <artifact_name>


**What it does:**
- Fetches Playwright report archives from GitHub Actions
- Extracts to `playwright-results/` directory
- Cleans up ZIP files after extraction

./download-artifacts.sh <run_id> <artifact_name>


**功能：**
- 从GitHub Actions获取Playwright报告压缩包
- 解压到`playwright-results/`目录
- 解压后清理ZIP文件

parse-junit.py

Parses JUnit XML from Playwright results and extracts structured failure information, including paths to failure screenshots for AI model analysis.

Usage:

bash

undefined

解析Playwright结果中的JUnit XML文件，提取结构化的失败信息，包括失败截图的路径供AI模型分析。

使用方式：

bash

undefined

Parse default location

解析默认路径下的文件

./parse-junit.py

Parse specific file

解析指定文件

./parse-junit.py path/to/junit.xml

Output as JSON (includes screenshot/trace/video paths)

以JSON格式输出（包含截图/跟踪/视频路径）

./parse-junit.py --json

Show screenshot paths for AI model analysis

显示截图路径供AI模型分析

./parse-junit.py --screenshots

Open HTML report after parsing

解析后打开HTML报告

./parse-junit.py --open-report

Show help

显示帮助信息

./parse-junit.py --help


**Output includes:**
- Test name and status
- Error message
- File location (spec file:line number)
- Stack trace
- **Screenshot paths** (absolute paths for AI model to read with Read tool)
- **Trace file paths** (for Playwright trace viewer)
- **Video paths** (if video recording was enabled)
- Local reproduction command for workflow tests

**Output Formats:**
- **Text (default):** Human-readable with colors and emojis, shows artifact paths inline
- **JSON (`--json`):** Structured output with `screenshots`, `traces`, and `videos` arrays per failure

**AI Model Integration:**
The screenshot paths are absolute, allowing AI models to directly read the images using the Read tool to visually analyze where Playwright failed.

./parse-junit.py --help


**输出内容包括：**
- 测试名称和状态
- 错误信息
- 文件位置（测试文件:行号）
- 堆栈跟踪
- **截图路径**（绝对路径，供AI模型使用Read工具读取）
- **跟踪文件路径**（用于Playwright trace viewer）
- **视频路径**（若启用了视频录制）
- 工作流测试的本地复现命令

**输出格式：**
- **文本（默认）：** 带颜色和表情符号的人类可读格式，内联显示工件路径
- **JSON（`--json`）：** 结构化输出，每个失败项包含`screenshots`、`traces`和`videos`数组

**AI模型集成：**
截图路径为绝对路径，AI模型可直接使用Read工具读取图片，可视化分析Playwright的失败位置。

find-failing-job.sh

Finds failing E2E jobs from recent PR workflow runs.

Usage:

bash

undefined

从近期PR工作流运行记录中查找失败的E2E任务。

使用方式：

bash

undefined

List recent PR workflow runs

列出近期PR工作流运行记录

./find-failing-job.sh

Find specific workflow

查找特定工作流

./find-failing-job.sh "PR Deploy Core"


**Output:**
- Recent workflow runs with status
- Run ID and job IDs for failed E2E tests
- Command to download artifacts

./find-failing-job.sh "PR Deploy Core"


**输出内容：**
- 近期工作流运行记录及状态
- 失败E2E测试的运行ID和任务ID
- 下载工件的命令

cleanup-artifacts.sh

Removes all downloaded Playwright artifacts after debugging.

Usage:

bash

./cleanup-artifacts.sh

What it removes:

```
playwright-results/
```
directory
```
*-playwright-results.zip
```
files
Any other temporary E2E debug files

Safety:

Idempotent (safe to run multiple times)
Confirms cleanup with file count and freed disk space

调试完成后删除所有已下载的Playwright工件。

使用方式：

bash

./cleanup-artifacts.sh

清理内容：

```
playwright-results/
```
目录
```
*-playwright-results.zip
```
文件
其他临时E2E调试文件

安全性：

幂等操作（可安全多次运行）
会显示清理的文件数量和释放的磁盘空间以确认操作

Common Failure Patterns

常见失败模式

Test Timeout

测试超时

Symptom: Test exceeds timeout (default: 30s for sanity, 120s for setup, 30s for e2e)

Solutions:

Check for network delays or slow API responses
Increase timeout in
```
playwright.config.ts
```
if legitimate
Look for missing
```
await
```
on async operations

症状： 测试超过超时时间（默认：sanity测试30秒，setup测试120秒，e2e测试30秒）

解决方案：

检查网络延迟或API响应缓慢问题
若合理，在
```
playwright.config.ts
```
中增加超时时间
查找异步操作中缺失的
```
await
```
关键字

Element Not Found

元素未找到

Symptom:

Selector not found

Element is not visible

Solutions:

Verify element exists in the DOM
Check for timing issues (add proper waits)
Inspect for dynamic class names or IDs
Use data-testid attributes instead of classes

症状：

Selector not found

或

Element is not visible

解决方案：

验证元素是否存在于DOM中
检查时序问题（添加适当的等待）
检查动态类名或ID
使用data-testid属性替代类名

Setup/Seed Failures

初始化/数据填充失败

Symptom:

setup

project fails before

e2e

tests can run

Solutions:

Check database seeding in
```
tests/*/typescript/seed/*.setup.ts
```
Verify API endpoints are accessible
Ensure authentication/tokens are valid

症状：

setup

项目在

e2e

测试运行前失败

解决方案：

检查
```
tests/*/typescript/seed/*.setup.ts
```
中的数据库数据填充逻辑
验证API端点是否可访问
确保认证/令牌有效

Flaky Tests

不稳定测试

Symptom: Test passes locally but fails in CI (or vice versa)

Solutions:

Check for race conditions
Avoid hard-coded waits (
```
page.waitForTimeout()
```
)
Use proper Playwright assertions with auto-retry
Verify test isolation (no shared state)

症状： 本地测试通过但CI中失败（反之亦然）

解决方案：

检查竞态条件
避免硬编码等待（
```
page.waitForTimeout()
```
）
使用带自动重试的Playwright断言
确保测试隔离（无共享状态）

Additional Resources

额外资源

For detailed workflow documentation, artifact paths, and Playwright configuration details, see reference.md.

有关工作流文档、工件路径和Playwright配置的详细信息，请查看reference.md。

When to Use This Skill

使用场景

Use this skill when:

A PR has failing E2E checks and you need to debug
You want to reproduce CI E2E failures locally
You need to understand E2E test structure and locations
You're debugging flaky or timing-related test failures in PRs

在以下场景使用本技能：

PR中的E2E检查项失败，需要调试时
想要在本地复现CI中的E2E测试失败问题时
需要了解E2E测试的结构和位置时
调试PR中不稳定或与时序相关的测试失败时