Playwright Reference Project: A Framework You Can Actually Use

Stop Starting From Scratch Every Time

You know what's exhausting? Setting up a new test automation framework from scratch. Every. Single. Time.

You install Playwright. You write a test. It works. Then you need reporting. Then you need Page Objects. Then you need CI/CD. Then you realize your locators are a mess. Then you're rewriting everything because you didn't plan for scale.

I got tired of this. So I built a reference project that solves the problems you'll actually face—not the ones in beginner tutorials.

---

What This Actually Is

This is a production-ready Playwright framework. Not a "hello world" example. Not a tutorial project. A real framework you can clone and adapt to your application.

It includes:

• ✅ Page Object Model — Maintainable test architecture
• ✅ TypeScript — Type safety that catches errors before runtime
• ✅ Allure Reporting — Rich HTML reports with history tracking
• ✅ Fixtures Pattern — Dependency injection for cleaner tests
• ✅ Multi-Browser Support — Chrome, Edge, Firefox, Safari
• ✅ CI/CD Ready — GitHub Actions workflow included
• ✅ Comprehensive Logging — Winston-based structured logging
• ✅ Failure Artifact Capture — Screenshots, videos, traces on test failures
• ✅ Documentation — 13 detailed docs covering architecture to troubleshooting

No fluff. No overcomplicated abstractions. Just the patterns that actually work in production environments.

---

Who This Is For

You should use this if:

• You're starting a new Playwright project and don't want to reinvent the wheel
• You inherited a messy automation codebase and need a better structure
• You're learning test automation and want to see best practices in action
• You're tired of frameworks that work great in demos but fall apart at scale

Skip this if:

