🎭 ngx-playwright-schematics

An enterprise-grade Angular Schematics package that automates setting up and scaffolding a production-ready Playwright E2E testing architecture into any Angular application.

⚡ Quick Start

In any Angular project root directory, simply run:

ng add ngx-playwright-schematics

Or run via generator:

ng g ngx-playwright-schematics:ng-add

CLI Options

Option	Type	Default	Description
`--project`	`string`	(default project)	Specific project name in `angular.json`
`--installBrowsers`	`boolean`	`false`	Automatically install Playwright browser binaries
`--overwrite`	`boolean`	`true`	Safely resolve conflicts and update existing configuration

Example with options:

ng add ngx-playwright-schematics --project=my-app --installBrowsers=true --overwrite=true

🔄 Schematic Execution Lifecycle

When you run ng add ngx-playwright-schematics, the schematic executes an idempotent, conflict-resilient pipeline:

flowchart TD
    START(["🚀 ng add ngx-playwright-schematics"]) --> INSPECT["🔍 Inspect Workspace Environment<br/>(angular.json, package.json, eslint, .gitignore)"]

    INSPECT --> ANGULAR["1️⃣ Configure angular.json<br/>- Add architect.e2e builder<br/>- Register schematic collections"]
    INSPECT --> PKG["2️⃣ Merge package.json<br/>- Inject 19 E2E scripts<br/>- Add zod, @playwright/test, allure, tsx"]
    INSPECT --> ESLINT["3️⃣ Update eslint.config.mjs<br/>- Inject strict boundary rule<br/>(blocks src/ imports in e2e/)"]
    INSPECT --> GIT["4️⃣ Update .gitignore<br/>- Ignore test-results, reports, artifacts"]

    ANGULAR & PKG & ESLINT & GIT --> SCAFFOLD["5️⃣ Deploy Blueprint Files (39 Files)<br/>- Component Objects & Page Objects<br/>- Modular Fixtures (mergeTests)<br/>- Zod Data Factory & Interceptors<br/>- GitHub Actions CI Matrix<br/>- Observability Scripts"]

    SCAFFOLD --> CONFLICT{"Conflict Detected?"}
    CONFLICT -- Yes --> RESOLVE["🛡️ Auto-Resolve with MergeStrategy.Overwrite<br/>(Gracefully update without halting)"]
    CONFLICT -- No --> TASKS
    RESOLVE --> TASKS["6️⃣ Schedule Post-Tasks<br/>- NodePackageInstallTask (npm install)<br/>- Optional Browser Binaries Download"]

    TASKS --> DONE(["✅ Setup Complete: npm run e2e"])

🏛️ Scaffolded Enterprise Architecture

The blueprint implements industry best practices for enterprise testing at scale:

graph TD
    subgraph "1. Playwright Test Runner & Configuration"
        CONFIG["playwright.config.ts<br/>- Cross-Platform Snapshot Templates<br/>- Session Caching (storageState: default.json)<br/>- Multi-Browser Projects (Chrome, Firefox)<br/>- Automated webServer Lifecycle<br/>- Multi-Reporters: HTML, Allure, JUnit, JSON, Blob"]
    end

    subgraph "2. Fixture Composition Layer (@fixtures/index)"
        MERGE["mergeTests() Composition Engine"]
        F_COM["componentFixtures<br/>(ToastComponent, LoaderComponent,<br/>ModalComponent, HeaderComponent)"]
        F_PAGE["pageFixtures<br/>(HomePage, LoginPage, Routes)"]
        F_API["apiFixtures<br/>(APIClient Helper)"]
        F_DATA["dataFactoryFixture<br/>(Zod Schemas, Synthetic Entity Lifecycle,<br/>Network Fault & Latency Simulation)"]
        F_A11Y["a11yFixture<br/>(AxeBuilder WCAG 2.2 AA Auditing)"]
        F_TEL["telemetryFixture<br/>(W3C Traceparent Header Injection)"]
        F_CONST["customFixtures<br/>(Application Constants)"]

        MERGE --> F_COM & F_PAGE & F_API & F_DATA & F_A11Y & F_TEL & F_CONST
    end

    subgraph "3. Application Runtime (Decoupled)"
        APP["Angular Application (src/)"]
        INTERCEPTOR["apiContractInterceptor<br/>(HTTP Interceptor + Zod safeParse<br/>Live Drift Telemetry)"]
        APP --> INTERCEPTOR
    end

    subgraph "4. CI/CD Matrix & Observability"
        CI_MATRIX["GitHub Actions Sharding<br/>(4 Shards Matrix Execution)"]
        BLOB_MERGE["Blob Report Aggregation"]
        DASHBOARD["Interactive HTML Dashboard<br/>+ P95 Metrics Recorder"]

        CI_MATRIX --> BLOB_MERGE --> DASHBOARD
    end

    CONFIG --> MERGE
    F_DATA -.->|"Validates Contracts"| INTERCEPTOR
    CONFIG --> CI_MATRIX

