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

…ent (openmrs#231)

.eslintrc

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

.github/workflows/e2e.yml

@@ -0,0 +1,102 @@
+name: E2E Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+env:
+  TURBO_API: 'http://127.0.0.1:9080'
+  TURBO_TOKEN: 'turbo-token'
+  TURBO_TEAM: ${{ github.repository_owner }}
+
+jobs:
+  run_e2e_tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📥 Checkout repo
+        uses: actions/checkout@v4
+
+      - name: 📝 Copy test environment variables
+        run: cp example.env .env
+
+      - name: 🛠️ Setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+
+      - name: 💾 Cache dependencies
+        id: cache-dependencies
+        uses: actions/cache@v4
+        with:
+          path: '**/node_modules'
+          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
+
+      - name: 📦 Install dependencies
+        if: steps.cache-dependencies.outputs.cache-hit != 'true'
+        run: yarn install --immutable
+
+      - name: 🎭 Get installed Playwright version
+        id: playwright-version
+        run: echo "PLAYWRIGHT_VERSION=$(grep '@playwright/test@' yarn.lock | sed -n 's/.*npm:\([^":]*\).*/\1/p' | head -n 1)" >> $GITHUB_ENV
+
+      - name: 💾 Cache Playwright binaries
+        id: playwright-cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/ms-playwright
+          key: ${{ runner.os }}-playwright-${{ env.PLAYWRIGHT_VERSION }}
+
+      - name: 🎭 Install Playwright Browsers
+        run: npx playwright install chromium --with-deps
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+
+      - name: 🚀 Setup local cache server for Turborepo
+        uses: felixmosh/turborepo-gh-artifacts@v3
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          server-token: ${{ env.TURBO_TOKEN }}
+
+      - name: 🏗️ Build apps
+        run: yarn turbo run build --color --concurrency=5
+
+      - name: 🚀 Run dev server
+        run: bash e2e/support/github/run-e2e-docker-env.sh
+
+      - name: ⏳ Wait for OpenMRS instance to start
+        run: while [[ "$(curl -s -o /dev/null -w ''%{http_code}'' http://localhost:8080/openmrs/login.htm)" != "200" ]]; do sleep 10; done
+
+      - name: 🧪 Run E2E tests
+        run: yarn test-e2e
+
+      - name: 🛑 Stop dev server
+        if: '!cancelled()'
+        run: docker stop $(docker ps -a -q)
+
+      - name: 📤 Upload report
+        uses: actions/upload-artifact@v4
+        if: '!cancelled()'
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+          overwrite: true
+
+      - name: 📝 Capture Server Logs
+        if: always()
+        uses: jwalton/gh-docker-logs@v2
+        with:
+          dest: './logs'
+
+      - name: 📤 Upload Logs as Artifact
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: server-logs
+          path: './logs'
+          retention-days: 2
+          overwrite: true

.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/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';

e2e/core/test.ts

@@ -0,0 +1,20 @@
+import { APIRequestContext, Page, test as base } from '@playwright/test';
+import { api } from '../fixtures';
+
+// This file sets up our custom test harness using the custom fixtures.
+// See https://playwright.dev/docs/test-fixtures#creating-a-fixture for details.
+// If a spec intends to use one of the custom fixtures, the special `test` function
+// exported from this file must be used instead of the default `test` function
+// provided by playwright.
+
+export interface CustomTestFixtures {
+  loginAsAdmin: Page;
+}
+
+export interface CustomWorkerFixtures {
+  api: APIRequestContext;
+}
+
+export const test = base.extend<CustomTestFixtures, CustomWorkerFixtures>({
+  api: [api, { scope: 'worker' }],
+});

e2e/fixtures/api.ts

@@ -0,0 +1,26 @@
+import { APIRequestContext, PlaywrightWorkerArgs, WorkerFixture } from '@playwright/test';
+
+/**
+ * A fixture which initializes an [`APIRequestContext`](https://playwright.dev/docs/api/class-apirequestcontext)
+ * that is bound to the configured OpenMRS API server. The context is automatically authenticated
+ * using the configured admin account.
+ *
+ * Use the request context like this:
+ * ```ts
+ * test('your test', async ({ api }) => {
+ *   const res = await api.get('patient/1234');
+ *   await expect(res.ok()).toBeTruthy();
+ * });
+ * ```
+ */
+export const api: WorkerFixture<APIRequestContext, PlaywrightWorkerArgs> = async ({ playwright }, use) => {
+  const ctx = await playwright.request.newContext({
+    baseURL: `${process.env.E2E_BASE_URL}/ws/rest/v1/`,
+    httpCredentials: {
+      username: process.env.E2E_USER_ADMIN_USERNAME,
+      password: process.env.E2E_USER_ADMIN_PASSWORD,
+    },
+  });
+
+  await use(ctx);
+};

e2e/fixtures/index.ts

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

e2e/pages/chart-page.ts

@@ -0,0 +1,11 @@
+import { type Page } from '@playwright/test';
+
+export class ChartPage {
+  constructor(readonly page: Page) {}
+
+  readonly formsTable = () => this.page.getByRole('table', { name: /forms/i });
+
+  async goTo(patientUuid: string) {
+    await this.page.goto('/openmrs/spa/patient/' + patientUuid + '/chart');
+  }
+}

e2e/pages/home-page.ts

@@ -0,0 +1,9 @@
+import { Page } from '@playwright/test';
+
+export class HomePage {
+  constructor(readonly page: Page) {}
+
+  async gotoHome() {
+    await this.page.goto('/openmrs/spa/login');
+  }
+}

e2e/pages/index.ts

@@ -0,0 +1,2 @@
+export * from './home-page';
+export * from './chart-page';

e2e/specs/stock-overview-test.spec.ts

@@ -0,0 +1,19 @@
+import { test, expect } from '@playwright/test';
+import dotenv from 'dotenv';
+import { HomePage } from '../pages';
+
+dotenv.config();
+//This is a sample test which can be deleted
+test.describe('Overview Page Test', () => {
+  test('should navigate to the Overview page and verify sections', async ({ page }) => {
+    const homePage = new HomePage(page);
+
+    await test.step('When I visit the home page', async () => {
+      await homePage.gotoHome();
+    });
+
+    await test.step('Then I should be at the home page', async () => {
+      await expect(page).toHaveURL(`${process.env.E2E_BASE_URL}spa/login`);
+    });
+  });
+});