SWC-6624: update documentation and add script for downloading reports…

… in forked repos

e2e_workflow/README.md

@@ -30,26 +30,40 @@ Notes:
 
 ### CI
 
+Playwright reports are configured and saved differently based on where the e2e workflow runs. In forked repos, reports are saved as GitHub artifacts, which are publically accessible in public repositories. Since traces can include credentials for the backend dev stack, these reports do not include traces. In the `Sage-Bionetworks`-owned repo, Playwright reports are saved to a private S3 bucket so the reports can include traces.
+
 #### Forked Repositories
 
-In your forked repository, ensure that [Actions are enabled](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository), then create [an Actions secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) for `ADMIN_PAT`. The tests will run on each push to your forked repository.
+In your forked repository, ensure that [Actions are enabled](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository), then create [an Actions secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) for `ADMIN_PAT`. The tests will run on each push to your forked repository. The Playwright report will be saved as a GitHub Artifact.
+
+The GitHub UI or CLI can be used to view the reports:
+
+- GitHub UI
+  - Navigate to the Action run summary page.
+  - Download the report named "html-report--atttempt-{number}". _Note:_ only the report from the latest attempt will be available.
+  - Unzip the file and move the "index.html" file into the `playwright-report` directory in SWC.
+  - Run `yarn e2e:report` to view the HTML report in the browser.
+- GitHub CLI
+  - Install [GitHub CLI](https://cli.github.com/), if necessary.
+  - [Authenticate](https://cli.github.com/manual/gh_auth_login) with a GitHub host, if necessary.
+  - Run `e2e_workflow/view_github_report.sh` with the following arguments: GitHub repo owner name and the GitHub run ID of the report to view. The HTML report will open in the browser.
 
 #### Sage Repository
 
-In the Sage-Bionetworks repository, the tests will run on push to `develop` and `release-**` branches. The Playwright blob report from each shard will be saved in the `s3://e2e-reports-bucket-bucket-1p1qz6p48t4uy` S3 bucket. Each report will be named as `report-{ shard-number }.zip` and be located within a subdirectory named `SynapseWebClient-${ github-run-id }-${ run-attempt-number }`.
+In the `Sage-Bionetworks`-owned repository, the tests will run on push to `develop` and `release-**` branches. The Playwright blob report from each shard will be saved in the `s3://e2e-reports-bucket-bucket-1p1qz6p48t4uy` S3 bucket. Each report will be named as `report-{ shard-number }.zip` and be located within a subdirectory named `SynapseWebClient-${ github-run-id }-${ run-attempt-number }`.
 
-The bucket is accessible using the `org-sagebase-synapsedev` account. The AWS console or CLI can be used to view the reports:
+The AWS console or CLI can be used to view the reports:
 
 - AWS console
+  - Authenticate with AWS console SSO with the `org-sagebase-synapsedev` account.
+  - Navigate to the S3 bucket: `s3://e2e-reports-bucket-bucket-1p1qz6p48t4uy`
   - Download the shard reports locally.
   - Move the files into the `blob-report` directory in SWC.
   - Run `yarn e2e:report:blob` to merge the shard reports and open the resulting HTML report in the browser.
 - AWS CLI
   - Install [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), if necessary.
-  - Configure access credentials for AWS CLI SSO.
-  - Run `e2e_workflow/view_s3_report.sh` with the following arguments: AWS SSO profile name, the GitHub run ID of the report to view, and optionally, the run attempt number.
-
-_Note_: reports are saved to S3 so reports can include traces, which can contain credentials for the backend dev stack. Reports including traces can't be saved as GitHub artifacts, since artifacts in public repositories are publically accessible.
+  - Configure access credentials for AWS CLI SSO with the `org-sagebase-synapsedev` account.
+  - Run `e2e_workflow/view_s3_report.sh` with the following arguments: AWS SSO profile name, the GitHub run ID of the report to view, and optionally, the run attempt number. The HTML report will open in the browser.
 
 ## Writing Tests
 

e2e_workflow/view_github_report.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+
+# View Playwright report stored in GitHub
+#   ./view_github_report.sh [github-repo-owner] [github-run-id]
+#  
+
+# Abort script on errors and unbound variables
+# https://bertvv.github.io/cheat-sheets/Bash.html
+set -o errexit   # abort on nonzero exitstatus
+set -o nounset   # abort on unbound variable
+set -o pipefail  # don't hide errors within pipes
+
+# Set variables
+SCRIPT_PATH="$(cd "$(dirname "${0}")"; echo $(pwd))"
+REPO_PATH="$(dirname ${SCRIPT_PATH})"
+REPO_NAME="$(basename ${REPO_PATH})"
+BLOB_DIR="${REPO_PATH}/blob-report/"
+REPORT_DIR="${REPO_PATH}/playwright-report/"
+
+# Get parameters from user
+if [ "$#" -lt 2 ]; then
+  echo "Usage: $0 [github-repo-owner] [github-run-id]"
+  echo "* github-repo-owner: GitHub repo owner"
+  echo "* github-run-id: GitHub Run ID of report to view"
+  exit
+fi
+REPO_OWNER="${1}"
+RUN_ID="${2}"
+
+# Delete previous report files
+for file in $(find "${BLOB_DIR}" -type f) $(find "${REPORT_DIR}" -type f); do 
+  [ -f "${file}" ] && echo "delete: ${file}" && rm "${file}"
+done
+
+# Get workflow artifact id and name
+ARTIFACT=$(gh api \
+  -H "Accept: application/vnd.github+json" \
+  -H "X-GitHub-Api-Version: 2022-11-28" \
+  "/repos/${REPO_OWNER}/${REPO_NAME}/actions/runs/${RUN_ID}/artifacts" \
+  | jq '.artifacts[] | select(.name | contains("html-report")) | {id, name}')
+ARTIFACT_ID=$(echo "${ARTIFACT}" | jq '.id')
+ARTIFACT_NAME=$(echo "${ARTIFACT}" | jq -r '.name')
+
+# Download workflow artifact
+ARTIFACT_ENDPOINT="/repos/${REPO_OWNER}/${REPO_NAME}/actions/artifacts/${ARTIFACT_ID}/zip"
+ARTIFACT_ZIP="${BLOB_DIR}/${ARTIFACT_NAME}.zip"
+echo "download: ${ARTIFACT_ENDPOINT} to ${ARTIFACT_ZIP}"
+gh api \
+  -H "Accept: application/vnd.github+json" \
+  -H "X-GitHub-Api-Version: 2022-11-28" \
+  "${ARTIFACT_ENDPOINT}" > "${ARTIFACT_ZIP}"
+
+# Unzip file
+unzip "${ARTIFACT_ZIP}" -d "${REPORT_DIR}"
+
+# Show report
+yarn e2e:report

e2e_workflow/view_s3_report.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
-#   View Playwright report stored in S3
-#     ./view_s3_report.sh [aws-sso-profile-name] [github-run-id] [optional-run-attempt-number]
+
+# View Playwright report stored in S3
+#   ./view_s3_report.sh [aws-sso-profile-name] [github-run-id] [optional-run-attempt-number]
 #
 
 # Abort script on errors and unbound variables