1. 识别失败的作业

获取当前提交对应的失败工作流运行：

COMMIT=$(git rev-parse HEAD)
./scripts/agents/tooling/agentTool.ts getCiStatus --commit "$COMMIT"

这将返回包含 run_id、status、conclusion 以及 jobs 数组的 JSON，数组中每个作业包含 {name, status, conclusion}。

如果提供了特定的作业名称（例如 /fix-tests electron-e2e），则专注于该作业。否则，从 jobs 数组中识别所有 conclusion == "failure" 的失败作业。

2. 下载失败的作业日志

仅下载失败作业的日志（而非所有制品）：

# 直接查看失败作业日志（最节省令牌）
gh run view <run-id> --log-failed

# 或者下载特定制品进行详细分析
./scripts/agents/tooling/agentTool.ts downloadArtifact --run-id <run-id> --artifact <artifact-name> --dest /tmp/<folder>

按作业划分的制品名称

3. 对失败进行分类

分析日志以确定失败类型：

Lint/类型错误 (build 作业)

症状：ESLint 错误，build 作业日志中的 TypeScript 错误

# 查找 lint 错误
grep -i "error\|warning" /tmp/logs.txt | head -20

# 常见模式：
# - "'foo' is defined but never used"
# - "Type 'X' is not assignable to type 'Y'"
# - "Unexpected any. Specify a different type"

修复：在源文件中解决 lint/类型错误。本地运行以验证：

pnpm lint
pnpm exec tsc -b

测试失败

症状：测试断言失败，超时错误

# 对于单元测试 (build 作业)
grep -i "fail\|error\|timeout" /tmp/logs.txt

修复：更新测试断言或修复代码逻辑。本地运行：

# 单元测试
pnpm --filter @tearleads/<package> test

# E2E 测试
pnpm --filter @tearleads/client test:e2e

覆盖率下降 (build 作业)

症状："Coverage threshold not met" 错误

# 查找覆盖率错误
grep -i "coverage\|threshold" /tmp/logs.txt

修复：添加测试以恢复覆盖率。检查哪些文件下降了：

# 本地运行覆盖率测试
pnpm --filter @tearleads/<package> test:coverage

# 检查覆盖率报告
cat packages/<package>/coverage/coverage-summary.json

重点关注：

• 缺少测试的新代码
• 未覆盖的分支
• 未调用的函数

不稳定的测试

症状：测试在本地通过，但在 CI 中间歇性失败

常见原因：

• 异步代码中的竞态条件
• 依赖于时间的断言
• 测试之间的共享状态

修复选项：

1. 添加显式的等待/重试
2. 隔离测试状态
3. 使用确定性的模拟
4. 暂时标记为 .skip 并创建问题

基础设施/超时失败

症状：网络错误、服务不可用、无测试输出的超时

修复：通常是暂时性的 - 重新运行 CI：

./scripts/agents/tooling/agentTool.ts rerunWorkflow --run-id <run-id>

如果持续存在，检查：

• CI 资源限制
• 外部服务依赖
• 数据库连接问题

4. 作业特定修复

build 作业

build 作业运行 lint、类型检查、构建以及带覆盖率的测试。

# 本地运行完整的构建流水线
pnpm lint && pnpm exec tsc -b && pnpm build && pnpm test:coverage

常见问题：

• Lint 错误：在源文件中修复，运行 pnpm lint
• 类型错误：修复类型，运行 pnpm exec tsc -b
• 构建错误：检查导入，运行 pnpm build
• 覆盖率下降：添加测试，运行 pnpm --filter @tearleads/<pkg> test:coverage

web-e2e / electron-e2e 作业

# 下载 Playwright 报告
./scripts/agents/tooling/agentTool.ts downloadArtifact --run-id <run-id> --artifact playwright-report --dest /tmp/playwright
open /tmp/playwright/index.html

# 本地运行
pnpm --filter @tearleads/client test:e2e

常见问题：

• 选择器已更改：更新测试中的选择器
• 时序问题：添加 await page.waitFor* 断言
• API 响应已更改：更新期望值

android-maestro-release / ios-maestro-release 作业

# 下载调试制品
./scripts/agents/tooling/agentTool.ts downloadArtifact --run-id <run-id> --artifact android-maestro-debug --dest /tmp/maestro

