taking-screenshots

Taking Screenshots & Screen Recordings

Rules for capturing UI screenshots (Playwright MCP) and screen recordings (video-recorder MCP) for PR demos.

---

1. Screenshot Location

Save all screenshots to the user's Downloads directory under a ticket-keyed folder:

~/Downloads/{TICKET_KEY}/
  MTV-XXXX-1-description.png
  MTV-XXXX-2-description.png
  ...

Create the directory if it doesn't exist. Never save screenshots to the project directory.

PR Image Upload

Use the gh attach CLI extension to upload images for PR descriptions:

# Upload and get the URL
gh attach upload ~/Downloads/{TICKET_KEY}/image.png \
  --target kubev2v/forklift-console-plugin#<PR_NUMBER> \
  --strategy release-asset \
  --format url

This produces a GitHub-hosted URL that renders inline in markdown. Use the returned URL in the PR body as ![description](URL).

Images are stored as release assets under the _gh-attach-assets tag on the target repo. The release-asset strategy works with gh auth token -- no browser session needed.

---

2. File Naming

Format: {TICKET_KEY}-{index}-{short-description}.png

• Use the ticket key (e.g., MTV-2482)
• Append an incrementing index starting at 1
• Add a brief kebab-case description of what the screenshot shows
• Example: MTV-2482-1-plan-details-header.png, MTV-2482-2-inspect-modal.png

---

3. Browser Setup

Before taking screenshots:

• Resize the browser: browser_resize -> { width: 1920, height: 1080 }
• Wait for the page to fully load before capturing
• If the target element is below the fold, scroll to it or use fullPage: true
• The 1920x1080 viewport matches a standard monitor; the sidebar uses ~250px leaving ~1670px for content. This is acceptable -- do NOT use larger viewports

---

4. Ticket-Driven Testing

Before taking any screenshots, re-read the Jira ticket. The screenshots must prove the fix works according to the ticket, not just show UI components exist.

Preparation

1. Read the ticket's Steps to Reproduce, Actual Results, and Expected Results.
2. Plan screenshots that demonstrate the transition from actual to expected.
3. Follow the ticket's user flow, not the code change list.