# PR Testing

Use this workflow for a bounded PR test within `cherry-electron-dev`. For
ongoing implementation or debugging, follow the skill's development loop.

## Prerequisites and safety

- Require authenticated `gh`, `pnpm`, and installed project dependencies.
- Use Playwright/CDP or optional `agent-browser` for UI control.
- Before touching Electron, read
  [Electron Instance Management](electron-instance.md)
  and select its `ephemeral` policy.
- Treat that reference as the only authority for discovery, target selection,
  launch, replacement, shutdown, tracking, and troubleshooting.
- Never discard local changes. Stop and ask if checkout would overwrite them.
- Show the report before posting it anywhere.

`$ARGUMENTS` may contain a PR number, PR URL, `latest`/`recent`, or nothing.

## Workflow

### 1. Resolve and inspect the PR

If no PR is specified, list recent PRs and ask the user to choose unless they
requested the latest:

```bash
gh pr list --repo CherryHQ/cherry-studio --state open --limit 10 \
  --json number,title,author,createdAt,headRefName,changedFiles
```

Record the current branch for restoration, inspect the PR, then check it out:

```bash
git status --short
git branch --show-current
gh pr view <NUMBER> --json title,body,author,headRefName,headRefOid,files
gh pr checkout <NUMBER>
```

Read the changed files and nearby instructions. Record the exact checked-out
HEAD and verify it matches the resolved PR head.

### 2. Analyze and start the app

Run static analysis while the app starts when both can proceed independently.

Inspect existing CI results with `gh pr checks <NUMBER>`. Follow current
repository instructions for local validation: use explicit affected test file
paths when needed, and do not default to full lint, test, or typecheck suites.
Record which checks ran locally, which ran in CI, and any coverage gaps.

Read the changed code and check:

- blocked or deprecated v1/v2-refactor files
- hardcoded user-visible strings instead of i18n
- `console.log` instead of `loggerService`
- missing types on new public interfaces

For Electron:

1. Use the shared reference to verify existing instances.
2. Reuse only an instance from this workspace whose recorded launch HEAD equals
   the checked-out PR HEAD.
3. When reusing one, mark it borrowed and preserve its existing policy and
   ownership. Never reclassify a persistent instance as ephemeral.
4. Otherwise gracefully replace only the verified same-workspace instance.
5. Launch an `ephemeral`, agent-owned instance with an isolated
   `CS_DEV_USER_DATA_SUFFIX`, such as `PR-<NUMBER>`.
6. Keep its managed terminal/session, PIDs, ports, log, exact target, and
   `pr-test:<NUMBER>` launch purpose in
   `instance.json`.

Do not use broad process or port cleanup.

### 3. Run interactive tests

Bind the controller to the exact target returned by the shared reference.
Never navigate to a guessed root URL or select a target by index.

Build test cases from the PR description and changed files:

1. Capture the initial state.
2. Inspect interactive elements with the available CDP controller.
3. Exercise the changed behavior.
4. Capture the result and verify relevant persisted state.
5. Repeat edge cases justified by the change.

Consider UI rendering, interactions, persistence, light/dark themes, relevant
window sizes, i18n, empty states, and rapid interaction only when in scope.

Store screenshots and the report under `.context/cherry-electron-dev/pr-<NUMBER>/`:

```bash
mkdir -p .context/cherry-electron-dev/pr-<NUMBER>
```

If an isolated profile shows the migration wizard or splash, follow the shared
troubleshooting guidance and startup logs. Do not reset or force-close data.

### 4. Clean up and restore

Perform cleanup and restoration even if testing fails or is blocked, and
report any incomplete cleanup or restoration.

Use the shared `ephemeral` finish procedure. Stop only an instance launched by
this PR-test workflow whose verified record remains `ephemeral`, agent-owned,
and scoped to `pr-test:<NUMBER>`. Leave every borrowed instance running. Do not
stop unrelated workspaces or packaged apps.

Restore the branch recorded before checkout. If it no longer exists, resolve
the repository default branch and report the fallback before switching:

```bash
git checkout <ORIGINAL_BRANCH>
```

### 5. Report

Save `.context/cherry-electron-dev/pr-<NUMBER>/report.md` and show it to the user.
Match the report language to the user's language; the template uses English labels:

```markdown
# PR #<NUMBER> Test Report

**Title**: <title>
**Author**: @<author>
**Branch**: <branch>
**Tested HEAD**: <commit SHA>
**Changed files**: <count>

## Static Analysis

| Check | Result | Notes |
| --- | --- | --- |
| CI checks | ✅/❌/pending | ... |
| Local checks | ✅/❌/not run | <exact commands and scope> |
| Blocked-file check | ✅/⚠️ | ... |
| Logging, i18n, and types | ✅/❌ | ... |

## UI Tests

### <Test Case>

<scenario, evidence, and result>

![screenshot](<filename>.png)

## Findings

<findings or none>

## Runtime and Cleanup

<verified PID, CDP port, tracking file, evidence paths, whether the instance
was started or borrowed, final process state, and restored branch>

## Conclusion

- Total findings: N
- Recommendation: APPROVE / REQUEST_CHANGES / COMMENT
```

Do not post the report or submit a GitHub review unless the user explicitly
asks.