ContextQMD
Back to Cherry Studio

Cherry Studio PR Test

.agents/skills/cherry-pr-test/SKILL.md

1.9.48.3 KB
Original Source

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:
    bash
    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:
    bash
    gh pr view <NUMBER> --json title,body,headRefName,files
  4. Checkout the PR branch:
    bash
    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):
    bash
    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):

    bash
    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):

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

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

    bash
    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:

    bash
    agent-browser connect 9222

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

    bash
    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:

    bash
    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:

    bash
    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):

    bash
    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:

    bash
    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.

markdown
# 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:

bash
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:

bash
# 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:

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