🧩 Architectural Pillars

1. Strict Source Decoupling (Rule 1)

E2E test suites (e2e/) remain completely isolated from application source code (src/). An ESLint no-restricted-imports rule is automatically injected to prevent leaking internal Angular implementations into test suites.

2. Component Object Model over BasePage Inheritance (Rule 2)

Avoid monolithic inheritance chains. UI widgets are encapsulated as standalone Component Objects and composed directly into fixtures:

import { test, expect } from '@fixtures/index';

test('verify user dashboard', { tag: ['@smoke', '@ui'] }, async ({ homePage, toastComponent }) => {
  await homePage.visit();
  await toastComponent.verifyNoFatalErrors();
});

3. Modular Fixture Slicing via `mergeTests()` (Rule 3)

Fixtures are sliced into focused domain concerns (componentFixtures, pageFixtures, apiFixtures, a11yFixture, dataFactoryFixture, telemetryFixture) and combined in @fixtures/index.

import { mergeTests } from '@playwright/test';
export const test = mergeTests(
  componentFixtures,
  pageFixtures,
  apiFixtures,
  a11yFixture,
  dataFactoryFixture,
  telemetryFixture
);

4. Pre-Cached Authentication (`storageState`) (Rule 4)

User authentication is executed once during global setup (auth.setup.ts) and cached to e2e/auth/default.json. Browser workers reuse this cached session instantly. Unauthenticated flows opt out with:

test.use({ storageState: { cookies: [], origins: [] } });

5. Cross-Platform Snapshot Consistency (Rule 5)

snapshotPathTemplate formats screenshots deterministically ({snapshotDir}/{arg}-{projectName}-{platform}{ext}), preventing visual mismatch failures across macOS local dev and Linux CI runners.

6. Angular HTTP Contract Interceptor (Rule 8)

An Angular HttpInterceptorFn validates all live HTTP responses against Zod schemas in real-time. Contract drifts are reported to browser console / telemetry without breaking the UI.

🛠️ Command Reference

After running ng add ngx-playwright-schematics, your package.json includes:

Script	Command	Purpose
`npm run e2e`	`ng e2e`	Full E2E suite headless with auto-started dev server
`npm run e2e:smoke`	`playwright test --grep @smoke`	P0 fast smoke suite for quick PR feedback
`npm run e2e:regression`	`playwright test --grep @regression`	Complete regression test suite
`npm run e2e:a11y`	`playwright test --grep @a11y`	Automated WCAG 2.2 AA accessibility audit scans
`npm run e2e:visual`	`playwright test --grep @visual`	Visual snapshot regression tests
`npm run e2e:api`	`playwright test --grep @api`	Zod API contract and fault resilience specs
`npm run e2e:ui`	`playwright test --ui`	Interactive UI Mode with time-travel & DOM snapshots
`npm run e2e:headed`	`playwright test --headed`	Run tests in a visible browser window
`npm run e2e:debug`	`playwright test --debug`	Step-by-step Playwright Inspector debugging
`npm run e2e:report`	`playwright show-report artifacts/playwright-report`	Open Playwright HTML report
`npm run allure:report`	`npm run allure:generate && allure open ...`	Generate and view Allure report
`npm run insights:all`	`tsx scripts/...`	Record execution metrics, P95 duration, and build HTML dashboard
`npm run lint:e2e`	`npx eslint e2e`	Enforce E2E source decoupling guardrails

📁 Scaffolded File Tree

