{"id":12031,"library":"simple-playwright-framework","title":"Simple Playwright Framework","description":"The `simple-playwright-framework` (current version 0.0.33) is a lightweight and modular TypeScript-based automation framework built on Microsoft Playwright. It aims to accelerate the setup of scalable UI and API test automation projects by providing a clean architecture, reusable fixtures, and streamlined onboarding processes. Key features include custom Playwright fixtures for authentication and state management, a `scenarioLoader` for environment-driven test data (supporting JSON, API, or DB integration), and a flexible provider registry for various authentication flows. It supports environment-aware configuration, offers reusable helpers for common test scenarios, and integrates with modern reporting tools like Playwright HTML, Allure, and TestRail. The framework also includes a CLI scaffolding tool (`npx init-demo-project`) to generate demo projects with recommended structures, promoting CI/CD readiness through parallel safety and isolated test states. Given its pre-1.0 version, the release cadence is likely agile, with frequent updates that may include API adjustments.","status":"active","version":"0.0.33","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","playwright","framework","testing","automation","fixtures","typescript"],"install":[{"cmd":"npm install simple-playwright-framework","lang":"bash","label":"npm"},{"cmd":"yarn add simple-playwright-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add simple-playwright-framework","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Playwright testing library, required for test execution and assertions.","package":"@playwright/test","optional":false},{"reason":"Playwright browser automation library, providing browser contexts and page interactions.","package":"playwright","optional":false}],"imports":[{"note":"The framework is ESM-first and ships TypeScript types. Prefer named ESM imports. CommonJS `require` will not work directly without transpilation.","wrong":"const scenarioLoader = require('simple-playwright-framework').scenarioLoader;","symbol":"scenarioLoader","correct":"import { scenarioLoader } from 'simple-playwright-framework';"},{"note":"This is a CLI command to scaffold a new project, invoked via `npx`, not a direct importable symbol in JavaScript/TypeScript.","symbol":"initDemoProject","correct":"npx init-demo-project"},{"note":"While `simple-playwright-framework` provides custom fixtures, the base `test` and `expect` utilities are typically imported directly from `@playwright/test` unless the framework explicitly exports its own augmented `test` object (which is not shown here).","symbol":"test, expect (Playwright base)","correct":"import { test, expect } from '@playwright/test';"}],"quickstart":{"code":"npm install --save-dev @playwright/test playwright\nnpm install simple-playwright-framework\n\nnpx init-demo-project\n\n# Navigate into the generated project\ncd demo-project\n\n# Example test from the generated project (e.g., tests/login.spec.ts)\n// import { test, expect } from '@playwright/test';\n// import { scenarioLoader } from 'simple-playwright-framework';\n\n// test('login works', async ({ page }) => {\n//   const data = scenarioLoader(__filename).get(\"validLogin\");\n//   await page.goto(data.baseUrl);\n//   await page.fill('#username', data.username);\n//   await page.fill('#password', data.password);\n//   await page.click('#login');\n//   await expect(page).toHaveURL(/dashboard/);\n// });\n\n# Run tests\nnpx playwright test\n\n# Or run tests with Playwright UI runner\nnpx playwright test --ui","lang":"typescript","description":"Demonstrates the initial setup by installing dependencies, scaffolding a new project using the CLI, navigating into it, and then running the generated example Playwright tests using the framework's `scenarioLoader`."},"warnings":[{"fix":"Ensure your `tsconfig.json` and build tools correctly resolve modules from `simple-playwright-framework`. Check the latest documentation or scaffold a new project (`npx init-demo-project`) to see the correct import paths and configurations.","message":"Earlier versions experienced 'Compiled JS confusion' which led to module resolution changes, moving output to 'dist' and enforcing root-level exports. This likely necessitated updating import paths or build configurations for users upgrading from older pre-1.0 versions.","severity":"breaking","affected_versions":"<0.0.33"},{"fix":"Always refer to the framework's documentation and the generated `playwright.config.ts` from the `init-demo-project` CLI for how to properly extend Playwright's base `test` object and import framework utilities.","message":"The framework emphasizes correct usage of its custom fixtures and helpers. Users might inadvertently bypass these by importing Playwright's base `test` object or not properly configuring `playwright.config.ts` to utilize framework-provided extensions.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Exercise caution when upgrading. Review release notes carefully for any breaking changes and pin exact versions in `package.json` for critical projects. Perform thorough regression testing after any update.","message":"As a pre-1.0 (0.0.x) package, `simple-playwright-framework` does not strictly adhere to Semantic Versioning. Minor or even patch releases may introduce breaking changes to the API without a major version increment.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure all necessary test state is initialized within individual tests or `beforeEach` hooks provided by Playwright, avoiding mutable global variables or shared resources that are not properly isolated for parallel execution.","message":"The framework is designed for parallel safety by advocating 'test-scoped' state and avoiding 'global mutation'. Improper handling of shared state across tests or Playwright workers can lead to flaky or inconsistent test results.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install simple-playwright-framework`. Verify your `tsconfig.json`'s `moduleResolution` and `baseUrl`/`paths` settings are compatible with an ESM-first package. If using CommonJS, ensure you are using dynamic `import()` or configuring your build tools for ESM compatibility.","cause":"The package is either not installed, or your module resolver (TypeScript compiler, bundler, or Node.js runtime) cannot locate the package correctly. This was a known issue in earlier versions related to module bundling.","error":"Error: Cannot find module 'simple-playwright-framework' or its corresponding type declarations."},{"fix":"Ensure you are using the correct ESM import syntax: `import { scenarioLoader } from 'simple-playwright-framework';`. Avoid CommonJS `require` statements directly. Verify the package is installed and at a version that exports `scenarioLoader`.","cause":"This error typically indicates that `scenarioLoader` was not correctly imported or is not available from the imported module. This can occur with incorrect `require` syntax in CommonJS contexts or if module bundling/tree-shaking inadvertently removes the export.","error":"TypeError: scenarioLoader is not a function"},{"fix":"After scaffolding, navigate into the generated `demo-project` directory (e.g., `cd demo-project`). Confirm that your `playwright.config.ts` has a `testMatch` property that correctly identifies your test files (e.g., `testMatch: '**/*.spec.ts'`).","cause":"This occurs when `playwright` cannot locate any test files. This might be due to running the `npx playwright test` command from an incorrect directory (not the project root) or if the `playwright.config.ts` file has an incorrect `testMatch` pattern.","error":"Playwright test run failed: No tests found"}],"ecosystem":"npm"}