Pearl Test Automation Framework

This is a test automation framework built on Playwright, using javascript as programming lenguage. It allows you to write end-to-end tests for Pearl's applications across different browsers (Chromium, Firefox).

Getting started

1. Clone the repository git clone [email protected]:hellopearl/quality-assurance/pearl-test-automation.git
2. Install dependencies npm install
3. Configure your tests environment (e.g URL, credentials)
4. Write your test scripts under the tests directory
5. Run tests npm run test-stage

Running tests

Running using pre-defined scripts

You can run all the existing tests using the scripts pre-defined in the package.json. For instance, you can run the test on the stage environment using the following command npm run test-stage

Running a single test

You can run a single test passing as parameter the test that you want to execute npx playwright test login.spec.js

Running using the Playwright UI

You can run the tests using the Playwright UI, adding the parameter --ui to the command npx playwright test login.spec.js --ui

Headless execution

By default, the tests are running in headless mode. If you want to run the tests and see the execution you to need pass the parameter --headed npx playwright test login.spec.js --headed

Environments

To set the environment where the tests will be executed, you need to define the environment variable ENV, possible values for this env variable are: local, dev, stage, prod.

All the credentials and the rest of sensitive data are stored and they should be accessed through environment variables. To run the tests locally, you need to create a .env file with all the environment variables used during the tests execution.

Those files should be located under the folder /env and the filename should have a suffix with the environment name, e.g /env/.env.dev

Using pearl-test-automation as a dependency (e2e-run)

Other repositories can install pearl-test-automation as a dev dependency and run its tests against their own local or remote environment using the e2e-run CLI.

How it works

e2e-run is a CLI binary shipped with this package. When you install pearl-test-automation, the e2e-run command becomes available in your node_modules/.bin/ directory (usable in npm scripts or via npx).

Under the hood it:

1. Takes a required environment name as the first argument (local, dev, stage, prod)
2. Sets the ENV environment variable automatically (no cross-env needed)
3. Resolves the playwright.config.js bundled inside the package
4. Forwards all remaining arguments directly to playwright test

e2e-run <env> [playwright args...]

Setup in the consuming repo

1. Install as a dev dependency:

npm install --save-dev pearl-test-automation

2. Add scripts to your package.json:

{
  "scripts": {
    "test:e2e": "e2e-run local --project=SO",
    "test:e2e:headed": "e2e-run local --project=SO --headed",
    "test:e2e:dev": "e2e-run dev --project=SO"
  }
}

3. Make sure your app is running locally before executing e2e-run local (e.g. SO expects http://localhost:3000).

Examples

Run SO tests against localhost:

e2e-run local --project=SO

Run SO tests against dev environment:

e2e-run dev --project=SO

Run PI tests against stage:

e2e-run stage --project=PI

Run tests in headed mode (visible browser):

e2e-run local --project=SO --headed

Filter tests by tag:

e2e-run dev --project=SO --grep=@heartbeat

Combine multiple filters (tag + headed):

e2e-run local --project=SO --headed --grep=@heartbeat

Limit the number of parallel workers:

e2e-run dev --project=PI --workers=1

Run multiple projects at once:

e2e-run dev --project=SO --project=PI --project=Management

Run a specific test file:

e2e-run local --project=SO tests/SO/login.spec.js

Debug a single test with Playwright Inspector:

e2e-run local --project=SO --debug

Open the Playwright UI runner:

e2e-run local --project=SO --ui

Available projects

| Project | Description | |------------------|--------------------------| | SO | Second Opinion UI tests | | PI | Practice Intelligence UI | | Management | Management portal | | Authentication | Auth flows | | RCM | RCM API tests | | agentControl | Agent Control API tests |

Available environments

| Env | SO URL | PI URL | MGMT URL | |---------|-------------------------|-----------------------------|-------------------------------------| | local | http://localhost:3000 | https://dev.pi.hellopearl.com | https://management-dev.hellopearl.com | | dev | https://dev.secondopinion.hellopearl.com | https://dev.pi.hellopearl.com | https://management-dev.hellopearl.com | | stage | https://stage.secondopinion.hellopearl.com | https://stage.pi.hellopearl.com | https://management-stage.hellopearl.com | | prod | https://secondopinion.hellopearl.com | https://pi.hellopearl.com | https://management.hellopearl.com |

Environment variables and credentials

The e2e-run binary sets ENV for you, but the tests may still need credentials and other secrets. The consuming repo should provide these via:

• An env/.env.<environment> file at the repo root (e.g. env/.env.local)
• A .env file at the repo root
• Or environment variables set directly in the shell / CI pipeline

Adding custom tests in a consuming repo

If you need to add your own tests on top of the bundled ones, create an e2e.config.js file at the root of your repo. e2e-run automatically detects it and uses it instead of the bundled config.

Step 1 -- Create e2e.config.js:

import { baseConfig } from 'pearl-test-automation/playwright.config.js'
import { defineConfig } from '@playwright/test'

export default defineConfig({
    ...baseConfig,
    projects: [
        ...baseConfig.projects,
        {
            name: 'my-app-e2e',
            testDir: './e2e',
            use: { baseURL: 'http://localhost:3000' },
            dependencies: ['so-setup'],
        },
    ],
})

baseConfig is exported with absolute paths, so all bundled tests, reporters, and setup files resolve correctly even when imported from a different repo.

Step 2 -- Write test files in your local e2e/ directory:

// e2e/my-feature.spec.js
import { test, expect } from '@playwright/test'

test('my custom feature works', async ({ page }) => {
    await page.goto('/')
    await expect(page.getByText('Welcome')).toBeVisible()
})

Step 3 -- Run with e2e-run:

# run only your custom tests
e2e-run local --project=my-app-e2e

# run bundled SO tests alongside your custom tests
e2e-run local --project=SO --project=my-app-e2e

# run everything (bundled + custom)
e2e-run local

If no e2e.config.js is found, e2e-run falls back to the bundled config as before.

Logger

The logger was set up by wrapping the allure.attachment() method, this is to allow for the log to be shown in the allure report that is generated.

In order to add logs, you only have to import the import { GlobalLogger } from '{the path to util/logger/globalLogger.js}', and then call the method log().

Example: await GlobalLogger.log("Example log").

Qmetry integration

Qmetry integration is done using a Playwright custom reporter, which allow us to update the execution results in Qmetry every time a test is run.

To make this work, the environment variable TEST_CYCLE_KEY needs to be set. This variable should contain the key of the test cycle in Qmetry. e.g DEN-TR-62.

Zephyr integration

Zephyr integration is done using a Playwright custom reporter, which allow us update the execution results in Zephyr every time a test is run.

To make this work, the environment variable ZEPHYR_TEST_CYCLE_KEY needs to be set. This variable should contains the key of the test cycle in Zephyr. e.g DEN-R62.