.
├── .github/
│   └── workflows/
│       ├── e2e.yml                       # Pull request CI workflow
│       └── e2e-matrix.yml                # 4-shard matrix execution & report merger
├── e2e/
│   ├── auth/
│   │   └── default.json                  # Pre-cached session storageState
│   ├── components/
│   │   ├── header.component.ts           # Header / navbar widget
│   │   ├── loader.component.ts           # Loading spinners & progress bars
│   │   ├── modal.component.ts            # Dialog modals (role="dialog")
│   │   └── toast.component.ts            # Status toasts & alerts
│   ├── fixtures/
│   │   ├── a11yFixture.ts                # AxeBuilder accessibility fixture
│   │   ├── apiFixtures.ts                # API client fixture
│   │   ├── componentFixtures.ts          # COM widget fixtures
│   │   ├── constants.ts                  # App titles & timeouts
│   │   ├── creds.ts                      # Credentials manager
│   │   ├── dataFactoryFixture.ts         # Zod schemas, synthetic lifecycle, network faults
│   │   ├── fixtures.ts                   # Custom test data fixtures
│   │   ├── index.ts                      # Unified mergeTests export
│   │   ├── pageFixtures.ts               # Page Object fixtures
│   │   └── telemetryFixture.ts           # W3C traceparent header injection
│   ├── global/
│   │   ├── global-setup.ts               # Global setup hook
│   │   └── global-teardown.ts            # Global teardown hook
│   ├── helpers/
│   │   ├── apiClient.ts                  # Isolated API client
│   │   └── utils.ts                      # Playwright helper utilities
│   ├── pages/
│   │   ├── homePage.ts                   # Home Page Object
│   │   ├── loginPage.ts                  # Login Page Object
│   │   ├── routes.ts                     # Central route dictionary
│   │   └── testExtender.ts               # Test extender re-export
│   ├── specs/
│   │   ├── a11y.spec.ts                  # WCAG 2.2 AA accessibility spec
│   │   ├── api-contract.spec.ts          # Zod contract validation & fault specs
│   │   ├── app.spec.ts                   # Core application specs
│   │   ├── auth.setup.ts                 # Pre-cached authentication setup
│   │   └── visual.spec.ts                # Visual snapshot regression specs
│   └── tsconfig.json                     # E2E TypeScript paths configuration
├── scripts/
│   ├── lib/
│   │   └── parseResults.ts               # Playwright JSON report parser
│   ├── html-reporter.ts                  # Interactive HTML execution dashboard
│   ├── markdown-summary.ts               # GitHub step summary markdown report
│   ├── metrics-recorder.ts               # Daily test metrics & P95 duration recorder
│   └── tsconfig.json                     # Scripts TypeScript configuration
├── src/
│   └── app/
│       └── core/
│           └── interceptors/
│               └── api-contract.interceptor.ts  # Angular HTTP Zod Contract Interceptor
├── eslint.config.mjs                     # Decoupled ESLint configuration
└── playwright.config.ts                  # Enterprise Playwright configuration

📄 License

Apache-2.0

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
scripts		scripts
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
collection.json		collection.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

🎭 ngx-playwright-schematics

⚡ Quick Start

CLI Options

🔄 Schematic Execution Lifecycle

🏛️ Scaffolded Enterprise Architecture

🧩 Architectural Pillars

1. Strict Source Decoupling (Rule 1)

2. Component Object Model over BasePage Inheritance (Rule 2)

3. Modular Fixture Slicing via `mergeTests()` (Rule 3)

4. Pre-Cached Authentication (`storageState`) (Rule 4)

5. Cross-Platform Snapshot Consistency (Rule 5)

6. Angular HTTP Contract Interceptor (Rule 8)

🛠️ Command Reference

📁 Scaffolded File Tree

📄 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🎭 ngx-playwright-schematics

⚡ Quick Start

CLI Options

🔄 Schematic Execution Lifecycle

🏛️ Scaffolded Enterprise Architecture

🧩 Architectural Pillars

1. Strict Source Decoupling (Rule 1)

2. Component Object Model over BasePage Inheritance (Rule 2)

3. Modular Fixture Slicing via mergeTests() (Rule 3)

4. Pre-Cached Authentication (storageState) (Rule 4)

5. Cross-Platform Snapshot Consistency (Rule 5)

6. Angular HTTP Contract Interceptor (Rule 8)

🛠️ Command Reference

📁 Scaffolded File Tree

📄 License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

3. Modular Fixture Slicing via `mergeTests()` (Rule 3)

4. Pre-Cached Authentication (`storageState`) (Rule 4)