• You're looking for a record-and-playback tool (this requires actual coding)
• You need Cucumber/BDD (this uses Playwright's native test runner)
• You want something "simple" (this is structured for real projects, not toy examples)

---

What You'll Find Inside

Core Architecture (lib/)

The foundation that makes everything else work:

basepage.ts A base class with common methods for all page objects. Click, type, wait, navigate—the stuff you'd otherwise copy-paste across every page class.

helpers-fixtures.ts & page-object-fixtures.ts Playwright fixtures for dependency injection. Page objects get injected into your tests automatically. No manual instantiation mess.

allure-helper.ts Utilities for rich Allure reporting. Add metadata, steps, attachments—make your reports actually useful.

logger.ts Winston-based logging with test lifecycle tracking. Know what happened when tests fail.

test-failure-capture.ts Automatically captures screenshots, videos, and traces when tests fail. Debugging becomes way easier.

Page Objects (page-objects/)

Example implementations showing how to structure page classes:

export class ExampleLoginPage extends BasePage {
    readonly emailInput: Locator;
    readonly passwordInput: Locator;
    
    constructor(page: Page) {
        super(page);
        this.emailInput = page.getByRole('textbox', { name: /email/i });
        this.passwordInput = page.getByRole('textbox', { name: /password/i });
    }
    
    async login(email: string, password: string) {
        await this.type(this.emailInput, email);
        await this.type(this.passwordInput, password);
        await this.click(this.loginButton);
    }
}

Notice:

• Uses Playwright's recommended locators (getByRole, getByText)
• Extends BasePage for common functionality
• Methods represent user actions, not technical details

Tests (tests/)

Example test files showing proper structure:

import { test, expect } from '../lib/page-object-fixtures';

test('User can log in successfully', async ({ exampleLoginPage }) => {
    await AllureHelper.applyTestMetadata({
        displayName: "Successful Login Flow",
        tags: ["smoke", "critical"],
        severity: "critical",
        epic: "Authentication",
        feature: "Login",
        story: "User Login"
    });
    
    await exampleLoginPage.navigateTo('/login');
    await exampleLoginPage.login('user@test.com', 'password123');
    await expect(page).toHaveURL(/dashboard/);
});

Tests use:

• Fixtures for page object injection
• Allure metadata for reporting
• Clear, readable assertions

Configuration Files

playwright.config.ts Main Playwright configuration. Multi-browser projects, timeouts, retries, reporters—all configured and ready.

.env.example Environment variables template. Copy to .env and customize for your app.

tsconfig.json TypeScript compiler settings optimized for Playwright.

eslint.config.mjs Linting rules to keep your code clean.

CI/CD (.github/workflows/)

GitHub Actions workflow that:

• Runs tests on Chrome
• Generates Allure reports
• Uploads artifacts
• Supports manual triggers and scheduled runs (cron examples included)

Adapt it to GitLab CI or Jenkins—the pattern is transferable.

Documentation (docs/)

13 comprehensive guides:

1. Architecture Overview
2. Configuration
3. Test Development
4. Page Objects
5. CI/CD Integration
6. Utilities and Helpers
7. Reporting
8. Project Setup
9. Allure Implementation
10. Allure Methods Deep Dive
11. Troubleshooting
12. Multi-Browser Setup
13. Logging

These aren't auto-generated nonsense. They're written explanations of why things are structured the way they are.

---

How to Actually Use This

1. Clone and Install

git clone https://github.com/StevenG0211/playwright-reference-project.git
cd playwright-reference-project
npm install

2. Install Browsers

Quick setup (Chrome only):

npx playwright install chromium --with-deps

Recommended (all browsers for parallel execution):

npx playwright install chromium msedge firefox webkit --with-deps

3. Configure Environment

cp .env.example .env

Edit .env with your application details:

• BASE_URL — Your app's URL
• TEST_USER_EMAIL / TEST_USER_PASSWORD — Test credentials
• TEST_ID_ATTRIBUTE — Custom test ID attribute (if used)

Update playwright.config.ts:

• Set baseURL
• Adjust testIdAttribute if needed
• Configure timeouts and retries

4. Run Tests

# Run smoke tests on Chrome
npm run test:smoke-chrome

# Run all tests (regression)
npm run test:regression

# Run tests in UI mode (interactive)
npx playwright test --ui

# Run specific test file
npx playwright test tests/example-login.spec.ts

5. Generate Reports

# Generate Allure report
npm run allure:generate

# Open Allure report
npm run allure:open

# Open Playwright HTML report
npx playwright show-report

---

Customizing for Your Application

Step 1: Create Your Page Objects

Replace the example page objects with your own:

// page-objects/your-page.ts
import BasePage from "../lib/basepage";
import { Locator, Page } from "@playwright/test";

export class YourPage extends BasePage {
    readonly someElement: Locator;
    
    constructor(page: Page) {
        super(page);
        this.someElement = page.getByRole('button', { name: 'Submit' });
    }
    
    async performAction() {
        await this.click(this.someElement);
    }
}

Step 2: Register in Fixtures

Add to lib/page-object-fixtures.ts:

yourPage: async ({ page }, use) => {
    const yourPage = new YourPage(page);
    use(yourPage);
}

Step 3: Write Tests

import { test, expect } from '../lib/page-object-fixtures';

test('Your test', async ({ yourPage }) => {
    await yourPage.performAction();
    // Add assertions
});

---

What Makes This Different

1. It's Actually Maintained

This isn't a "throw it on GitHub and forget it" project. I use this structure in real projects. When I find better patterns, I update it.

2. It Solves Real Problems

This framework includes solutions to problems you don't realize you'll have yet:

• Flaky tests? Proper waits and retry logic baked in
• Hard to debug failures? Automatic screenshot, video, and trace capture
• Reports that don't help? Allure integration with proper metadata
• Messy test code? Fixtures pattern keeps tests clean
• Slow CI/CD? Multi-browser parallel execution configured

3. It Doesn't Overcomplicate Things

I've seen frameworks with 17 layers of abstraction and custom DSLs. Those are nightmares to maintain.

This framework:

• Uses Playwright's native features
• Adds structure without hiding what's happening
• Includes only what you'll actually use

4. The Documentation Doesn't Suck

Each doc covers a specific topic in depth. No auto-generated API docs that just repeat method signatures. Actual explanations of patterns and decisions.

---

What This Doesn't Do

Let's be clear about what this framework doesn't include:

❌ API Testing Examples The framework supports API testing (Playwright handles it), but the examples focus on UI testing. You'll need to add your own API test implementations.

❌ Mobile App Testing This is for web applications. Mobile testing requires Appium or similar tools—different setup entirely.

❌ Visual Regression Testing No Percy, Applitools, or visual diff tools integrated. You can add them, but they're not included by default.

❌ BDD/Cucumber Uses Playwright's native test runner, not Cucumber. If you need Gherkin syntax, this isn't the right starting point.

❌ Database Testing Utilities You'll need to add your own database connection and validation logic.

---

Common Questions

"Can I use this with my existing tests?"

Yes. The page object pattern and fixtures are modular. You can gradually migrate existing tests to this structure.

"Do I need to know TypeScript?"

Basic TypeScript helps, but if you know JavaScript, you'll pick it up quickly. The type safety is worth the learning curve—it catches bugs before you run tests.

"Is this opinionated?"

Absolutely. This framework makes specific choices:

• TypeScript over JavaScript
• Page Object Model over test-only architecture
• Fixtures over manual instantiation
• Playwright's native runner over Cucumber

If you disagree with these choices, this might not be for you. But these are battle-tested decisions, not random preferences.

"Can I use this commercially?"

Yes. ISC license. Use it in your company projects, adapt it, share it—just don't sue me if something breaks.

"What if I need help?"

• Read the docs in the /docs folder first
• Check the example implementations
• Open an issue on GitHub if you find bugs
• Connect with me on LinkedIn or TikTok

---

Final Thoughts

Building a good automation framework takes time. This project gives you a head start with patterns that work in production.

You still need to:

• Understand your application
• Design good test cases
• Write maintainable locators
• Handle your specific edge cases

But you won't waste weeks setting up infrastructure, figuring out reporting, or debugging fixture injection issues.

Clone it. Explore it. Adapt it. Make it yours.

---

Questions? Find me on TikTok @angry_tester or connect on LinkedIn.

---

angry docs — QA concepts without the fluff