Percy workflow selectivity improvements

.github/workflows/percy-snapshot/action.yml → .github/actions/percy-snapshot/action.yml

@@ -1,6 +1,9 @@
 name: Percy Snapshot
 description: Starts Vanilla local server, captures example snapshots, & uploads them to Percy
 inputs:
+  pr_number:
+    required: false
+    description: Identifier of a pull request to associate with this Percy build. I.E. github.com/{repo}/pull/{pr_number}
   commitsh:
     required: true
     description: SHA signature of commit triggering the build
@@ -81,6 +84,8 @@ runs:
         PERCY_BRANCH: ${{ inputs.branch_name }}
         PERCY_COMMIT: ${{ inputs.commitsh }}
         PERCY_CLIENT_ERROR_LOGS: false
+        # If PR number is set & a Percy-GHA integration is set up, this allows Percy to set status on the PR
+        PERCY_PULL_REQUEST: ${{ inputs.pr_number }}
       run: |
         set -e
         # Start a percy build and capture the stdout

.github/workflows/percy-baseline.yml

@@ -13,7 +13,7 @@ jobs:
       - name: Checkout SCM
         uses: actions/checkout@v4
 
-      - uses: ./.github/workflows/percy-snapshot
+      - uses: ./.github/actions/percy-snapshot
         with:
           branch_name: main
           commitsh: ${{ github.sha }}

.github/workflows/percy-prepare.yml

