Cherry Studio PR Test

Workflow de test automatisé des PR pour Cherry Studio. Récupère une PR, lance l'application Electron avec le Chrome DevTools Protocol, connecte agent-browser, et exécute des tests interactifs UI + revue de code.

Prérequis

gh CLI installé et authentifié
agent-browser installé (pour les tests UI basés sur CDP)
pnpm installé avec les dépendances du projet (pnpm install)

Contraintes

Toujours tuer les processus Cherry Studio existants avant de lancer une nouvelle instance.
Ne jamais laisser les processus de debug en cours d'exécution après la fin des tests.
Toujours revenir à la branche par défaut après les tests.
Toujours afficher le rapport de test à l'utilisateur avant de le poster.

Arguments

$ARGUMENTS peut contenir :

Un numéro de PR (ex. 13955)
Une URL de PR (ex. https://github.com/CherryHQ/cherry-studio/pull/13955)
Des mots-clés comme « latest », « recent » pour sélectionner une PR récente
Vide — affiche les PR récentes et laisse l'utilisateur choisir

Workflow

Phase 1 : Sélectionner et récupérer la PR

Si aucun numéro de PR fourni, afficher les PR ouvertes récentes :

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}}'

Demander à l'utilisateur d'en choisir une (ou sélection automatique si « latest »/« recent »).
Afficher les détails de la PR pour comprendre ce qui a changé :
```
gh pr view <NUMBER> --json title,body,headRefName,files
```
Récupérer la branche de la PR :
```
gh pr checkout <NUMBER>
```
Lire les fichiers clés modifiés pour comprendre l'étendue des modifications.

Phase 2+3 : Analyse statique et lancement de l'app (parallèle)

L'analyse statique et le lancement de l'app sont indépendants — les exécuter en parallèle pour gagner du temps.

Analyse statique (peut s'exécuter pendant le démarrage de l'app)

Vérification des types TypeScript (détecter les erreurs de type rapidement) :
```
pnpm typecheck 2>&1 | grep -E "error TS|exited with code"
```
Examiner les fichiers bloqués : Vérifier si la PR modifie des fichiers avec les en-têtes @deprecated / V2 DATA&UI REFACTORING. Ces fichiers sont bloqués pour les changements de fonctionnalités jusqu'à v2.0.0.
Analyser les problèmes courants :
- Chaînes en dur (devrait utiliser i18n)
- Utilisation de console.log (devrait utiliser loggerService)
- Annotations de type manquantes sur les nouvelles interfaces publiques

Enregistrer tous les résultats pour le rapport final.

Lancer l'app

