simple-playwright-framework 0.0.15 → 0.0.17

package/README.md

@@ -1,183 +1,160 @@
+📥 Single‑click Copyable README
+markdown
 # simple-playwright-framework
 
-![npm version](https://img.shields.io/npm/v/simple-playwright-framework)
-![npm
-downloads](https://img.shields.io/npm/dm/simple-playwright-framework)
-![license](https://img.shields.io/npm/l/simple-playwright-framework)
-![node](https://img.shields.io/node/v/simple-playwright-framework)
-![playwright](https://img.shields.io/badge/Playwright-supported-45ba63?logo=playwright)
+![npm version](https://img.shields.io/npm/v/simple-playwright-framework)  
+![npm downloads](https://img.shields.io/npm/dm/simple-playwright-framework)  
+![license](https://img.shields.io/npm/l/simple-playwright-framework)  
+![node](https://img.shields.io/node/v/simple-playwright-framework)  
+![playwright](https://img.shields.io/badge/Playwright-supported-45ba63?logo=playwright)  
 ![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)
 
-A lightweight and modular automation framework built on top of
-**Microsoft Playwright** to help teams quickly bootstrap scalable UI and
-API test automation projects.
+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**.
 
-The framework focuses on simplicity, maintainability, and developer
-ergonomics while following modern test automation best practices.
+Repository: [GitHub](https://github.com/Udayakumarg/simpleplaywrightframework)
 
-Repository: https://github.com/Udayakumarg/simpleplaywrightframework
+---
 
-------------------------------------------------------------------------
+## ✨ Key Features
 
-## 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
 
--   Playwright-powered end‑to‑end browser automation
--   Clean and scalable project structure
--   Environment-aware configuration
--   Reusable authentication sessions
--   UI and API testing support
--   File upload and download helpers
--   CLI project scaffolding
--   CI/CD ready architecture
--   Easy integration with reporting tools such as Allure and TestRail
+---
 
-------------------------------------------------------------------------
-
-## Installation
+## 📦 Installation
 
 ### 1. Install Playwright
-
-``` bash
+```bash
 npm install --save-dev @playwright/test playwright
-```
-
-### 2. Install the framework
-
-``` bash
+2. Install the framework
+bash
 npm install simple-playwright-framework
-```
-
-------------------------------------------------------------------------
-
-## Create a Demo Project
-
-Use the CLI to generate a ready‑to‑run project:
+🚀 Create a Demo Project
+Use the CLI to scaffold a ready‑to‑run project:
 
-``` bash
+bash
 npx init-demo-project
-```
+This generates a demo project with fixtures, config, and sample tests.
 
-This command scaffolds a demo project with the recommended structure.
+▶️ Run Tests
+Navigate into the generated project:
 
-------------------------------------------------------------------------
-
-## Run Tests
-
-Navigate into the generated project and run:
-
-``` bash
+bash
 cd demo-project
 npx playwright test
-```
-
-Run tests with the Playwright UI runner:
+Run with Playwright UI runner:
 
-``` bash
+bash
 npx playwright test --ui
-```
-
-------------------------------------------------------------------------
-
-## Example Test
-
-``` ts
+🧪 Example Test
+ts
 import { test, expect } from '@playwright/test';
-
-test('homepage loads', async ({ page }) => {
-  await page.goto('https://example.com');
-  await expect(page).toHaveTitle(/Example/);
+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 project generated by the framework:
+📂 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.
 
-    demo-project
-    │
-    ├── tests
-    │   └── example.spec.ts
-    │
-    ├── pages
-    │   └── login.page.ts
-    │
-    ├── utils
-    │   └── apiClient.ts
-    │
-    ├── config
-    │   └── environments.ts
-    │
-    ├── auth
-    │   └── storageState.json
-    │
-    └── playwright.config.ts
+📊 Reporting
+Supports:
 
-------------------------------------------------------------------------
+Playwright HTML reports
 
-## Environment Configuration
+Allure reports
 
-Multiple environments can be configured easily.
+TestRail integration
 
-Example:
+Generate Playwright report:
 
-``` ts
-export const environments = {
-  dev: {
-    baseUrl: "https://dev.example.com"
-  },
-  qa: {
-    baseUrl: "https://qa.example.com"
-  }
-};
-```
-
-This allows running tests across different deployment environments
-without changing test logic.
+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
 
-## Reporting
+Scenario injection limits → iterated scenarios in test bodies, reporting adapted
 
-The framework works seamlessly with:
+Environment defaults missing → added safe fallback (prod)
 
--   Playwright HTML reports
--   Allure reports
--   TestRail integrations
+Dependency resolution issues → onboarding scripts install required packages
 
-Generate the Playwright report:
+Report formatting limitations → modernized with inline CSS and branded colors
 
-``` bash
-npx playwright show-report
-```
+Auth provider rigidity → introduced provider registry for flexible login flows
 
-------------------------------------------------------------------------
+Parallel safety concerns → kept state test‑scoped, avoided global mutation
 
-## Contributing
+Demo project scaffolding risks → added warnings and safe file writes
 
+🤝 Contributing
 Contributions are welcome.
 
-If you would like to contribute:
+Fork the repository
 
-1.  Fork the repository
-2.  Create a feature branch
-3.  Commit your changes
-4.  Submit a pull request
+Create a feature branch
 
-Please ensure that code changes include appropriate tests and follow
-existing coding conventions.
+Commit your changes
 
-------------------------------------------------------------------------
+Submit a pull request
 
-## License
+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
 
-## Author
+Code
 
-Developed by Udayakumar
+---
 
-GitHub: https://github.com/Udayakumarg
+👉 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

package/dist/fixtures/data.fixture.js

@@ -10,7 +10,7 @@ exports.dataFixture = {
         let td;
         try {
             td = (0, data_loader_1.loadTestData)(testInfo, envName);
-            console.log("Loaded test data:", td, "Type:", Array.isArray(td) ? "array" : typeof td);
+            //console.log("Loaded test data:", td, "Type:", Array.isArray(td) ? "array" : typeof td);
         }
         catch (err) {
             console.error(`❌ loadTestData threw for env '${envName}':`, err);

package/dist/fixtures/index.d.ts

@@ -1,6 +1,7 @@
 import { Page } from "@playwright/test";
 import { Fixtures } from "../types/fixtures";
 export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & Fixtures & {
+    pc: Record<string, any>;
     authStore: (page: Page, creds: {
         username: string;
         password: string;

package/dist/fixtures/index.js

@@ -1,4 +1,12 @@
 "use strict";
+// ════════════════════════════════════════════════════════════════
+// framework/src/fixtures/index.ts
+//
+// MODIFIED — added projectConfigFixture alongside existing fixtures.
+// Only this block is new:
+//   ...projectConfigFixture,
+// Everything else is unchanged from your original file.
+// ════════════════════════════════════════════════════════════════
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -19,13 +27,15 @@ const test_1 = require("@playwright/test");
 const envConfig_fixture_1 = require("./envConfig.fixture");
 const data_fixture_1 = require("./data.fixture");
 const testrail_fixture_1 = require("./testrail.fixture");
-const initAuthSession_1 = require("../utils/auth-session/initAuthSession");
 const file_fixture_1 = require("./file.fixture");
+const projectConfig_fixture_1 = require("./projectConfig.fixture"); // ← NEW
+const initAuthSession_1 = require("../utils/auth-session/initAuthSession");
 exports.test = test_1.test.extend({
     ...envConfig_fixture_1.envConfigFixture,
     ...data_fixture_1.dataFixture,
     ...testrail_fixture_1.testrailFixture,
     ...file_fixture_1.fileFixture,
+    ...projectConfig_fixture_1.projectConfigFixture, // ← NEW
     authStore: async ({ envConfig }, use) => {
         await use(async (page, creds, providerRegistry) => {
             if (!envConfig.authStorage) {
@@ -37,4 +47,4 @@ exports.test = test_1.test.extend({
 });
 var test_2 = require("@playwright/test");
 Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return test_2.expect; } });
-__exportStar(require("../loaders/scenario.loader"), exports); // ✅ keep scenarioLoader export
+__exportStar(require("../loaders/scenario.loader"), exports); // ← NEW

package/dist/fixtures/projectConfig.fixture.d.ts

@@ -0,0 +1,6 @@
+import { Page } from "@playwright/test";
+export declare const projectConfigFixture: {
+    pc: ({ page }: {
+        page: Page;
+    }, use: (config: Record<string, any>) => Promise<void>) => Promise<void>;
+};

package/dist/fixtures/projectConfig.fixture.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectConfigFixture = void 0;
+const projectConfig_loader_1 = require("../loaders/projectConfig.loader");
+exports.projectConfigFixture = {
+    pc: async ({ page }, use) => {
+        const config = (0, projectConfig_loader_1.loadProjectConfig)();
+        await use(config);
+    },
+};

package/dist/loaders/projectConfig.loader.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Loads and returns the contents of config/projectConfig.json
+ * as a plain object. The shape is defined by each project —
+ * the framework imposes no type constraints here.
+ *
+ * @returns  Plain object from projectConfig.json
+ * @throws   If the file is missing or contains invalid JSON
+ */
+export declare function loadProjectConfig(): Record<string, any>;

package/dist/loaders/projectConfig.loader.js

@@ -0,0 +1,41 @@
+"use strict";
+// ════════════════════════════════════════════════════════════════
+// framework/src/loaders/projectConfig.loader.ts
+//
+// Loads projectConfig.json from the consuming project's
+// config/ directory. Follows the exact same pattern as
+// envConfig.loader.ts — flat JSON, no env nesting.
+//
+// projectConfig.json is for project-wide constants that are
+// not environment-specific (threshold, schema paths, etc).
+// Anything env-specific belongs in environments.json instead.
+// ════════════════════════════════════════════════════════════════
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadProjectConfig = loadProjectConfig;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Loads and returns the contents of config/projectConfig.json
+ * as a plain object. The shape is defined by each project —
+ * the framework imposes no type constraints here.
+ *
+ * @returns  Plain object from projectConfig.json
+ * @throws   If the file is missing or contains invalid JSON
+ */
+function loadProjectConfig() {
+    const configPath = path_1.default.join(process.cwd(), "config", "projectConfig.json");
+    if (!fs_1.default.existsSync(configPath)) {
+        throw new Error(`❌ projectConfig.json not found at ${configPath}\n` +
+            `   Create config/projectConfig.json in your project root.`);
+    }
+    const raw = fs_1.default.readFileSync(configPath, "utf-8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`❌ projectConfig.json contains invalid JSON at ${configPath}\n${e}`);
+    }
+}

package/dist/types/env.d.ts

@@ -1,5 +1,6 @@
 import type { AuthStorageConfig } from "./auth";
 export interface EnvConfig {
+    openAiApiKey: string;
     baseUrl: string;
     apiUrl?: string;
     db?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-playwright-framework",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "A modular Playwright framework with fixtures, loaders, and demo scaffolding.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",