playwright-typescript-playwright-test: a full-stack Playwright framework template

What the template gives you before you write a single test

This is a boilerplate, and the description says so: a template for a Playwright and TypeScript framework for web UI, API, mobile emulation, DB and visual testing, with a Docker image, SonarQube, Lighthouse and GitHub Actions setup with Slack notifications also implemented.

That framing sets the right expectation. You are not installing a package and calling an API, you are copying a directory and then replacing the example tests with your own. The value is the wiring, which is the tedious part: report configuration, CI triggers, a database connection, a container image, a static analysis profile.

The project is built on Microsoft Playwright, and the top feature list is largely a list of Playwright capabilities that the template exposes through npm scripts. Auto-waits for the relevant checks before performing an action, video recording for test cases, the codegen recorder that turns every action on the page into a generated script, trace files for in-depth execution details, headful and headless execution across Firefox, WebKit, Google Chrome, Chromium and MS Edge on Windows, Linux and Mac, API testing from Playwright 1.16 onwards, over 100 mobile device profiles, screenshot comparison, the slowMo option, download event monitoring, and serial and parallel execution.

The one claim to treat carefully is the last line of that list, that support turnaround time for queries is 48 hours. That is a statement about the upstream Playwright project rather than about this template, and it is the kind of number that ages badly.

Getting the toolchain in place before the first run

The prerequisites are more than just Node. The documentation asks for Node.js, and separately for Java 8 or above because Allure reports require it, with a specific instruction to install Java 11 instead of Java 8 if you intend to use SonarQube. The Allure command line tool is installed globally, and the SonarQube path additionally asks for the community server and the scanner for your operating system, both unzipped and added to the PATH environment variable.

The SonarQube and Allure requirements are the ones people miss. Allure renders its report with a Java process, so a machine that has only Node installed will fail at report generation rather than at test time, which is a confusing way to discover the dependency.

Installation itself is a clone, an install, and a browser download:

npm install
npx playwright install

That last command matters because Playwright ships its own browser builds. Without it the suite fails on a missing executable, and on CI runners it is the step most often forgotten, which is exactly why the Dockerfile in this repository runs npx playwright install chrome as its own layer.

One caveat that will cost you an hour if you do not read ahead. The clone URL printed in the installation section of the documentation is spelled with a transposed letter in the typecipt part of the name, so it will not resolve. Take the address from the browser rather than from the readme.

The ENV variable that shapes every run

The usage section starts with configuration in playwright.config.ts, and then moves to a single idea that runs through the whole design: the ENV variable is mandatory, and every command line invocation in the readme shows all three platform spellings for it.

On Windows CMD the pattern is a chained set, on Windows PowerShell it is a semicolon separated pair, and on Mac, Linux and WSL it is the POSIX inline form. The documentation is explicit that you must provide the ENV variable, and that it can be qa or dev.

The reason it appears everywhere is visible in the npm scripts, which pass it through to Playwright with the cross-env helper:

"test": "cross-env ENV=%ENV% npx playwright test",
"test:single": "cross-env ENV=%ENV% npx playwright test Interactions.test.ts --project=Chrome",
"test:parallel": "cross-env ENV=%ENV% npx playwright test --grep @Smoke --project=Chrome",
"test:serial": "cross-env ENV=%ENV% npx playwright test --grep @Smoke --workers=1 --project=Chrome"

The percent sign syntax in %ENV% is the Windows cmd convention, not the POSIX one, so on a Mac or a Linux CI runner those scripts do not expand the variable the way the readme suggests. cross-env is there to make the value consistent across platforms, but the placeholder itself still has to be right for the shell that npm invokes. This is the clearest sign that the template was developed on Windows and is worth fixing in the first hour you own it.

One script per testing style, and how the selection works

The script list is the clearest map of what the framework can do, and it is worth reading as a design document rather than as a list of commands.

The base test script runs the whole suite. test:single targets one file, Interactions.test.ts, on the Chrome project. test:parallel and test:serial both select by the @Smoke grep pattern, differing in that serial adds --workers=1 to force one at a time. test:ui opens the Playwright UI mode. test:api runs the @API grep against a project named API, test:db runs DB.test.ts against a DB project, test:device runs Emulation.test.ts against a Device project, and test:visual runs visualComparision.test.ts against Chrome. test:accessibility runs Axe.test.ts against Chrome.

Two things fall out of this. First, the different testing modes are separate Playwright projects with their own names, so API tests, database tests and device emulation tests have their own configuration and their own browser or context settings. Second, the selection mechanism for parallel and serial runs is a grep on a tag in the test name, for example @SmokeTest at the start of the test case name, with the tag value given in package.json against the test:parallel script. That is a light tagging scheme, and it means the tag is part of the test title rather than a metadata field.

