workstream-labs/workstreams/update-screenshots

Update Component Screenshots from CI

When asked to update, accept, or refresh screenshot baselines from CI — or when the Screenshot Tests GitHub Action has failed with screenshot differences — follow this procedure to download the CI-generated screenshots and commit them as the new baselines.

Why CI Screenshots?

Screenshots captured locally may differ from CI due to platform differences (fonts, rendering, DPI). The CI (Linux, ubuntu-latest) is the source of truth. This skill downloads the CI-produced screenshots and commits them as baselines.

Prerequisites

• The gh CLI must be authenticated (gh auth status).
• The Screenshot Tests GitHub Action must have run and produced a screenshot-diff artifact.

Procedure

1. Find the latest screenshot artifact

If the user provides a specific run ID or PR number, use that. Otherwise, find the latest run:

# For a specific PR:
gh run list --workflow screenshot-test.yml --branch <branch> --limit 5 --json databaseId,status,conclusion,headBranch
 
# For the current branch:
gh run list --workflow screenshot-test.yml --branch $(git branch --show-current) --limit 5 --json databaseId,status,conclusion

Pick the most recent run that has a screenshot-diff artifact (runs where screenshots matched won't have one).

2. Download the artifact

gh run download <run-id> --name screenshot-diff --dir .tmp/screenshot-diff

The artifact is uploaded from two paths (test/componentFixtures/.screenshots/current/ and test/componentFixtures/.screenshots/report/), but GitHub Actions strips the common prefix. So the downloaded structure is:

• current/ — the CI-captured screenshots (e.g. current/baseUI/Buttons/Dark.png)
• report/report.json — structured diff report
• report/report.md — human-readable diff report

3. Review the changes

Show the user what changed by reading the markdown report:

cat .tmp/screenshot-diff/report/report.md

4. Copy CI screenshots to baseline

# Remove old baselines and replace with CI screenshots
rm -rf test/componentFixtures/.screenshots/baseline/
cp -r .tmp/screenshot-diff/current/ test/componentFixtures/.screenshots/baseline/

5. Clean up

rm -rf .tmp/screenshot-diff

6. Stage and commit

git add test/componentFixtures/.screenshots/baseline/
git commit -m "update screenshot baselines from CI"

7. Push LFS objects before pushing

Screenshot baselines are stored in Git LFS. The git lfs pre-push hook is not active in this repo (husky overwrites it), so LFS objects are NOT automatically uploaded on git push. You must push them manually before pushing the branch, otherwise the push will fail with GH008: Your push referenced unknown Git LFS objects.

git lfs push --all origin <branch-name>
git push

8. Verify

Confirm the baselines are updated by listing the files:

git diff --stat HEAD~1

Notes

• If no screenshot-diff artifact exists, the screenshots already match the baselines — no update needed.
• The --filter option on the CLI can be used to selectively accept only some fixtures if needed.
• After committing updated baselines, the next CI run should pass the screenshot comparison.