@cryptotaxi247 / SquadScope
Code Commits Issues Pulls Sessions CI/CD
main
main
md 149 lines 4.5 KB
Rendered Raw
1 ---
2 name: "pr-screenshots"
3 description: "Capture Playwright screenshots and embed them in GitHub PR descriptions"
4 domain: "pull-requests, visual-review, docs, testing"
5 confidence: "high"
6 source: "earned (multiple sessions establishing the pattern for PR #11 TypeDoc API reference)"
7 ---
8
9 ## Context
10
11 When a PR includes visual changes (docs sites, UI components, generated pages), reviewers
12 need to see what the PR delivers without checking out the branch. Screenshots belong in
13 the **PR description body**, not as committed files and not as text descriptions.
14
15 Use this skill whenever:
16 - A PR touches docs site pages (Astro, Starlight, etc.)
17 - A PR adds or changes UI components
18 - A PR generates visual artifacts (TypeDoc, Storybook, diagrams)
19 - Playwright tests already capture screenshots as part of testing
20
21 ## Patterns
22
23 ### 1. Capture screenshots with Playwright
24
25 If Playwright tests already exist and produce screenshots, reuse those. Otherwise,
26 write a minimal capture script:
27
28 ```javascript
29 // scripts/capture-pr-screenshots.mjs
30 import { chromium } from 'playwright';
31
32 const browser = await chromium.launch();
33 const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
34
35 const screenshots = [
36 { url: 'http://localhost:4321/path/to/page', name: 'feature-landing' },
37 { url: 'http://localhost:4321/path/to/detail', name: 'feature-detail' },
38 ];
39
40 for (const { url, name } of screenshots) {
41 await page.goto(url, { waitUntil: 'networkidle' });
42 await page.screenshot({ path: `screenshots/${name}.png`, fullPage: false });
43 }
44
45 await browser.close();
46 ```
47
48 ### 2. Host screenshots on a temporary branch
49
50 GitHub PR descriptions render images via URLs. The `gh` CLI cannot upload binary
51 images directly. Use a temporary orphan branch to host the images:
52
53 ```powershell
54 # Save current branch
55 $currentBranch = git branch --show-current
56
57 # Create orphan branch with only screenshot files
58 git checkout --orphan screenshots-temp
59 git reset
60 git add screenshots/*.png
61 git commit -m "screenshots for PR review"
62 git push origin screenshots-temp --force
63
64 # Build raw URLs
65 $base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots"
66 # Each image: $base/{name}.png
67
68 # Return to working branch
69 git checkout -f $currentBranch
70 ```
71
72 ### 3. Embed in PR description
73
74 Use `gh pr edit` with the raw URLs embedded as markdown images:
75
76 ```powershell
77 $base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots"
78
79 gh pr edit {PR_NUMBER} --repo {owner}/{repo} --body @"
80 ## {PR Title}
81
82 ### What this PR delivers
83 - {bullet points of changes}
84
85 ---
86
87 ### Screenshots
88
89 #### {Page/Feature Name}
90 ![{alt text}]($base/{name}.png)
91
92 #### {Another Page}
93 ![{alt text}]($base/{another-name}.png)
94
95 ---
96
97 ### To verify locally
98 ```bash
99 {commands to run locally}
100 ```
101 "@
102 ```
103
104 ### 4. Cleanup after merge
105
106 After the PR is merged, delete the temporary branch:
107
108 ```bash
109 git push origin --delete screenshots-temp
110 ```
111
112 ### 5. Gitignore screenshots locally
113
114 Screenshots are build artifacts — never commit them to feature branches:
115
116 ```gitignore
117 # PR screenshots (hosted on temp branch, not committed to features)
118 screenshots/
119 docs/tests/screenshots/
120 ```
121
122 ## Examples
123
124 ### Example: Docs site PR with 3 pages
125
126 1. Start dev server: `cd docs && npm run dev`
127 2. Run Playwright tests (they capture screenshots as a side effect)
128 3. Push screenshots to `screenshots-temp` branch
129 4. Update PR body with embedded `![...]()` image references
130 5. Reviewer sees the pages inline without checking out the branch
131
132 ### Example: Reusing existing Playwright test screenshots
133
134 If tests at `docs/tests/*.spec.mjs` already save to `docs/tests/screenshots/`:
135
136 ```powershell
137 cd docs && npx playwright test tests/api-reference.spec.mjs
138 # Screenshots now at docs/tests/screenshots/*.png
139 # Push those to screenshots-temp and embed in PR
140 ```
141
142 ## Anti-Patterns
143
144 - ❌ **Committing screenshots to feature branches** — they bloat the repo and go stale
145 - ❌ **Posting text descriptions instead of actual images** — reviewers can't see what they're getting
146 - ❌ **Using `gh` CLI to "upload" images** — `gh issue comment` and `gh pr edit` don't support binary uploads
147 - ❌ **Asking the user to manually drag-drop images** — automate it with the temp branch pattern
148 - ❌ **Skipping screenshots for visual PRs** — if the PR changes what users see, show what users see
149 - ❌ **Leaving the screenshots-temp branch around forever** — clean up after merge