Playwright Agentic Framework v2

A production-ready Playwright + TypeScript framework foundation built with a:

• framework-first
• manifest-driven
• validator-governed
• spec-driven
• agent-assisted

architecture.

Design principles

1. Framework owns structure

Agents never control:

• folder structure
• naming conventions
• fixture boundaries
• auth model
• environment resolution
• registry schema
• governance rules
• healing limits

2. Manifest before generation

All inputs are normalized into deterministic manifests before code generation.

3. Validation before execution

Generated code is blocked if it violates framework rules.

4. Healing is constrained

Healers can fix only approved test-side issues.

5. Traceability is mandatory

Every generated test and artifact must map back to a source.

Target practice systems

• Primary UI: Test Automation Playground at https://apptesting.pl/
• Primary API: DummyJSON at https://dummyjson.com

Supported source inputs

• OpenAPI YAML / JSON
• story.md
• Jira markdown / normalized export
• user instruction snapshots
• screenshots and flow notes

Main flow

1. Collect inputs in specs/
2. Normalize to manifests in src/ai/manifests/
3. Plan changes by comparing manifests, registry, and target files
4. Generate code using templates
5. Sync registry
6. Validate manifests + registry + generated code
7. Execute by layer, tag, sourceRef, or scenarioId
8. Record artifacts and registry updates
9. Heal only approved issues

Quick start

npm install
npx playwright install --with-deps
cp .env.example .env
cp .env.local.example .env.local
npm run typecheck
npm run validate:manifests
npm run registry:check
npm run test:smoke

Environment config

Runtime config is loaded from .env plus an environment-specific file:

• TEST_ENV=local loads .env.local
• TEST_ENV=qa loads .env.qa
• TEST_ENV=stage loads .env.stage

Use .env for shared defaults and .env.<TEST_ENV> for environment-specific URLs, credentials, and test data. Shell or CI variables still take precedence over file values.

Examples:

TEST_ENV=qa npm run test:api
npm run agentic -- --action=run --mode=ui --env=stage
npm run agentic -- --action=run --mode=api --test-env=qa

NPM scripts

• npm run test
• npm run test:smoke
• npm run test:ui
• npm run test:api
• npm run test:hybrid
• npm run agentic -- --action=plan --mode=ui --input-type=story --strategy=plan-only --env=local
• npm run agentic -- --action=generate --mode=api --input-type=openapi --strategy=extend --env=qa
• npm run agentic -- --action=normalize --mode=ui --input-type=jira --env=local
• npm run agentic -- --action=normalize --mode=ui --input-type=user-input --env=local
• npm run agentic -- --action=normalize --mode=ui --input-type=screenshot --env=local
• npm run agentic -- --action=promote --mode=ui --input-type=story --strategy=auto --env=local
• npm run agentic -- --action=run --mode=ui --env=local
• npm run agentic -- --action=classify --mode=ui --env=local
• npm run agentic -- --action=heal --mode=ui --env=local
• npm run agentic -- --action=flakes --mode=ui --env=local
• npm run agentic -- --action=analytics --mode=ui --env=local
• npm run agentic -- --action=security --env=local
• npm run agentic -- --action=full --mode=smoke --input-type=openapi --strategy=auto --env=local
• npm run auth:setup
• npm run validate:manifests
• npm run plan:changes
• npm run registry:check
• npm run validate:framework
• npm run validate:secrets
• npm run validate
• npm run artifacts:init
• npm run generate:sample

What v2 adds

• UI wrappers for forms, interactions, widgets, tables, alerts, frames/windows, files, dynamic content, and shadow DOM
• DummyJSON API wrappers for auth, users, products, carts, and posts
• executable governance checks for schema validity, traceability, folder placement, weak assertions, hard waits, hardcoded URLs/secrets, and fixture boundaries
• stronger registry schema
• sample manifest schema
• sample normalized sources
• artifact initialization script
• OpenAPI normalization stub
• template-based generator for manifest-backed Playwright specs
• governance docs
• CI pipeline
• UI/API/hybrid skeletons