From 0fe396d4777c8c6022b7898b5b899b7ee1e1c484 Mon Sep 17 00:00:00 2001 From: Jayasanka Date: Tue, 24 Oct 2023 18:47:51 -0700 Subject: [PATCH] Add documentation --- .github/workflows/e2e-on-release.yml | 2 +- e2e_test_support_files/README.md | 64 ++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+), 1 deletion(-) create mode 100644 e2e_test_support_files/README.md diff --git a/.github/workflows/e2e-on-release.yml b/.github/workflows/e2e-on-release.yml index 9c4acd727..aced8cc97 100644 --- a/.github/workflows/e2e-on-release.yml +++ b/.github/workflows/e2e-on-release.yml @@ -1,4 +1,4 @@ -name: Run on release +name: Run E2E Tests on Release PRs on: pull_request: diff --git a/e2e_test_support_files/README.md b/e2e_test_support_files/README.md new file mode 100644 index 000000000..8a421b7d1 --- /dev/null +++ b/e2e_test_support_files/README.md @@ -0,0 +1,64 @@ +# Run E2E Tests on Release PRs + +This GitHub Actions workflow, named "Run E2E Tests on Release PRs," serves as Quality Gate #4 in the slide +deck [O3 Release QA pipeline](https://docs.google.com/presentation/d/1k3DH74Mz1Afnrgy2MpwR5HQK5vMpVx0pTfN1na62lvI/edit#slide=id.g165af5ac0be_0_24). + +The workflow is designed to automate the end-to-end (E2E) testing process for release pull requests (PRs) +that opened in the format described in +here: [How to Release the O3 RefApp](https://wiki.openmrs.org/display/projects/How+to+Release+the+O3+RefApp) + +The workflow is conditional and **only runs if the pull request title starts with "(release)"**. + +Below is an overview of the key components of the workflow: + + +## Job: build + +This job prepares the test environment, extracts version numbers, builds and runs Docker containers, and uploads +artifacts for use in subsequent E2E testing jobs. + +### Checking out to the release commit + +The reason for the step: + +```yaml +- name: Checkout to the release commit + run: | + release_commit_sha=$(git log --oneline | awk 'NR==3 {print $1}') + git checkout $release_commit_sha +``` + +is to ensure that the workflow checks out to the specific release commit associated with the pull request. This is +necessary because the pull request contain both release commits and revert commits, and the goal is to specifically +target the release commit for further processing. + +Here's an explanation of what this step does: + +1. It uses `git log --oneline` to retrieve a list of recent commits in the repository. +2. The `awk 'NR==3 {print $1}'` part is used to extract the SHA hash of the third most recent commit, which is the + release commit we want to target. This is done by specifying `NR==3`, which means selecting the third line (commit) + in the log. + The reason to use the 3rd commit instead of 2nd is that a GitHub Action workflow operates within a context where + there's an additional merge commit on the head of the pull request. +3. Finally, the workflow checks out to this release commit by using git checkout $release_commit_sha. + +By checking out to the specific release commit, it ensures that the subsequent steps of the workflow are based on the +state of the code associated with the release, and not on the revert commit present in the pull request. + +## End-to-End Test Jobs + +The workflow includes several end-to-end test jobs, each corresponding to a specific components of O3 (frontend +mono-repos). These jobs are structured similarly and are listed below: + +* `run-patient-management-e2e-tests` +* `run-patient-chart-e2e-tests` +* `run-form-builder-e2e-tests` +* `run-esm-core-e2e-tests` +* `run-cohort-builder-e2e-tests` + +In each "End-to-End Test Job," the workflow first checks out the repository associated with a specific OpenMRS +component. It then downloads Docker images from a previous "build" job, loads these images, and starts an OpenMRS instance. + +The workflow checks out a specific tagged version of the component's repository, the tag is imported from the previous " +build" job. This is necessary because the goal is to perform end-to-end tests on the codebase that corresponds to a +particular release version, rather than the code at the head of the repository.