Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

docs(cli): add pull request attachment guide to the cli skill (#42645)

Pavel Feldman575442d5a763
diff --git a/packages/playwright-core/src/tools/skills/playwright-cli/SKILL.md b/packages/playwright-core/src/tools/skills/playwright-cli/SKILL.md
index b7c883842d..a9aa086406 100644
--- a/packages/playwright-core/src/tools/skills/playwright-cli/SKILL.md
+++ b/packages/playwright-core/src/tools/skills/playwright-cli/SKILL.md
@@ -412,6 +412,17 @@ playwright-cli open https://example.com
playwright-cli show --annotate
```
+## Attaching screenshots and videos to pull requests
+
+`gh` 2.99+ uploads local images and videos with the repeatable `--attach` flag on `gh pr create`, `gh pr comment` and `gh issue comment`. Attach a screenshot or a short video when it saves the reviewer a checkout: a UI fix, a before/after pair, a new user-facing flow, or the failure state in a bug report.
+
+```bash
+playwright-cli screenshot --filename=settings-after.png
+gh pr comment 123 --body "Settings page after the fix." --attach ./settings-after.png
+```
+
+See [references/pr-attachments.md](references/pr-attachments.md) for alt text, inline references, size limits and attaching test artifacts from CI.
+
## Specific tasks
* **Running and Debugging Playwright tests** [references/playwright-tests.md](references/playwright-tests.md)
@@ -422,4 +433,5 @@ playwright-cli show --annotate
* **Test generation (plan / generate / heal)** [references/test-generation.md](references/test-generation.md)
* **Tracing** [references/tracing.md](references/tracing.md)
* **Video recording** [references/video-recording.md](references/video-recording.md)
+* **Attaching screenshots and videos to pull requests** [references/pr-attachments.md](references/pr-attachments.md)
* **Inspecting element attributes** [references/element-attributes.md](references/element-attributes.md)
diff --git a/packages/playwright-core/src/tools/skills/playwright-cli/references/pr-attachments.md b/packages/playwright-core/src/tools/skills/playwright-cli/references/pr-attachments.md
new file mode 100644
index 0000000000..91663b58bc
--- /dev/null
+++ b/packages/playwright-core/src/tools/skills/playwright-cli/references/pr-attachments.md
@@ -0,0 +1,60 @@
+# Attaching Screenshots and Videos to Pull Requests
+
+`gh` 2.99+ uploads local images and videos with the repeatable `--attach` flag on `gh pr create`, `gh pr comment`, `gh pr edit`, `gh issue create`, `gh issue comment` and `gh issue edit`. PNG, JPEG, GIF, WebP, SVG, MP4, MOV and WebM are accepted, so `playwright-cli screenshot` and `video-start` output can be attached as is.
+
+## When to attach
+
+Attach visual evidence when it saves the reviewer a checkout: a screenshot of a UI fix, a before/after pair, a short video of a new user-facing flow, or the failure state when filing a bug. Skip it for refactors, backend-only changes and anything the diff already shows.
+
+## From a local session
+
+```bash
+# capture the evidence
+playwright-cli open http://localhost:3000/settings
+playwright-cli screenshot --filename=settings-after.png
+playwright-cli video-start settings-flow.webm
+playwright-cli click e5
+playwright-cli fill e7 "New name" --submit
+playwright-cli video-stop
+
+# attach when creating the PR; alt text goes after "#" (images only)
+gh pr create --title "fix(settings): keep name after save" --body-file body.md \
+ --attach './settings-after.png#Settings page after saving' --attach ./settings-flow.webm
+
+# or comment on an existing PR / issue
+gh pr comment 123 --body "Recorded the new flow end to end." --attach ./settings-flow.webm
+gh issue comment 456 --body "Failure state after submitting the form." --attach ./failure.png
+```
+
+Reference the file in the body as `![alt](./settings-after.png)` to place it inline and `gh` rewrites the path to the uploaded URL. Unreferenced attachments are appended at the end in flag order.
+
+## Limits
+
+- Images up to 10 MB, videos up to 10 MB on free plans and 100 MB on paid plans, so keep recordings short.
+- Alt text is not supported on videos.
+- Uploads need push access to the repository.
+- Available on GitHub.com and GitHub Enterprise Cloud only.
+
+## From CI
+
+Attach the screenshots and videos Playwright Test already saves under `test-results` (`screenshot: 'only-on-failure'`, `video: 'retain-on-failure'`) with the same command:
+
+```yaml
+permissions:
+ pull-requests: write
+steps:
+ - run: npx playwright test
+ - name: Attach failure screenshots and videos to the PR
+ if: failure() && github.event_name == 'pull_request'
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ files=$(find test-results -name '*.png' -o -name '*.webm' | head -20)
+ if [ -n "$files" ]; then
+ gh pr comment ${{ github.event.pull_request.number }} \
+ --body "Failure screenshots and videos from run ${{ github.run_id }}." \
+ $(printf -- '--attach %s ' $files)
+ fi
+```
+
+For a polished walkthrough of a new feature, record a hero script as described in [video-recording.md](video-recording.md) and attach the resulting WebM the same way.
diff --git a/packages/playwright-core/src/tools/skills/playwright-cli/references/video-recording.md b/packages/playwright-core/src/tools/skills/playwright-cli/references/video-recording.md
index 5209d21ee0..aae2f9b43b 100644
--- a/packages/playwright-core/src/tools/skills/playwright-cli/references/video-recording.md
+++ b/packages/playwright-core/src/tools/skills/playwright-cli/references/video-recording.md
@@ -128,6 +128,18 @@ Embrace creativity, overlays are powerful.
| `disposable.dispose()` | Remove a sticky overlay added without duration |
| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()` | Temporarily hide/show all overlays |
+### 3. Attach the recording to the pull request
+
+A hero script recording is the best proof of work for a user-facing change. GitHub accepts WebM as is, so once the recording looks right, attach it with `gh` 2.99+ instead of describing the flow in words:
+
+```bash
+gh pr create --title "feat(todo): add items inline" --body-file body.md --attach ./demo.webm
+gh pr comment 123 --body "Walkthrough of the new flow." --attach ./demo.webm
+gh issue comment 456 --body "Recording of the repro steps." --attach ./repro.webm
+```
+
+`gh` appends unreferenced attachments to the end of the body, which is the right place for a walkthrough. Videos are limited to 10 MB on free plans and 100 MB on paid plans, so keep the script focused, record at a modest size such as 1280x800 and drop chapters that do not add to the story. See [pr-attachments.md](pr-attachments.md) for the full set of commands, including attaching test artifacts from CI.
+
## Tracing vs Video
| Feature | Video | Tracing |