Skip to content

Overview

Jump to bottom
Abigail Smith edited this page Sep 17, 2025 · 1 revision

1. Introduction

This wiki page provides an overview of the Playwright Project Template repository. It serves as a starting point for UI test automation within HMCTS using Playwright. The template is designed to accelerate setup by providing a robust foundation with cross-browser support, environmental configuration, and sensible defaults. You can clone the repository to start a new project or copy specific parts into an existing one.

2. Getting Started

This page will guide you through setting up and running tests with the Playwright Project Template.

Prerequisites

Before you begin, ensure you have the following installed on your machine:

  • Node.js (v14+)
  • Yarn

Installation

  1. Clone the repository from GitHub: 
    git clone https://github.com/hmcts/tcoe-playwright-example.git
  2. Navigate to the project directory: 
    cd tcoe-playwright-example
  3. Install the project dependencies: 
    yarn install

Running Tests

  • Run all tests: 
    yarn playwright test
  • Run a specific test file: 
    yarn playwright test tests/specific_test_file.spec.ts
  • Run on a specific browser: 
    yarn playwright test --project=chrome
yarn playwright test --project=firefox
yarn playwright test --project=webkit
  • Run tests using tags: 
    yarn playwright test --grep @smoke

3. Project Structure

The repository follows a Page Object Model (POM) design pattern. This approach ensures that your test code is well-organized, reusable, and easy to maintain by separating test logic from page element locators and actions.

Core Directories

  • tests/: Contains all of your test files.
  • page-objects/: Houses the page objects, which represent different pages or components of your application. This includes:
    • components/: For common components shared across pages.
    • elements/: For common elements that could be found in a page or in a component.
    • pages/: For unique pages that may contain their own locators.
  • utils/: Contains utility functions and common tasks, such as login helpers or API methods.

Interaction with playwright-common

This project enhances its testing capabilities by leveraging the hmcts/playwright-common library. It does this by importing and extending the base Playwright test object with custom fixtures.

Fixtures are a powerful Playwright feature that allows you to set up the environment for your tests. By using fixtures from playwright-common, the project can:

  • Reuse common setup logic, such as authentication for different HMCTS applications.
  • Maintain consistency across various projects by using a single, version-controlled source for shared code.
  • Simplify test code by abstracting complex prerequisites into a single fixture, allowing you to write more focused and readable tests.

4. Key Features

This page highlights some of the powerful features included in this project template.

  • Cross-Browser Testing: Supports running tests on Chromium, Firefox, and WebKit.
  • Responsive Testing: Tests can be run on different viewports (e.g., tablet, desktop).
  • Parallel Test Execution: Tests run concurrently, significantly reducing the time for feedback.
  • Accessibility Tests: Integrates with libraries like Axe Core to perform basic accessibility checks. You can run these specifically using the @a11y tag.
  • Performance Tests: An implementation of Lighthouse is included to provide quick feedback on UI performance.
  • CI/CD Ready: The repository includes a sample Jenkinsfile for seamless integration with your Continuous Integration pipelines.
  • Test Tagging: Use tags like @smoke or @a11y to group and run specific subsets of your tests.

5. Debugging and CI

This page provides guidance on debugging tests and running them in a Continuous Integration environment.

Debugging Tests

  • Tracing and recording: To capture traces, screenshots, and videos for debugging, use the command: 
    yarn playwright test --trace on --video on --screenshot on
  • Pausing execution: Use page.pause() inside your test to stop execution at a specific point. This requires running in headed mode.

Continuous Integration

The project provides two sample Jenkinsfiles to help you get started with CI:

  • Jenkinsfile_CNP: A typical "merge" pipeline that runs when you create a Pull Request. It performs type checks and linting.
  • Jenkinsfile_nightly: A scheduled daily pipeline designed for running your regression suite. You can customize this to run specific tests.
Clone this wiki locally