Playwright Testing Base

A comprehensive Playwright testing framework base project with authentication support, multiple browser testing, and CI/CD integration.

🚀 Features

• Multi-browser testing - Chromium, Firefox, and WebKit support
• Authentication handling - Automated login with storage state management
• Environment configuration - Flexible configuration via environment variables
• CI/CD ready - GitHub Actions workflows for automated testing
• HTML reporting - Beautiful test reports with screenshots and traces
• Parallel execution - Optimized for fast test runs
• TypeScript support - Full type safety and IntelliSense

📋 Prerequisites

• Node.js (version 18 or higher)
• npm or yarn package manager

🛠️ Installation

1. Clone the repository

   git clone <your-repo-url>
   cd playwrightbase

2. Install dependencies

   npm install

3. Install Playwright browsers

   npx playwright install --with-deps

4. Configure environment variables

   Copy the example environment file:

   cp .env.example .env

   Update .env with your application details:

   BASE_URL=https://your-app-url.com
   LOGIN_USERNAME=your-username
   LOGIN_PASSWORD=your-password

🏃‍♂️ Usage

Running Tests

# Run all tests
npm test

# Run tests with UI mode (interactive)
npm run test:ui

# Run tests in headed mode (visible browser)
npm run test:headed

# Run only authentication tests
npm run test:auth

# Show test report
npm run report

# Generate tests with Codegen
npm run codegen

Test Configuration

The project includes two Playwright configuration files:

• playwright.config.ts - Main configuration for general tests
• playwright.auth.config.ts - Configuration for authenticated tests

Authentication Setup

The project supports automated authentication with storage state management:

1. Configure your login credentials in .env
2. Run authentication setup: npm run test:auth
3. Authentication state is saved to .auth/user.json
4. Subsequent tests can reuse this authentication state

📁 Project Structure

playwrightbase/
├── .auth/                 # Authentication storage states
├── .github/
│   └── workflows/
│       └── playwright.yml # GitHub Actions CI/CD
├── tests/
│   ├── pages/             # Page Object Models
│   │   └── LoginPage.ts   # Login page object
│   ├── auth.setup.ts      # Authentication setup
│   └── *.spec.ts          # Test files
├── .env.example           # Environment variables template
├── playwright.config.ts   # Main Playwright configuration
├── playwright.auth.config.ts # Auth-specific configuration
└── README.md

🔧 Configuration

Environment Variables

Variable	Description	Required
BASE_URL	Base URL of the application under test	Yes
LOGIN_URL	Login page URL	For auth tests
LOGIN_USERNAME	Username for authentication	For auth tests
LOGIN_PASSWORD	Password for authentication	For auth tests

Playwright Configuration Options

• Timeout: 30 seconds per test
• Global timeout: 2.5 hours for entire test suite
• Retries: 2 retries on CI, 0 locally
• Parallel execution: Tests run in parallel by default
• Traces: Collected on first retry for debugging
• Screenshots: Captured only on failure
• Videos: Retained only on failure

🚢 CI/CD

The project includes GitHub Actions workflows for automated testing:

Workflow Jobs

1. test-base - Runs general tests across all browsers
2. test-auth - Runs authenticated tests (requires secrets configuration)

Required GitHub Secrets

Configure these secrets in your GitHub repository settings:

• BASE_URL - Your application URL
• LOGIN_USERNAME - Username for authentication
• LOGIN_PASSWORD - Password for authentication

Viewing Test Reports

After each workflow run, HTML reports are uploaded as artifacts:

• playwright-report-base - General test reports
• playwright-report-auth - Authentication test reports

🧪 Writing Tests

Basic Test Structure

import { test, expect } from '@playwright/test';

test('should perform basic action', async ({ page }) => {
  await page.goto('/');
  // Your test code here
});

Using Page Objects

import { LoginPage } from '../pages/LoginPage';

test('should login successfully', async ({ page }) => {
  const loginPage = new LoginPage(page);
  await loginPage.goto();
  await loginPage.login('username', 'password');
  // Assertions
});

Authentication in Tests

For tests requiring authentication, use the storage state:

test.use({ storageState: '.auth/user.json' });

test('should access protected content', async ({ page }) => {
  await page.goto('/protected-page');
  // Test authenticated content
});

🐛 Debugging

Running Tests in Debug Mode

# Debug specific test
npx playwright test --debug tests/example.spec.ts

# Run tests in headed mode to see browser
npm run test:headed

# Use UI mode for interactive debugging
npm run test:ui

Viewing Traces

When tests fail, traces are automatically collected. View them:

npx playwright show-trace test-results/trace.zip

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run tests locally (npm test)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

📝 License

This project is licensed under the ISC License - see the LICENSE file for details.

🆘 Support

If you encounter any issues or need help:

1. Check the Playwright documentation
2. Review existing issues in the repository
3. Create a new issue with detailed information

🔄 Updating Playwright

To update Playwright to the latest version:

npm update @playwright/test
npx playwright install --with-deps

📊 Best Practices

• Use page objects for better test organization
• Leverage Playwright's auto-waiting capabilities
• Write descriptive test names and assertions
• Use data-testid attributes for reliable element selection
• Keep authentication logic separate from test logic
• Regularly update dependencies for security and features