test:record is the shortest one, npx playwright codegen, and it is the entry point for authoring: you drive a browser and Playwright writes the script.

Sharding, blob reports and the CI variants

The sharding scripts are where the template moves from a local convenience to a CI arrangement, and they are the most interesting part of the package manifest.

The local shard script runs Playwright with the blob reporter and a shard parameter that takes two environment variables, the shard index and the shard total:

"test:shard": "cross-env ENV=%ENV% npx playwright test --grep @Smoke --workers=1 --project=Chrome --reporter=blob --shard=%SHARD_INDEX%/%SHARD_TOTAL%",
"test:merge:reports": "npx playwright merge-reports --reporter html ./all-blob-reports"

The mechanism is the standard one for splitting a Playwright suite across parallel CI jobs. Each job runs a slice, writes a blob report, and a final job merges the blobs into a single HTML report with merge-reports. The blob reporter exists precisely because the HTML reporter cannot be written independently by several workers at once.

Note the pairing of shard scripts with the serial and CI variants. test:serial:ci and test:shard:ci drop the cross-env wrapper, which is the pattern for a CI job where the environment variable is set by the workflow itself rather than by the shell. That is a small but sensible distinction, and it is the one place in the manifest where the author clearly had both environments in mind.

The container image runs the serial suite

The Dockerfile is short and its choices are visible in five lines. The base image is node:20.5.1-bookworm-slim, the working directory is /app, the manifest and lock file are copied first so that the dependency install layer is cached, npm ci performs a clean install, and the rest of the source is copied in.

The last two instructions are the interesting ones. Chrome is installed for Playwright with npx playwright install chrome, and the default command is the serial test script rather than the full suite.

FROM node:20.5.1-bookworm-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npx playwright install chrome
CMD ["npm", "run", "test:serial"]

Choosing the serial script as the container default is a conservative choice, and it is worth understanding why rather than assuming it is a mistake. The serial script forces --workers=1, so a container that runs one job does not try to parallelise inside a resource slice that may only have a couple of cores. It also limits the run to the @Smoke tests rather than the entire suite.

What the image does not do is install the Java runtime that Allure needs, or the browsers other than Chrome, so if you build it and expect the Allure report or the Firefox project to work, you will need to extend it. The readme also mentions converting HTML reports to a zip format for sharing, which is the step that usually pairs with uploading artifacts from a CI job.

SonarQube, Lighthouse, and the rest of the reporting stack

Three reporting paths sit alongside the test execution, and they answer different questions.

The HTML and Allure reports come out of the run itself. The documentation states that Allure, HTML and Ortoni HTML reports are generated after execution, with an option to capture a screenshot, video or trace file on failure. The Ortoni report is a separate project linked in the built-with list, and the package manifest includes the allureReport script, which is simply allure serve, so you point a browser at the generated report locally.

SonarQube is the static analysis path rather than a test path, and it has its own prerequisites, Java 11, the community server and the scanner, with a sonar-project.properties file at the repository root and a .scannerwork directory already present. The .scannerwork directory being committed or present in the tree is a small smell, since it holds scanner working data, but it is also what tells you the author runs the scanner locally as well as in CI.

Lighthouse is the performance path, run through a script rather than a Playwright test, with the npm script pointing at node tests/lighthouse/Lighthouse.js. The repository layout supports that: there is a tests/ directory, a lib/ directory, a pageFactory/ directory, a utils/ directory, a global-setup.ts, a testConfig.ts and a CustomReporterConfig.ts at the root. The pageFactory pattern is the interesting one, since it is the usual way to keep page objects out of the test bodies in a Playwright suite, and the global setup file is where you would put the checks that need to run once before the suite, such as verifying that the environment under test is reachable.

Editorial conclusion

Adopt this template if you are starting a web application test suite from nothing and want the reporting, container and CI wiring in place on day one, since the Playwright projects, sharding scripts, Allure reports and SonarQube properties are already configured. Do not adopt it if you want a small library to depend on, since this is a template you copy and then own, and it does not work on macOS or Linux without editing the npm scripts, because they pass the environment variable through Windows-style percent syntax. Before you clone, note that the URL printed in the installation section is spelled with a transposed letter and will not resolve, so use the repository address from the browser instead, and confirm that the browser names in package.json match the project names in playwright.config.ts before running a single test.

Frequently asked questions

Official sources

1. akshayp7/playwright-typescript-playwright-test on GitHub
2. Issues
3. License: MIT
4. README
5. Releases