@@ -0,0 +1,50 @@
+# This workflow is triggered by the `pr-percy-prepare` workflows.
+# It checks out the SCSS/example markup changes and uploads them to Github as an artifact.
+name: "Prepare Percy build"
+
+on:
+  workflow_call:
+    inputs: 
+      pr_number:
+        required: true
+        type: number
+      repository: 
+        required: true
+        type: string
+      commitsh:
+        required: true
+        type: string
+
+jobs:
+  copy_artifact:
+    name: Copy changed files to GHA artifact
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            templates/docs/examples/
+            scss/
+          ref: ${{ github.event.inputs.commitsh }}
+          repository: ${{ github.event.inputs.repository }}
+
+      - name: Populate artifact directory
+        run: |
+          mkdir -p artifact
+          cp -R templates/docs/examples/ scss/ artifact/.
+
+      # Archive the PR number associated with this workflow since it won't be available in the base workflow context
+      # https://github.com/orgs/community/discussions/25220
+      - name: Archive PR data
+        if: github.event_name=='pull_request'
+        working-directory: artifact
+        run: |
+          echo ${{ inputs.pr_number }} > pr_num.txt
+          echo ${{ inputs.commitsh }} > pr_head_sha.txt
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: "percy-testing-web-artifact"
+          path: artifact/*

.github/workflows/pr-percy-prepare-label.yml

@@ -0,0 +1,23 @@
+# This workflow ensures Percy is executed against PRs with the Percy required label, regardless of which paths were changed
+name: "Percy (labeled)"
+
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+        # workflow runs after a label is added to the PR, or when a commit is added to a PR with the Percy label
+      - labeled
+      - synchronize
+
+jobs:
+  copy_artifact:
+    name: Copy changed files to GHA artifact
+    if: contains(github.event.pull_request.labels.*.name, vars.PERCY_TEST_REQUESTED_LABEL_NAME)
+    uses: ./.github/workflows/percy-prepare.yml
+    with:
+      pr_number: ${{ github.event.number }}
+      repository: ${{ github.repository }}
+      commitsh: ${{ github.event.pull_request.head.sha }}
+
+# Completion should trigger `pr-percy-snapshots` workflow.

.github/workflows/pr-percy-prepare-push.yml

@@ -0,0 +1,27 @@
+# This workflow runs Percy against non-draft PRs that have changes in relevant examples filepaths.
+name: "Percy (pushed)"
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "templates/docs/examples/**"
+      - "scss/**"
+    types:
+      - opened
+      - synchronize
+
+jobs:
+  copy_artifact:
+    name: Copy changed files to GHA artifact
+    # Ignore draft PRS and PRs with the Percy label
+    # If we run tests against PRs with the Percy label, we will run tests twice (test is also ran by the labelling workflow)
+    if: ${{ !github.event.pull_request.draft && !contains(github.event.pull_request.labels.*.name, vars.PERCY_TEST_REQUESTED_LABEL_NAME) }}
+    uses: ./.github/workflows/percy-prepare.yml
+    with:
+      pr_number: ${{ github.event.number }}
+      repository: ${{ github.repository }}
+      commitsh: ${{ github.event.pull_request.head.sha }}
+
+# Completion should trigger `pr-percy-snapshots` workflow.

.github/workflows/pr-percy-snapshots.yml

@@ -1,9 +1,11 @@
+# This workflow listens for completion of the `pr-percy-prepare` workflows, picks up their outputs, and performs Percy testing.
 name: "Percy screenshots"
 
 on:
   workflow_run:
     workflows:
-      - "Prepare Percy build"
+      - "Percy (pushed)"
+      - "Percy (labeled)"
     types:
       - completed
 
@@ -14,27 +16,31 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       pr_head_sha: ${{ steps.get_pr_data.outputs.sha }}
+      pr_number: ${{ steps.get_pr_data.outputs.pr_number }}
       percy_build_link: ${{ steps.percy_snapshot.outputs.build_link }}
       percy_org_id: ${{ steps.percy_snapshot.outputs.org_id }}
       percy_build_id: ${{ steps.percy_snapshot.outputs.build_id }}
     steps:
       - name: Checkout SCM
         uses: actions/checkout@v4
 
+      - name: Remove SCM directories that will be replaced by artifact files
+        run: |
+          set -e
+          rm -rf templates/docs/examples/ scss/
+
       - name: Download artifact from workflow run
         uses: actions/download-artifact@v4
         with:
-          name: "web-artifact-${{ github.event.workflow_run.id }}"
+          name: "percy-testing-web-artifact"
           github-token: ${{ secrets.GITHUB_TOKEN }}
           repository: ${{ github.event.workflow_run.repository.full_name }}
           run-id: ${{ github.event.workflow_run.id }}
 
-      - name: Replace SCM files with artifact files
+      - name: Move artifact files into place to replace SCM
         run: |
           set -e
-          rm -rf templates/docs/examples/ scss/
-          tar xzf build.tar.gz
-          rm build.tar.gz
+          # artifact directory contains `scss/`, `/examples`, `pr_num.txt`, and `pr_head_sha.txt`. `/examples` must be moved to `templates/docs/`.
           mv examples/ templates/docs/.
 
       - name: Get PR data
@@ -43,17 +49,19 @@ jobs:
         run: |
           set -e
           echo "sha=$(cat pr_head_sha.txt)" >> $GITHUB_OUTPUT
-          echo "pr=$(cat pr_num.txt)" >> $GITHUB_OUTPUT
+          echo "pr_number=$(cat pr_num.txt)" >> $GITHUB_OUTPUT
 
       - name: Take snapshots & upload to Percy
         id: percy_snapshot
-        uses: './.github/workflows/percy-snapshot'
+        uses: "./.github/actions/percy-snapshot"
         with:
-          branch_name: "pull/${{ steps.get_pr_data.outputs.pr }}"
+          branch_name: "pull/${{ steps.get_pr_data.outputs.pr_number }}"
+          pr_number: ${{ steps.get_pr_data.outputs.pr_number }}
           commitsh: ${{ steps.get_pr_data.outputs.sha }}
           percy_token_write: ${{ secrets.PERCY_TOKEN_WRITE }}
 
   # Add a check to the PR to show that screenshots were sent to Percy
+  # Manual status check to be removed once IS-GHA integration is complete
   # https://docs.github.com/en/rest/checks/runs?apiVersion=2022-11-28#create-a-check-run
   apply_pr_check:
     name: Apply PR check
@@ -65,7 +73,7 @@ jobs:
         id: create_check_run
         uses: octokit/request-action@v2.x
         with:
-          route: POST /repos/${{github.repository}}/check-runs
+          route: POST /repos/${{ github.repository }}/check-runs
           owner: octokit
           repo: request-action
           name: "percy_upload"

guides/pull-requests.md

@@ -78,6 +78,34 @@ apply the relevant `-1` Labels.
 
 ### Submitting & merging a PR
 
+#### Percy visual testing
+
+We use [Percy](https://percy.io) for visual testing. Percy tests are run against pull requests to
+ensure that PRs to not introduce visual regressions. Your PR will be tested by Percy if it meets the following conditions:
+
+- PR is against the `main` branch
+- One of the following is true:
+  - PR passes Percy selectivity filters
+    - PR changes files in the `scss/` or `templates/docs/examples/` directories
+    - PR is not a draft
+  - PR is labeled with "Review: Percy needed"
+
+To ensure optimal Percy usage, we suggest the following PR flow:
+
+1. Open the PR (against `main`) in such a way that it causes an initial Percy test to run.
+   - If your PR makes changes to files in the `scss/` or `templates/docs/examples/` directories, it will be automatically
+     tested as long as it is not marked as a draft.
+   - Applying the "Review: Percy needed" label to the PR ensures that it is always tested.
+2. Review the initial [Percy build](https://percy.io/bb49709b/vanilla-framework).
+3. If there are additional changes needed to the PR through the review process, you can remove the "Review: Percy needed"
+   label and mark the PR as a draft to prevent additional Percy tests from running.
+4. Once the PR is ready for final review, remove the draft status and reapply the "Review: Percy needed" label to trigger
+   a final Percy test.
+5. If the Percy test passes, apply "Review: Percy +1" to indicate that the PR has passed Percy testing.
+6. If all other reviews have been completed, the PR is ready to be merged.
+
+#### Merging a PR
+
 After the necessary review steps have been completed and the PR is ready to be
 merged, the creator of the PR should merge it themself. The type of merge to use
 should be decided using the following logic: