O3-2902: (test) Setup playwright for automated tests in Stock Management

.eslintrc

@@ -48,5 +48,13 @@
         ]
       }
     ]
-  }
+  },
+  "overrides": [
+    {
+      "files": ["e2e/**/*.spec.ts"],
+      "rules": {
+        "testing-library/prefer-screen-queries": "off" 
+      }
+    }
+  ]
 }

.github/workflows/e2e.yml

@@ -0,0 +1,53 @@
+name: E2E Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  main:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+
+      - name: Copy test environment variables
+        run: |
+          cp example.env .env
+          sed -i 's/8080/8180/g' .env
+
+      - name: Setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-${{ hashFiles('yarn.lock') }}
+
+      - name: Install dependencies
+        run: yarn install
+
+      - name: Install Playwright Browsers
+        run: npx playwright install chromium --with-deps
+
+      - name: Run dev server
+        run: yarn start --sources 'packages/esm-*-app/' --port 8180 &
+
+      - name: Run E2E tests
+        run: yarn playwright test
+
+      - name: Upload Report
+        uses: actions/upload-artifact@v3
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30

.github/workflows/node.js.yml

@@ -54,6 +54,8 @@ jobs:
             dist
           overwrite: true
 
+
+
   pre_release:
     runs-on: ubuntu-latest
     needs: build

.gitignore

@@ -80,6 +80,12 @@ dist/
 !.yarn/sdks
 !.yarn/versions
 
