diff --git a/.github/workflows/percy-snapshot/action.yml b/.github/actions/percy-snapshot/action.yml similarity index 92% rename from .github/workflows/percy-snapshot/action.yml rename to .github/actions/percy-snapshot/action.yml index ea4ff4abf..61e813ceb 100644 --- a/.github/workflows/percy-snapshot/action.yml +++ b/.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 diff --git a/.github/workflows/percy-baseline.yml b/.github/workflows/percy-baseline.yml index bc7c1a9ca..5ef6b4611 100644 --- a/.github/workflows/percy-baseline.yml +++ b/.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 }} diff --git a/.github/workflows/percy-prepare.yml b/.github/workflows/percy-prepare.yml new file mode 100644 index 000000000..7b72ffe37 --- /dev/null +++ b/.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/* \ No newline at end of file diff --git a/.github/workflows/pr-percy-prepare-label.yml b/.github/workflows/pr-percy-prepare-label.yml new file mode 100644 index 000000000..7f6a87d5d --- /dev/null +++ b/.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. diff --git a/.github/workflows/pr-percy-prepare-push.yml b/.github/workflows/pr-percy-prepare-push.yml new file mode 100644 index 000000000..0fc6f5f73 --- /dev/null +++ b/.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. diff --git a/.github/workflows/pr-percy-prepare.yml b/.github/workflows/pr-percy-prepare.yml deleted file mode 100644 index f00cc0931..000000000 --- a/.github/workflows/pr-percy-prepare.yml +++ /dev/null @@ -1,42 +0,0 @@ -name: "Prepare Percy build" - -on: - pull_request: - branches: - - main - -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/ - - - name: Make artifact directory - run: mkdir -p 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 ${{ github.event.number }} > pr_num.txt - echo ${{ github.event.pull_request.head.sha }} > pr_head_sha.txt - - - name: Compress artifact - working-directory: artifact - run: | - cp -R ../templates/docs/examples/ ../scss/ . - tar -czf build.tar.gz * - - - name: Upload artifact - uses: actions/upload-artifact@v4 - with: - name: "web-artifact-${{ github.run_id }}" - path: artifact/build.tar.gz \ No newline at end of file diff --git a/.github/workflows/pr-percy-snapshots.yml b/.github/workflows/pr-percy-snapshots.yml index aef7c93b2..6cadda20e 100644 --- a/.github/workflows/pr-percy-snapshots.yml +++ b/.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,6 +16,7 @@ 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 }} @@ -21,20 +24,23 @@ jobs: - 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" diff --git a/guides/pull-requests.md b/guides/pull-requests.md index 449438e02..a7552bbe5 100644 --- a/guides/pull-requests.md +++ b/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: