Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
These guidelines provide a structured framework for contributing to the playwright-page-object repository. The project is maintained as a decorator-driven Page Object Model (POM) framework for Playwright, and contributions are encouraged through a specific workflow involving communication, standardized commit messages, and automated linting tools.
Sources: CONTRIBUTING.md:1-5, README.md:1-5
Communication and Workflow
The project follows a "Golden Rule" for contributions. While minor fixes like typos or bug resolutions can be submitted directly via Pull Request, significant changes require prior discussion.
- Bugs & Typos: Open a Pull Request directly.
- New Features & Major Architecture: Open an Issue first to discuss the vision, architecture, and potential duplication of effort.
Sources: CONTRIBUTING.md:7-14
Contribution Flow Diagram
The following diagram illustrates the decision path for contributing based on the nature of the change.
Sources: CONTRIBUTING.md:7-14, CONTRIBUTING.md:46-50
Local Development Environment
Setting up the development environment requires Node.js (>=20.0.0) and npm. The project uses tsup for building and a development watcher for real-time compilation.
| Requirement | Value |
|---|---|
| Node.js Engine | >=20.0.0 |
| Primary Build Tool | tsup |
| Package Manager | npm |
| Formatting Engine | Biome |
Sources: package.json:96-98, CONTRIBUTING.md:16-30
Development Commands
- Install Dependencies:
npm ci - Development Watcher:
npm run dev(Runstsupin watch mode) - Build Project:
npm run build - Linting:
npm run lintornpm run lint:fix - Testing:
npm run test(Uses Vitest)
Sources: package.json:14-25, CONTRIBUTING.md:23-28
Code Style and Quality Standards
The project enforces code quality through Biome, which handles both linting and formatting without requiring extensive editor configuration.
Automated Checks
A Husky pre-commit hook is utilized to automatically format files and fix basic linting errors before a commit is finalized.
- Formatter: Configured to use tabs and double quotes for JavaScript.
- Linter: Recommended rules are enabled, with specific overrides such as
useArrowFunctionset to "off". - Imports: Automatically organized on save/fix via the Biome assist feature.
Sources: CONTRIBUTING.md:32-42, biome.json:1-40
Committing and Releases
playwright-page-object uses Conventional Commits to automate version numbering and changelog generation via Semantic Release.
Commit Message Format
Commit messages must follow the standard convention; otherwise, the Husky/Commitlint hook will reject the commit.
| Prefix | Description | Release Impact |
|---|---|---|
feat: | Added a new tool or feature | Minor (e.g., 1.1.0) |
fix: | Resolved a bug or crash | Patch (e.g., 1.0.1) |
docs: | Documentation updates | No Release |
chore: | Maintenance tasks | No Release |
Sources: CONTRIBUTING.md:44-55, package.json:42-63, commitlint.config.js:1
Release Automation Sequence
The project automates the release process through GitHub Actions once a PR is merged into the main branch.
Sources: CONTRIBUTING.md:57-61, package.json:42-63
Testing Architecture
Contributors should ensure that changes are verified by the existing test suite, which includes unit tests, decorator tests, and end-to-end (E2E) example tests.
- Unit Tests: Run via
vitest. - E2E Examples: Located in the
example/directory. These can be run from the root usingnpm run test:example. This script packs the current package, installs it in the example project, and runs Playwright tests.
Sources: package.json:20-25, example/package.json:1-15
The project maintains high standards for contributions to ensure the reliability of the decorator-driven POM framework while keeping the development experience streamlined and automated.