Tuer tout processus Cherry Studio existant (SIGTERM gracieux d'abord) :

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
# Escalader à SIGKILL seulement si les processus persistent
lsof -ti :9222 | xargs kill -9 2>/dev/null
lsof -ti :5173 | xargs kill -9 2>/dev/null

Démarrer en mode debug (inclut --remote-debugging-port=9222) :
```
nohup pnpm debug > /tmp/cherry-debug.log 2>&1 &
```

Attendre le démarrage (généralement 20-30s) :

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

Phase 4 : Connecter agent-browser

Se connecter :

agent-browser connect 9222

Si connect échoue, se replier sur l'URL websocket des logs :

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

Vérifier la connexion et identifier la page principale :
```
agent-browser tab
```
Vous devriez voir la page principale de Cherry Studio à http://localhost:5173/. Si plusieurs onglets sont affichés, utiliser agent-browser tab <N> pour sélectionner le principal.
Gérer les scénarios de premier lancement :
- Assistant de migration V2 : Sur la branche v2 (ou données dev fraîches), l'app peut afficher un assistant de migration (/migrationV2.html) avant l'UI principale. Cliquer à travers : 介绍(下一步) → 备份(我已备份，开始迁移) → 迁移(确定) → 完成(重启应用). Après « 重启应用 », tuer et relancer l'app (le bouton redémarrage ne fonctionne pas en mode dev).
- Écran de démarrage : Attendre jusqu'à 30s que l'écran de démarrage disparaisse.
Créer un répertoire de captures d'écran pour cette PR :
```
mkdir -p /tmp/pr-<NUMBER>
```
Utiliser ce répertoire pour toutes les captures : /tmp/pr-<NUMBER>/<descriptive-name>.png

Phase 5 : Tests interactifs UI

En fonction des fichiers modifiés de la PR, naviguer vers les pages pertinentes et tester. Utiliser son jugement pour décider ce à tester — la description de la PR et les fichiers modifiés devraient guider la stratégie de test.

Approche générale

Prendre une capture d'écran de l'état actuel
Utiliser agent-browser snapshot -i pour découvrir les éléments interactifs
Interagir avec les éléments (cliquer, remplir, faire glisser, etc.)
Prendre une capture et vérifier le résultat
Vérifier les changements d'état si pertinents (via agent-browser eval)

Points clés de test

L'UI se rend correctement : Les nouveaux composants apparaissent au bon endroit
Les interactions fonctionnent : Bascules, entrées, boutons — tout fonctionne
Persistance d'état : Les modifications survivent aux navigations de page
Compatibilité thème : Tester en modes clair et sombre
Modes de disposition : Si la sidebar/disposition est impliquée, tester à différentes tailles
i18n : Changer la langue et vérifier que les nouvelles chaînes apparaissent correctement
Cas limites : Conditions aux limites, basculement rapide, états vides

Phase 6 : Nettoyage

Après les tests :

Tuer tous les processus Cherry Studio (SIGTERM gracieux d'abord) :

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

Revenir à la branche par défaut :

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

Phase 7 : Rapport de test

Générer un rapport structuré avec captures d'écran. Sauvegarder le rapport sous /tmp/pr-<NUMBER>/report.md aux côtés des captures d'écran.

# 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

Si l'utilisateur le demande, copier le répertoire du rapport vers un emplacement plus accessible (ex. Bureau) pour le partage.

Dépannage

Port 9222 ne reste pas en écoute après le démarrage

Le script pnpm debug passe --remote-debugging-port=9222 à Electron. Si cela ne fonctionne pas :

Vérifier les logs : tail -50 /tmp/cherry-debug.log
Tuer par port : lsof -ti :9222 | xargs kill -9
Vérifier qu'electron-vite s'exécute : ps aux | grep electron-vite

agent-browser connect échoue

Utiliser l'URL websocket directe :

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

La cible agent-browser saute vers la mauvaise page

Les apps Electron ont plusieurs cibles CDP (fenêtre principale + webviews pour mini-apps). Si agent-browser se connecte à une webview au lieu de la page principale :

# Lister toutes les cibles
agent-browser tab
# Basculer vers la page principale (généralement l'onglet 0, l'URL contient localhost:5173)
agent-browser tab 0

Après ouverture/fermeture de mini-apps, toujours vérifier que vous êtes sur la bonne cible avec agent-browser tab.

Assistant de migration V2

Sur la branche v2, l'app peut afficher un assistant de migration des données au premier lancement. Ce n'est pas un bug — c'est attendu quand les données dev n'ont pas encore été migrées. Cliquer à travers les étapes de l'assistant, puis redémarrer l'app manuellement (tuer + relancer). L'assistant n'apparaît qu'une fois ; les lancements suivants vont directement à l'UI principale.

App bloquée sur l'écran de démarrage

Attendre plus longtemps (jusqu'à 30s au premier lancement). L'app doit :

Construire et servir le renderer via le serveur Vite dev (port 5173)
Exécuter les migrations de base de données
Initialiser les services (MCP, etc.)

Liste de cibles CDP vide

Après connexion, si agent-browser tab affiche seulement about:blank :

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

cherry-pr-test