# 查看截图
open /tmp/maestro/*.png

# 检查 logcat (Android)
grep -i "console\|error\|capacitor" /tmp/maestro/logcat.txt

# 查看 UI 层级结构
cat /tmp/maestro/ui-hierarchy.xml

常见问题：

• 未找到元素：更新选择器或添加等待
• WebView NAF="true"：在测试中添加 androidWebViewHierarchy: devtools
• 时序问题：使用 waitForAnimationToEnd 或增加 retryTapIfNoChange

5. 应用修复并验证

1. 在源代码中进行修复

2. 本地验证（运行相关的测试命令）

3. 提交并推送：

   git add -A
   git commit -S -m "fix(tests): <修复描述>" >/dev/null
   git push >/dev/null
   

4. 报告修复了哪个作业以及更改了什么

6. 常见问题参考

Maestro: WebView 不可访问 (NAF="true")

如果 Maestro 在 WebView 中找不到元素：

appId: com.tearleads.app
androidWebViewHierarchy: devtools
- launchApp:
    clearState: true
- assertVisible: "My Text"

Android: JavaScript 错误 / 空白屏幕

如果应用启动后显示空白白屏，检查 logcat 中的 JavaScript 错误：

# 在 Maestro 调试输出中检查 JS 错误
grep -i "Capacitor/Console\|TypeError\|Error" /tmp/maestro/logcat.txt

# 常见错误："Object.hasOwn is not a function"
# 这发生在 WebView < Chrome 93 的情况下（系统镜像附带的 WebView 是 91 版）

根本原因：Android 系统镜像（即使是 API 35）默认附带 WebView 91。WebView 91 不支持像 Object.hasOwn 这样的 ES2022 功能。

修复：在 packages/client/src/main.tsx 中为缺失的功能添加 polyfill：

// 在任何导入之前
if (!Object.hasOwn) {
  Object.defineProperty(Object, 'hasOwn', {
    value: function (obj: object, prop: PropertyKey) {
      return Object.prototype.hasOwnProperty.call(obj, prop);
    },
    configurable: true,
    writable: true
  });
}

检查模拟器上的 WebView 版本：

adb shell "dumpsys webviewupdate" | grep "Current WebView"

Maestro: 使用 evalScript 进行复杂交互

- evalScript: document.querySelector('[data-testid="my-button"]').click()

Playwright: 不稳定的选择器

// 替代方案：
await page.click('.dynamic-class');

// 使用：
await page.getByTestId('button-submit').click();
await page.getByRole('button', { name: 'Submit' }).click();

覆盖率：为新代码添加测试

1. 在覆盖率报告中识别未覆盖的行
2. 编写执行这些代码路径的测试
3. 专注于分支覆盖率（if/else, switch cases）
4. 运行 pnpm --filter @tearleads/<pkg> test:coverage 以验证

令牌效率

• 尽可能使用 --log-failed 而不是下载所有制品
• 使用 --jq 过滤以最小化 JSON 响应大小
• 仅下载特定失败作业的制品
• 抑制 git 输出：git commit ... >/dev/null && git push >/dev/null

每周安装数

1

仓库

a2f0/tearleads

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketFailSnykPass

安装于

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1

1. Identify Failing Jobs

Get the failing workflow run for the current commit:

COMMIT=$(git rev-parse HEAD)
./scripts/agents/tooling/agentTool.ts getCiStatus --commit "$COMMIT"

This returns JSON with run_id, status, conclusion, and jobs array with each job's {name, status, conclusion}.

If a specific job name was provided (e.g., /fix-tests electron-e2e), focus on that job. Otherwise, identify all failing jobs from the jobs array where conclusion == "failure".

2. Download Failed Job Logs

Download only the logs for failed jobs (not all artifacts):

# View failed job logs directly (most token-efficient)
gh run view <run-id> --log-failed

# Or download specific artifact for detailed analysis
./scripts/agents/tooling/agentTool.ts downloadArtifact --run-id <run-id> --artifact <artifact-name> --dest /tmp/<folder>

Artifact Names by Job

3. Categorize the Failure

Analyze the logs to determine the failure type:

Lint/Type Errors (build job)

Symptoms : ESLint errors, TypeScript errors in build job logs

# Look for lint errors
grep -i "error\|warning" /tmp/logs.txt | head -20

# Common patterns:
# - "'foo' is defined but never used"
# - "Type 'X' is not assignable to type 'Y'"
# - "Unexpected any. Specify a different type"

Fix : Address the lint/type error in the source file. Run locally to verify:

pnpm lint
pnpm exec tsc -b

Test Failures

Symptoms : Test assertion failures, timeout errors

# For unit tests (build job)
grep -i "fail\|error\|timeout" /tmp/logs.txt

Fix : Update test assertions or fix the code logic. Run locally:

# Unit tests
pnpm --filter @tearleads/<package> test

# E2E tests
pnpm --filter @tearleads/client test:e2e

Coverage Drop (build job)

Symptoms : "Coverage threshold not met" errors

# Look for coverage errors
grep -i "coverage\|threshold" /tmp/logs.txt

Fix : Add tests to restore coverage. Check which files dropped:

# Run coverage locally
pnpm --filter @tearleads/<package> test:coverage

# Check the coverage report
cat packages/<package>/coverage/coverage-summary.json

Focus on:

• New code that lacks tests
• Branches not covered
• Functions not called

Flaky Tests

Symptoms : Test passes locally but fails intermittently in CI

Common causes :

• Race conditions in async code
• Timing-dependent assertions
• Shared state between tests

Fix options :

1. Add explicit waits/retries
2. Isolate test state
3. Use deterministic mocks
4. Mark as .skip temporarily and create an issue

Infrastructure/Timeout Failures

Symptoms : Network errors, service unavailable, timeout without test output

Fix : Usually transient - rerun CI:

./scripts/agents/tooling/agentTool.ts rerunWorkflow --run-id <run-id>

If persistent, check:

• CI resource limits
• External service dependencies
• Database connection issues

4. Job-Specific Fixes

build Job

The build job runs lint, type-check, build, and tests with coverage.

# Run the full build pipeline locally
pnpm lint && pnpm exec tsc -b && pnpm build && pnpm test:coverage

Common issues:

• Lint errors : Fix in source, run pnpm lint
• Type errors : Fix types, run pnpm exec tsc -b
• Build errors : Check imports, run pnpm build
• Coverage drop : Add tests, run pnpm --filter @tearleads/<pkg> test:coverage

web-e2e / electron-e2e Jobs

# Download Playwright report
./scripts/agents/tooling/agentTool.ts downloadArtifact --run-id <run-id> --artifact playwright-report --dest /tmp/playwright
open /tmp/playwright/index.html

# Run locally
pnpm --filter @tearleads/client test:e2e

Common issues:

• Selector changed : Update the selector in the test
• Timing issue : Add await page.waitFor* assertions
• API response changed : Update expected values

android-maestro-release / ios-maestro-release Jobs

# Download debug artifacts
./scripts/agents/tooling/agentTool.ts downloadArtifact --run-id <run-id> --artifact android-maestro-debug --dest /tmp/maestro

# View screenshots
open /tmp/maestro/*.png

# Check logcat (Android)
grep -i "console\|error\|capacitor" /tmp/maestro/logcat.txt

# View UI hierarchy
cat /tmp/maestro/ui-hierarchy.xml

Common issues:

• Element not found : Update selector or add wait
• WebView NAF="true" : Add androidWebViewHierarchy: devtools to test
• Timing issue : Use waitForAnimationToEnd or increase retryTapIfNoChange

5. Apply Fix and Verify

1. Make the fix in the source code

2. Verify locally (run the relevant test command)

3. Commit and push:

   git add -A
   git commit -S -m "fix(tests): <description of fix>" >/dev/null
   git push >/dev/null
   

4. Report which job was fixed and what changed

6. Common Issues Reference

Maestro: WebView Not Accessible (NAF="true")

If Maestro can't find elements in a WebView:

appId: com.tearleads.app
androidWebViewHierarchy: devtools
- launchApp:
    clearState: true
- assertVisible: "My Text"

Android: JavaScript Errors / Blank Screen

If the app shows a blank white screen after launch, check logcat for JavaScript errors:

# Check for JS errors in Maestro debug output
grep -i "Capacitor/Console\|TypeError\|Error" /tmp/maestro/logcat.txt

# Common error: "Object.hasOwn is not a function"
# This occurs on WebView < Chrome 93 (system images ship with WebView 91)

Root cause : Android system images (even API 35) ship with WebView 91 by default. WebView 91 doesn't support ES2022 features like Object.hasOwn.

Fix : Add polyfills for missing features in packages/client/src/main.tsx:

// Before any imports
if (!Object.hasOwn) {
  Object.defineProperty(Object, 'hasOwn', {
    value: function (obj: object, prop: PropertyKey) {
      return Object.prototype.hasOwnProperty.call(obj, prop);
    },
    configurable: true,
    writable: true
  });
}

Check WebView version on emulator:

adb shell "dumpsys webviewupdate" | grep "Current WebView"

Maestro: Use evalScript for Complex Interactions

- evalScript: document.querySelector('[data-testid="my-button"]').click()

Playwright: Flaky Selector

// Instead of:
await page.click('.dynamic-class');

// Use:
await page.getByTestId('button-submit').click();
await page.getByRole('button', { name: 'Submit' }).click();

Coverage: Adding Tests for New Code

1. Identify uncovered lines in coverage report
2. Write tests that exercise those code paths
3. Focus on branch coverage (if/else, switch cases)
4. Run pnpm --filter @tearleads/<pkg> test:coverage to verify

Token Efficiency

• Use --log-failed instead of downloading all artifacts when possible
• Use --jq filtering to minimize JSON response size
• Only download artifacts for the specific failing job
• Suppress git output: git commit ... >/dev/null && git push >/dev/null

Weekly Installs

1

Repository

a2f0/tearleads

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketFailSnykPass

Installed on

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1