Skip to content

PetFolio UI tests

The PetFolio UI Tests can be found within the apps folder, see petfolio-ui-tests. The purpose of the application is to provide UI tests that capture high level integration between pages of the PetFolio UI applications.

Stack

  • Playwright for browser automation
  • playwright-bdd for Gherkin (BDD) support - feature files and step definitions
  • Page Object Model for maintainable locator management

Project structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
apps/petfolio-ui-tests/
├── playwright.config.ts        # Playwright + BDD configuration
├── project.json                # Nx targets (bddgen, e2e, lint)
├── eslint.config.mjs           # ESLint config
└── src/
    ├── features/               # Gherkin .feature files
    │   └── home.feature
    ├── steps/                  # Step definitions
    │   └── home.steps.ts
    └── pages/                  # Page objects
        └── HomePage.ts

Features

Gherkin .feature files live in src/features/. Each file describes a user-facing scenario in plain language:

1
2
3
4
5
Feature: Home page

  Scenario: Site loads with expected content
    Given I am on the home page
    Then I should see the welcome heading

Steps

Step definitions in src/steps/ implement the Gherkin steps using createBdd from playwright-bdd. Each step receives a Playwright page fixture and uses page objects for interactions and assertions.

Pages

Page objects in src/pages/ encapsulate locators and actions for a given page, keeping step definitions clean and avoiding duplicated selectors.

Running tests

Command Description
npx nx e2e petfolio-ui-tests Run all e2e tests (headless)
npx nx e2e petfolio-ui-tests --ui Run in Playwright UI mode
npx nx e2e petfolio-ui-tests --headed Run in headed browsers
npx nx e2e petfolio-ui-tests --debug Run with Playwright Inspector
npx nx e2e petfolio-ui-tests --browser=firefox Run in a specific browser

The e2e target automatically runs bddgen first to generate Playwright spec files from the feature files, then executes the tests.

How it works

  1. bddgen reads .feature files and step definitions, then generates intermediate Playwright spec files into .features-gen/ (git-ignored).
  2. Playwright runs the generated specs as standard tests.
  3. The webServer config in playwright.config.ts automatically starts the petfolio-business dev server if it isn't already running.

CI integration

UI tests run automatically in the CI pipeline when petfolio-business is affected. The pipeline builds a Docker image, then runs Playwright against the containerised application.

Pipeline flow

graph LR
    A[Build Docker Image] --> B[Download Image Artefact]
    B --> C[Start Container]
    C --> D[Run Playwright Tests]
    D --> E[Upload Reports]
    E --> F[Stop Container]

    classDef layer-infra fill:#f5a6232e,stroke:#f5a623,stroke-width:2px
    classDef layer-domain fill:#7ed32126,stroke:#7ed321,stroke-width:2px
    classDef neutral fill:#c8c8c826,stroke:#999999,stroke-width:1.5px

    class A layer-infra
    class B,C,F neutral
    class D layer-domain
    class E layer-domain
Diagram key
  • Orange (Infrastructure): Docker image build step
  • Green (Domain): Test execution and reporting
  • Grey (Neutral): Container lifecycle steps
  1. The build_docker_image job builds and uploads the Docker image as a CI artefact.
  2. The run_ui_tests job downloads the image, starts a container via the start-docker-container composite action, and waits for the healthcheck to pass.
  3. Playwright runs chromium-only tests against the container on localhost:4200.
  4. Test results are appended to the CI summary PR comment and included in any failure issues created on the main branch.

Composite action - start-docker-container

A reusable composite action at .github/actions/start-docker-container/ handles container lifecycle:

  • Starts the container with configurable port mapping and environment variables
  • Polls until the container is running (up to 60s)
  • Polls the Docker healthcheck status (up to 90s)
  • On healthcheck failure, captures container logs and uploads them as an artefact

Reports and artefacts

Playwright is configured with two reporters:

Reporter Output Path Purpose
HTML dist/.playwright/apps/petfolio-ui-tests/playwright-report/ Interactive test report
JUnit dist/.playwright/apps/petfolio-ui-tests/test-results/junit.xml CI summary generation

Both are uploaded as CI artifacts with a 7 day retention period. The JUnit XML is parsed to produce a test summary table in the GitHub Actions step summary and the PR comment.