--- name: dyad:pr-screencast description: Record a visual demonstration of the key feature of this PR using screenshots and add it as a new comment to the PR. --- # PR Screencast Record a visual demonstration of the key feature of this PR using screenshots and add it as a new comment to the PR. **IMPORTANT:** This skill should complete all steps autonomously where possible. Permission prompts from Claude Code for file writes, bash commands, or GitHub operations should be accepted as normal — do not treat them as blockers. ## Arguments - `$ARGUMENTS`: (Optional) PR number or URL. If not provided, will use the PR associated with the current branch. ## Task Tracking **You MUST use the TodoWrite tool to track your progress.** At the start, create tasks for each step below. Mark each task as `in_progress` when you start it and `completed` when you finish. This ensures you complete ALL steps. ## Instructions 1. **Determine the PR:** If `$ARGUMENTS` is provided, use it as the PR number or URL. Otherwise, get the PR for the current branch: ``` gh pr view --json number,title,body,files,headRefOid -q '.number' ``` If no PR exists for the current branch, report an error and stop. 2. **Analyze if this PR is user-facing:** Fetch the PR details including changed files: ``` gh pr view --json title,body,files,labels ``` **Skip recording if the PR is NOT user-facing.** A PR is NOT user-facing if: - It only changes documentation files (`*.md`, `*.txt`, `*.rst`) - It only changes configuration files (`*.json`, `*.yaml`, `*.yml`, `*.toml`, `*.config.*`) - It only changes test files (`*test*`, `*spec*`, `*tests*`) - It only changes CI/CD files (`.github/*`, `.circleci/*`, etc.) - It only changes type definitions (\*.d.ts) - It has labels like "refactor", "chore", "docs", "ci", "internal", "dependencies" - The title/body indicates it's a refactoring, internal change, or non-user-facing work If the PR is not user-facing, post a brief comment explaining why the screencast was skipped: ``` gh pr comment --body "$(cat <<'EOF' ## Screencast Skipped This PR appears to be a non-user-facing change (refactoring, documentation, tests, or internal changes), so no screencast was recorded. --- *Automated by `/dyad:pr-screencast`* EOF )" ``` Then stop. 3. **Identify the key feature to demonstrate:** Analyze the PR to understand: - What UI component or feature was added/changed? - What user action triggers the feature? - What is the expected visual outcome? Read the changed files to understand: - Which components are affected - What user interactions are involved - What visual changes should be demonstrated Formulate a plan for what the screencast should show: - Starting state (screenshot 1) - User actions to perform - Result state (screenshot 2-3) 4. **Create a Playwright screencast script:** Create a new file at `e2e-tests/screencast-demo.spec.ts` that takes multiple screenshots to tell the visual story: ```typescript import { expect } from "@playwright/test"; import { test } from "./helpers/fixtures"; import * as fs from "fs"; import * as path from "path"; test.describe.configure({ mode: "serial" }); test("PR Demo Screencast", async ({ electronApp, po }) => { // Ensure screenshots directory exists const screenshotDir = path.join(__dirname, "screencast-screenshots"); if (!fs.existsSync(screenshotDir)) { fs.mkdirSync(screenshotDir, { recursive: true }); } const page = await electronApp.firstWindow(); // Set up the app for demo await po.setUp({ autoApprove: true }); // Import or create a test app if needed await po.importApp("minimal"); // Wait for app to be ready await page.waitForTimeout(1000); // === STEP 1: Capture initial state === await page.screenshot({ path: path.join(screenshotDir, "01-initial-state.png"), fullPage: false, }); // === STEP 2: Navigate to the feature / perform action === // TODO: Replace with actual navigation/interaction for this PR // Example: await po.goToSettingsTab(); await page.waitForTimeout(500); await page.screenshot({ path: path.join(screenshotDir, "02-during-action.png"), fullPage: false, }); // === STEP 3: Show the result === // TODO: Replace with actual result state await page.waitForTimeout(500); await page.screenshot({ path: path.join(screenshotDir, "03-final-result.png"), fullPage: false, }); // Verify the final screenshot exists to ensure all steps completed expect( fs.existsSync(path.join(screenshotDir, "03-final-result.png")), ).toBe(true); }); ``` **Customize the script based on the feature being demonstrated:** - Use the PageObject methods from `e2e-tests/helpers/page-objects/PageObject.ts` - Use stable selectors (data-testid, role, text) - Add appropriate waits between actions (500-1000ms) so screenshots are clear - Capture 2-4 screenshots showing the progression of the feature 5. **Build the app:** The app must be built before recording: ``` npm run build ``` 6. **Run the screencast test:** Run the test to capture screenshots: ``` PLAYWRIGHT_HTML_OPEN=never npx playwright test e2e-tests/screencast-demo.spec.ts --timeout=120000 --reporter=list ``` If the test fails, read the error output, fix the script, and try again (up to 3 attempts). If the test still fails after 3 attempts, post a comment on the PR indicating the screencast could not be captured and report the error. Common issues: - Missing selectors - check the component implementation - Timing issues - add more `waitForTimeout` calls - Import app issues - try a different test app or create from scratch 7. **Verify screenshots were captured:** Check that the screenshots exist: ``` ls -la e2e-tests/screencast-screenshots/ ``` You should see 2-4 PNG files. If not, check the test output for errors. 8. **Upload screenshots to GitHub:** Upload screenshots to an `assets` branch so they can be referenced in PR comments. ```bash # Get repo info REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner') TIMESTAMP=$(date +%Y%m%d-%H%M%S) ASSET_DIR="pr-screencasts/pr--$TIMESTAMP" # Create or update the assets branch git fetch origin assets:assets 2>/dev/null || git checkout --orphan assets # Switch to assets branch, preserving working directory git stash --include-untracked git checkout assets 2>/dev/null || (git checkout --orphan assets && git rm -rf . 2>/dev/null || true) # Create directory and copy screenshots mkdir -p "$ASSET_DIR" git stash pop 2>/dev/null || true cp e2e-tests/screencast-screenshots/*.png "$ASSET_DIR/" # Commit and push git add "$ASSET_DIR" git commit -m "Add screencast assets for PR #" git push origin assets # Switch back to original branch git checkout - git stash pop 2>/dev/null || true ``` The screenshots will be accessible at: ``` https://raw.githubusercontent.com//assets//.png ``` **Fallback: Use text description if upload fails:** If uploads don't work, describe the screenshots in text format. 9. **Post the comment to the PR:** Create the PR comment with the demonstration: ``` gh pr comment --body "$(cat <<'EOF' ## Feature Demo ### What this PR does ### Visual Walkthrough **Step 1: Initial State** **Step 2: User Action** **Step 3: Result** ### How to Test Manually 1. 2. --- *Automated by `/dyad:pr-screencast`* EOF )" ``` **IMPORTANT:** Do NOT use `--edit-last` or modify existing comments. Always create a NEW comment. 10. **Clean up the Playwright script and assets:** Delete the temporary screencast script and screenshots: ``` rm -f e2e-tests/screencast-demo.spec.ts rm -rf e2e-tests/screencast-screenshots/ ``` Also clean up any test results: ``` rm -rf test-results/screencast-demo* ``` 11. **Summarize results:** Report to the user: - Whether the PR was determined to be user-facing or not - What feature was demonstrated (if applicable) - How many screenshots were captured - Link to the PR comment - Any issues encountered during recording