cherry-pr-test

name	cherry-pr-test
description	Test Cherry Studio PRs by checking out the branch, launching the Electron app in debug mode, and running interactive UI tests via CDP.

Cherry Studio PR Test

Automated PR testing workflow for Cherry Studio. Checks out a PR, launches the Electron app with Chrome DevTools Protocol, connects agent-browser, and runs interactive UI + code review tests.

Prerequisites

• gh CLI installed and authenticated
• agent-browser installed (for CDP-based UI testing)
• pnpm installed with project dependencies (pnpm install)

Constraints

• Always kill existing Cherry Studio processes before launching a new instance.
• Never leave debug processes running after testing completes.
• Always switch back to the default branch after testing.
• Always show the test report to the user before posting it.

Arguments

$ARGUMENTS may contain:

• A PR number (e.g., 13955)
• A PR URL (e.g., https://github.com/CherryHQ/cherry-studio/pull/13955)
• Keywords like "latest", "recent" to pick a recent PR
• Empty — list recent PRs and let the user choose

Workflow

Phase 1: Select & Checkout PR

1. If no PR number given, list recent open PRs:

   gh pr list --repo CherryHQ/cherry-studio --state open --limit 10 \
     --json number,title,author,createdAt,headRefName,changedFiles \
     --template '{{range .}}#{{.number}} | {{.title}} | by {{.author.login}} | files: {{.changedFiles}}
   {{end}}'
   

2. Ask the user to pick one (or auto-pick if "latest"/"recent").
3. View PR details to understand what changed:

   gh pr view <NUMBER> --json title,body,headRefName,files
   

4. Checkout the PR branch:

   gh pr checkout <NUMBER>
   

5. Read the key changed files to understand the scope of changes.

Phase 2+3: Static Analysis & Launch App (parallel)

Static analysis and app launch are independent — run them in parallel to save time.

Static Analysis (can run while app is starting)

1. TypeScript typecheck (catch type errors early):

   pnpm typecheck 2>&1 | grep -E "error TS|exited with code"
   

2. Review blocked files: Check if the PR modifies files with @deprecated / V2 DATA&UI REFACTORING headers. These files are blocked for feature changes until v2.0.0.
3. Scan for common issues:
   • Hardcoded strings (should use i18n)
   • console.log usage (should use loggerService)
   • Missing type annotations on new public interfaces

Record all findings for the final report.

Launch App

1. Kill any existing Cherry Studio processes (graceful SIGTERM first):

   pkill -f "cherry-studio.*Electron" 2>/dev/null
   pkill -f "electron-vite" 2>/dev/null
   lsof -ti :9222 | xargs kill 2>/dev/null
   lsof -ti :5173 | xargs kill 2>/dev/null
   sleep 3
   # Escalate to SIGKILL only if processes remain
   lsof -ti :9222 | xargs kill -9 2>/dev/null
   lsof -ti :5173 | xargs kill -9 2>/dev/null
   

2. Start in debug mode (includes --remote-debugging-port=9222):

   nohup pnpm debug > /tmp/cherry-debug.log 2>&1 &
   

3. Wait for startup (typically 20-30s):

   for i in $(seq 1 30); do
     lsof -i :9222 2>/dev/null | grep LISTEN && break
     sleep 2
   done
   

Phase 4: Connect agent-browser

1. Connect:

   agent-browser connect 9222
   

   If connect fails, fall back to websocket URL from logs:

   WS_URL=$(grep "DevTools listening" /tmp/cherry-debug.log | sed 's/.*ws:/ws:/')
   agent-browser --cdp "$WS_URL" navigate http://localhost:5173
   

2. Verify connection and identify the main page:

   agent-browser tab
   

   You should see the main Cherry Studio page at http://localhost:5173/. If multiple tabs are listed, use agent-browser tab <N> to select the main one.

3. Handle first-launch scenarios:

   • V2 Data Migration Wizard: On the v2 branch (or fresh dev data), the app may show a migration wizard (/migrationV2.html) before the main UI. Click through: 介绍(下一步) → 备份(我已备份，开始迁移) → 迁移(确定) → 完成(重启应用). After "重启应用", kill and relaunch the app (the restart button doesn't work in dev mode).
   • Splash screen: Wait up to 30s for the splash to dismiss.

4. Create screenshot directory for this PR:

   mkdir -p /tmp/pr-<NUMBER>
   

   Use this directory for all screenshots: /tmp/pr-<NUMBER>/<descriptive-name>.png

Phase 5: Interactive UI Testing

Based on the PR's changed files, navigate to the relevant pages and test. Use your judgement to decide what to test — the PR description and changed files should guide your testing strategy.

General Approach

1. Take a screenshot of the current state
2. Use agent-browser snapshot -i to discover interactive elements
3. Interact with elements (click, fill, drag, etc.)
4. Screenshot and verify the result
5. Verify state changes if relevant (via agent-browser eval)

Key Testing Points

• UI renders correctly: New components appear in the right place
• Interactions work: Toggles, inputs, buttons all function
• State persistence: Changes survive across page navigations
• Theme compatibility: Test in both light and dark modes
• Layout modes: If sidebar/layout is involved, test at different sizes
• i18n: Switch language and verify new strings appear correctly
• Edge cases: Boundary conditions, rapid toggling, empty states

Phase 6: Cleanup

After testing:

1. Kill all Cherry Studio processes (graceful SIGTERM first):

   pkill -f "cherry-studio.*Electron" 2>/dev/null
   pkill -f "electron-vite" 2>/dev/null
   lsof -ti :9222 | xargs kill 2>/dev/null
   lsof -ti :5173 | xargs kill 2>/dev/null
   sleep 3
   lsof -ti :9222 | xargs kill -9 2>/dev/null
   lsof -ti :5173 | xargs kill -9 2>/dev/null
   

2. Switch back to the default branch:

   default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
   git checkout "${default_branch:-main}"
   

Phase 7: Test Report

Generate a structured report with screenshots. Save the report as /tmp/pr-<NUMBER>/report.md alongside the screenshots.

# PR #<NUMBER> 测试报告

**PR 标题**: <title>
**作者**: @<author>
**分支**: <branch>
**修改文件数**: <count>

## 静态分析

| 检查项 | 结果 | 说明 |
|--------|------|------|
| TypeScript 类型检查 | ✅/❌ | ... |
| 受阻文件检查 | ✅/⚠️ | ... |
| console.log 使用 | ✅/❌ | ... |

## UI 测试

### <Test Case Name>
<description of what was tested and the result>
![screenshot](<filename>.png)

## 发现的问题
(if any)

## 结论
- 问题总数：N
- 建议：APPROVE / REQUEST_CHANGES / COMMENT

If the user requests, copy the report directory to a more accessible location (e.g., Desktop) for sharing.

Troubleshooting

Port 9222 not listening after startup

The pnpm debug script passes --remote-debugging-port=9222 to Electron. If not working:

• Check logs: tail -50 /tmp/cherry-debug.log
• Kill by port: lsof -ti :9222 | xargs kill -9
• Verify electron-vite is running: ps aux | grep electron-vite

agent-browser connect fails

Use direct websocket URL:

WS_URL=$(grep "DevTools listening" /tmp/cherry-debug.log | grep 9222 | sed 's/.*\(ws:\/\/[^ ]*\)/\1/')
agent-browser --cdp "$WS_URL" tab

agent-browser target jumps to wrong page

Electron apps have multiple CDP targets (main window + webviews for mini-apps). If agent-browser connects to a webview instead of the main page:

# List all targets
agent-browser tab
# Switch to the main page (usually tab 0, URL contains localhost:5173)
agent-browser tab 0

After opening/closing mini-apps, always verify you're on the right target with agent-browser tab.

V2 Data Migration Wizard

On the v2 branch, the app may show a data migration wizard on first launch. This is not a bug — it's expected when dev data hasn't been migrated yet. Click through the wizard steps, then restart the app manually (kill + relaunch). The wizard only appears once; subsequent launches go straight to the main UI.

App stuck on splash screen

Wait longer (up to 30s on first launch). The app needs to:

• Build and serve renderer via Vite dev server (port 5173)
• Run database migrations
• Initialize services (MCP, etc.)

Empty CDP target list

After connecting, if agent-browser tab shows only about:blank:

agent-browser navigate http://localhost:5173
sleep 10
agent-browser tab