Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
This page provides technical documentation for setting up the playwright-page-object library for local development. The project is designed as a TypeScript-first Page Object Model (POM) framework for Playwright that utilizes decorator-driven selector composition. The development environment focuses on a streamlined workflow using modern tools like tsup for building and Biome for linting and formatting.
Sources: package.json:4-5, CONTRIBUTING.md:20-22
Prerequisites and Environment
The project requires a modern Node.js environment to support ECMAScript accessor keywords and TypeScript 5.0+.
| Requirement | Value | Source |
|---|---|---|
| Node.js Engine | >=20.0.0 | package.json:113-115 |
| Volta Node Pin | 24.14.0 | package.json:116-118 |
| TypeScript | >=5.0.0 | package.json:106-109, README.md:52-54 |
| Playwright | >=1.35.0 | package.json:102-105 |
Initial Setup
To begin local development, developers must fork and clone the repository, followed by dependency installation using npm ci to ensure a clean, reproducible environment.
# Clone and install
npm ci
The project utilizes husky for Git hooks, which is automatically initialized during the prepare script lifecycle.
Sources: CONTRIBUTING.md:24-30, package.json:19
Development Workflow
The core development loop relies on tsup for fast rebuilding.
Building and Watching
Developers can run a development watcher that rebuilds the project instantly upon file changes. This is particularly useful for testing changes in the "Model Context Protocol" (MCP) server or the library core.
npm run dev
Note: This command runs tsup src/index.ts with the --watch flag.
Sources: CONTRIBUTING.md:31-35, package.json:15-16
Code Quality and Style
The project uses Biome for zero-config formatting and linting. Developers do not need to manually configure ESLint or Prettier.
- Linting:
npm run lintchecks thesrcdirectory. - Auto-fixing:
npm run lint:fixapplies formatting and basic linting fixes. - Git Hooks: A Husky pre-commit hook automatically runs Biome to ensure code style compliance before commits are accepted.
Sources: CONTRIBUTING.md:37-47, package.json:17-18, biome.json:1-30
Type Checking
To verify type integrity across the core library and the example project, run:
npm run typecheck
This executes tsc --noEmit in both the root and the example directory.
Sources: package.json:20
Testing Architecture
The project maintains a dual testing strategy: unit/integration tests for the core library and end-to-end (E2E) tests for the example application.
Core Testing
Unit tests are powered by vitest.
npm run test: Runs the test suite once.npm run test:watch: Runs tests in watch mode for active development.
Sources: package.json:21-22
Example App and E2E Testing
The example directory contains a React checkout application that serves as a demonstration and an integration test target. The flow for testing the example involves packing the local library into a tarball to simulate a real installation.
The diagram shows the sequence of packaging and installing the local library into the example app before running Playwright tests.
Sources: package.json:23, example/package.json:10, example/README.md:12-25
| Script | Command / Description |
|---|---|
pack:example | node ./run/pack-example-package.mjs |
test:example | Packs the library, installs it in the example, and runs Playwright. |
test:e2e | (Inside example) playwright test |
Sources: package.json:23, example/package.json:10
Contribution and Release Standards
The project follows the Conventional Commits specification to manage automated releases via GitHub Actions.
Commit Messages
Commit messages determine the next version number and generate changelogs:
feat:triggers a Minor release (e.g., 1.1.0).fix:triggers a Patch release (e.g., 1.0.1).docs:orchore:triggers no release.
Sources: CONTRIBUTING.md:49-62
Release Pipeline
The release process is managed by semantic-release.
The diagram illustrates the automated path from a code push to an NPM publication.
Sources: package.json:44-77, CONTRIBUTING.md:64-67
Conclusion
Local development for playwright-page-object is built on a "low-config" philosophy. By utilizing Biome for style, tsup for builds, and vitest for testing, the environment allows developers to focus on the decorator-driven architecture. Integration is verified by packing the library into the included React example, ensuring that the locator composition and PageObject base classes function correctly in a real-world Playwright environment.
Sources: CONTRIBUTING.md:20-22, README.md:45-50