Simple Playwright Framework

Common errors

• Error: Cannot find module 'simple-playwright-framework' or its corresponding type declarations.

  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.
  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.

• TypeError: scenarioLoader is not a function

  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.
  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`.

• Playwright test run failed: No tests found

  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.
  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'`).

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install simple-playwright-framework npm
• yarn add simple-playwright-framework yarn
• pnpm add simple-playwright-framework pnpm

Imports

• scenarioLoader
  wrong:

  const scenarioLoader = require('simple-playwright-framework').scenarioLoader;

  correct:

  import { scenarioLoader } from 'simple-playwright-framework';

  The framework is ESM-first and ships TypeScript types. Prefer named ESM imports. CommonJS `require` will not work directly without transpilation.
• initDemoProject

  npx init-demo-project

  This is a CLI command to scaffold a new project, invoked via `npx`, not a direct importable symbol in JavaScript/TypeScript.
• test, expect (Playwright base)

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

  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).

Quickstart

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`.

npm install --save-dev @playwright/test playwright
npm install simple-playwright-framework

npx init-demo-project

# Navigate into the generated project
cd demo-project

# Example test from the generated project (e.g., tests/login.spec.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/);
// });

# Run tests
npx playwright test

# Or run tests with Playwright UI runner
npx playwright test --ui