+# Playwright and e2e tests
+/test-results/
+/playwright-report/
+/playwright/.cache/
+e2e/storageState.json
+
 # Turborepo
 .turbo
 /*.idea/

e2e/README.md

@@ -0,0 +1,117 @@
+# E2E Tests
+
+This directory contains an E2E test suite using the [Playwright](https://playwright.dev)
+framework.
+
+## Getting Started
+
+Please ensure that you have followed the basic installation guide in the [root README](../README.md). Once everything is set up, make sure the dev server is running by using:
+
+```sh
+yarn start 
+```
+
+Then, in a separate terminal, run:
+
+```sh
+yarn test-e2e --headed
+```
+
+By default, the test suite will run against the http://localhost:8080. You can override this by exporting `E2E_BASE_URL` environment variables beforehand:
+
+```sh
+# Ex: Set the server URL to dev3:
+export E2E_BASE_URL=https://dev3.openmrs.org/openmrs
+
+# Run all e2e tests:
+
+```sh
+yarn test-e2e --headed
+```
+
+To run a specific test by title:
+
+```sh
+yarn test-e2e --headed -g "title of the test"
+```
+
+Check [this documentation](https://playwright.dev/docs/running-tests#command-line) for more running options.  
+
+It is also highly recommended to install the companion VS Code extension:
+https://playwright.dev/docs/getting-started-vscode
+
+## Writing New Tests
+
+In general, it is recommended to read through the official [Playwright docs](https://playwright.dev/docs/intro)
+before writing new test cases. The project uses the official Playwright test runner and,
+generally, follows a very simple project structure:
+
+```
+e2e
+|__ commands
+|   ^ Contains "commands" (simple reusable functions) that can be used in test cases/specs,
+|     e.g. generate a random patient.
+|__ core
+|   ^ Contains code related to the test runner itself, e.g. setting up the custom fixtures.
+|     You probably need to touch this infrequently.
+|__ fixtures
+|   ^ Contains fixtures (https://playwright.dev/docs/test-fixtures) which are used
+|     to run reusable setup/teardown tasks
+|__ pages
+|   ^ Contains page object model classes for interacting with the frontend.
+|     See https://playwright.dev/docs/test-pom for details.
+|__ specs
+|   ^ Contains the actual test cases/specs. New tests should be placed in this folder.
+|__ support
+    ^ Contains support files that requires to run e2e tests, e.g. docker compose files. 
+```
+
+When you want to write a new test case, start by creating a new spec in `./specs`.
+Depending on what you want to achieve, you might want to create new fixtures and/or
+page object models. To see examples, have a look at the existing code to see how these
+different concepts play together.
+
+## Open reports from GitHub Actions / Bamboo
+
+To download the report from the GitHub action/Bamboo plan, follow these steps:
+
+1. Go to the artifact section of the action/plan and locate the report file.
+2. Download the report file and unzip it using a tool of your choice.
+3. Open the index.html file in a web browser to view the report. 
+
+The report will show you a full summary of your tests, including information on which 
+tests passed, failed, were skipped, or were flaky. You can filter the report by browser 
+and explore the details of individual tests, including any errors or failures, video 
+recordings, and the steps involved in each test. Simply click on a test to view its details.
+
+## Debugging Tests
+
+Refer to [this documentation](https://playwright.dev/docs/debug) on how to debug a test.
+
+## Configuration
+
+This is very much underdeveloped/WIP. At the moment, there exists a (git-shared) `.env`
+file which can be used for configuring certain test attributes. This is most likely
+about to change in the future. Stay tuned for updates!
+
+## Github Actions integration
+
+The e2e.yml workflow is made up of two jobs: one for running on pull requests (PRs) and
+one for running on commits.
+
+1. When running on PRs, the workflow will start the dev server, use dev3.openmrs.org as the backend, 
+and run tests only on chromium. This is done in order to quickly provide feedback to the developer. 
+The tests are designed to generate their own data and clean up after themselves once they are finished. 
+This ensures that the tests will have minimum effect from changes made to dev3 by other developers. 
+In the future, we plan to use a docker container to run the tests in an isolated environment once we 
+figure out a way to spin up the container within a small amount of time.
+2. When running on commits, the workflow will spin up a docker container and run the dev server against
+it in order to provide a known and isolated environment. In addition, tests will be run on multiple 
+browsers (chromium, firefox, and WebKit) to ensure compatibility.
+
+## Troubleshooting tips
+
+On MacOS, you might run into the following error:
+```browserType.launch: Executable doesn't exist at /Users/<user>/Library/Caches/ms-playwright/chromium-1015/chrome-mac/Chromium.app/Contents/MacOS/Chromium```
+In order to fix this, you can attempt to force the browser reinstallation by running:
+```PLAYWRIGHT_BROWSERS_PATH=/Users/$USER/Library/Caches/ms-playwright npx playwright install```

e2e/commands/index.ts

@@ -0,0 +1,2 @@
+export * from './patient-operations';
+export * from './visit-operations';

e2e/commands/patient-operations.ts

@@ -0,0 +1,105 @@
+import { APIRequestContext, expect } from '@playwright/test';
+
+export interface Patient {
+  uuid: string;
+  identifiers: Identifier[];
+  display: string;
+  person: {
+    uuid: string;
+    display: string;
+    gender: string;
+    age: number;
+    birthdate: string;
+    birthdateEstimated: boolean;
+    dead: boolean;
+    deathDate?: string;
+    causeOfDeath?: string;
+    preferredAddress: {
+      address1: string;
+      cityVillage: string;
+      country: string;
+      postalCode: string;
+      stateProvince: string;
+      countyDistrict: string;
+    };
+    attributes: Array<Record<string, unknown>>;
+    voided: boolean;
+    birthtime?: string;
+    deathdateEstimated: boolean;
+    resourceVersion: string;
+  };
+  attributes: { value: string; attributeType: { uuid: string; display: string } }[];
+  voided: boolean;
+}
+
+export interface Address {
+  preferred: boolean;
+  address1: string;
+  cityVillage: string;
+  country: string;
+  postalCode: string;
+  stateProvince: string;
+}
+
+export interface Identifier {
+  uuid: string;
+  display: string;
+}
+
+export const generateRandomPatient = async (api: APIRequestContext): Promise<Patient> => {
+  const identifierRes = await api.post('idgen/identifiersource/8549f706-7e85-4c1d-9424-217d50a2988b/identifier', {
+    data: {},
+  });
+  await expect(identifierRes.ok()).toBeTruthy();
+  const { identifier } = await identifierRes.json();
+
+  const patientRes = await api.post('patient', {
+    // TODO: This is not configurable right now. It probably should be.
+    data: {
+      identifiers: [
+        {
+          identifier,
+          identifierType: '05a29f94-c0ed-11e2-94be-8c13b969e334',
+          location: '44c3efb0-2583-4c80-a79e-1f756a03c0a1',
+          preferred: true,
+        },
+      ],
+      person: {
+        addresses: [
+          {
+            address1: 'Bom Jesus Street',
+            address2: '',
+            cityVillage: 'Recife',
+            country: 'Brazil',
+            postalCode: '50030-310',
+            stateProvince: 'Pernambuco',
+          },
+        ],
+        attributes: [],
+        birthdate: '2020-2-1',
+        birthdateEstimated: true,
+        dead: false,
+        gender: 'M',
+        names: [
+          {
+            familyName: `Smith${Math.floor(Math.random() * 10000)}`,
+            givenName: `John${Math.floor(Math.random() * 10000)}`,
+            middleName: '',
+            preferred: true,
+          },
+        ],
+      },
+    },
+  });
+  await expect(patientRes.ok()).toBeTruthy();
+  return await patientRes.json();
+};
+
+export const getPatient = async (api: APIRequestContext, uuid: string): Promise<Patient> => {
+  const patientRes = await api.get(`patient/${uuid}?v=full`);
+  return await patientRes.json();
+};
+
+export const deletePatient = async (api: APIRequestContext, uuid: string) => {
+  await api.delete(`patient/${uuid}`, { data: {} });
+};

e2e/commands/visit-operations.ts

@@ -0,0 +1,31 @@
+import { APIRequestContext, expect } from '@playwright/test';
+import { Visit } from '@openmrs/esm-framework';
+import dayjs from 'dayjs';
+
+export const startVisit = async (api: APIRequestContext, patientId: string): Promise<Visit> => {
+  const visitRes = await api.post('visit', {
+    data: {
+      startDatetime: dayjs().subtract(1, 'D').format('YYYY-MM-DDTHH:mm:ss.SSSZZ'),
+      patient: patientId,
+      location: process.env.E2E_LOGIN_DEFAULT_LOCATION_UUID,
+      visitType: '7b0f5697-27e3-40c4-8bae-f4049abfb4ed',
+      attributes: [],
+    },
+  });
+
+  await expect(visitRes.ok()).toBeTruthy();
+  return await visitRes.json();
+};
+
+export const endVisit = async (api: APIRequestContext, uuid: string) => {
+  const visitRes = await api.post(`visit/${uuid}`, {
+    data: {
+      location: process.env.E2E_LOGIN_DEFAULT_LOCATION_UUID,
+      startDatetime: dayjs().subtract(1, 'D').format('YYYY-MM-DDTHH:mm:ss.SSSZZ'),
+      visitType: '7b0f5697-27e3-40c4-8bae-f4049abfb4ed',
+      stopDatetime: dayjs().format('YYYY-MM-DDTHH:mm:ss.SSSZZ'),
+    },
+  });
+
+  return await visitRes.json();
+};

e2e/core/global-setup.ts

@@ -0,0 +1,32 @@
+import { request } from '@playwright/test';
+import * as dotenv from 'dotenv';
+
+dotenv.config();
+
+/**
+ * This configuration is to reuse the signed-in state in the tests
+ * by log in only once using the API and then skip the log in step for all the tests.
+ *
+ * https://playwright.dev/docs/auth#reuse-signed-in-state
+ */
+
+async function globalSetup() {
+  const requestContext = await request.newContext();
+  const token = Buffer.from(`${process.env.E2E_USER_ADMIN_USERNAME}:${process.env.E2E_USER_ADMIN_PASSWORD}`).toString(
+    'base64',
+  );
+  await requestContext.post(`${process.env.E2E_BASE_URL}/ws/rest/v1/session`, {
+    data: {
+      sessionLocation: process.env.E2E_LOGIN_DEFAULT_LOCATION_UUID,
+      locale: 'en',
+    },
+    headers: {
+      Accept: 'application/json',
+      Authorization: `Basic ${token}`,
+    },
+  });
+  await requestContext.storageState({ path: 'e2e/storageState.json' });
+  await requestContext.dispose();
+}
+
+export default globalSetup;

e2e/core/index.ts

@@ -0,0 +1 @@
+export * from './test';