📥 Single‑click Copyable README markdown

simple-playwright-framework

A lightweight, modular automation framework built on top of Microsoft Playwright.
It helps teams quickly bootstrap scalable UI and API test automation projects with clean architecture, reusable fixtures, and ergonomic onboarding.

Repository: GitHub

✨ Key Features

• Playwright-powered automation for browsers and APIs
• Custom fixtures for authentication, storage state, and reusable contexts
• Scenario loader for environment‑driven test data (JSON or API/DB integration)
• Provider registry for flexible login flows (username, email, or custom auth)
• Environment-aware configuration with safe defaults (prod fallback)
• Reusable helpers for file upload/download, iframe handling, and API clients
• Modern reporting with Playwright HTML, Allure, and TestRail integration
• CLI scaffolding to generate demo projects with recommended structure
• CI/CD ready with parallel safety and isolated test state
• Extensible design: plug in your own providers, loaders, or reporters

📦 Installation

1. Install Playwright

npm install --save-dev @playwright/test playwright
2. Install the framework
bash
npm install simple-playwright-framework
🚀 Create a Demo Project
Use the CLI to scaffold a ready‑to‑run project:

bash
npx init-demo-project
This generates a demo project with fixtures, config, and sample tests.

▶️ Run Tests
Navigate into the generated project:

bash
cd demo-project
npx playwright test
Run with Playwright UI runner:

bash
npx playwright test --ui
🧪 Example Test
ts
import { test, expect } from '@playwright/test';
import { scenarioLoader } from 'simple-playwright-framework';

test('login works', async ({ page }) => {
  const data = scenarioLoader(__filename).get("validLogin");
  await page.goto(data.baseUrl);
  await page.fill('#username', data.username);
  await page.fill('#password', data.password);
  await page.click('#login');
  await expect(page).toHaveURL(/dashboard/);
});
📂 Project Structure
Example demo project:

Code
demo-project
│
├── tests
│   └── login.spec.ts
│
├── pages
│   └── login.page.ts
│
├── utils
│   └── apiClient.ts
│
├── config
│   └── environments.ts
│
├── auth
│   └── storageState.json
│
└── playwright.config.ts
🌍 Environment Configuration
ts
export const environments = {
  dev: { baseUrl: "https://dev.example.com" },
  qa:  { baseUrl: "https://qa.example.com" },
  prod:{ baseUrl: "https://prod.example.com" }
};
Run against different environments without changing test logic.

📊 Reporting
Supports:

Playwright HTML reports

Allure reports

TestRail integration

Generate Playwright report:

bash
npx playwright show-report
🛠 Challenges & Solutions
Compiled JS confusion → moved output to dist and enforced root‑level exports

Demo projects bypassing fixtures → documented imports from framework only

Scenario injection limits → iterated scenarios in test bodies, reporting adapted

Environment defaults missing → added safe fallback (prod)

Dependency resolution issues → onboarding scripts install required packages

Report formatting limitations → modernized with inline CSS and branded colors

Auth provider rigidity → introduced provider registry for flexible login flows

Parallel safety concerns → kept state test‑scoped, avoided global mutation

Demo project scaffolding risks → added warnings and safe file writes

🤝 Contributing
Contributions are welcome.

Fork the repository

Create a feature branch

Commit your changes

Submit a pull request

Please ensure that code changes include appropriate tests and follow existing coding conventions.

📜 License
MIT License

👤 Author
Developed by Udayakumar  
GitHub: https://github.com/Udayakumarg

Code

---

👉 Just copy everything above into a file named `README.md` in your repo.  
If you’d like, I can also prepare a **shorter npm landing page version** (featur