docs(ai-docs): playwright ai docs added (#623)

Author: rsarika

AGENTS.md

@@ -4,7 +4,7 @@
 
 This is the main orchestrator for AI assistants working on this repository. It routes you to the correct templates and documentation based on the developer's task.
 
-**For every developer request:** (1) Identify task type (A–E below). (2) If the work is in an existing package or widget, load that scope's ai-docs (see [Package and widget ai-docs reference](#package-and-widget-ai-docs-reference)) and follow its AGENTS.md. (3) Open the template for that type and complete its mandatory pre-steps (see [Mandatory pre-steps by task type](#mandatory-pre-steps-by-task-type)). (4) Then follow the rest of this guide and the template.
+**For every developer request:** (1) Identify task type (A–F below). (2) If the work is in an existing package, widget, or test framework scope, load that scope's ai-docs (see [Package and widget ai-docs reference](#package-and-widget-ai-docs-reference)) and follow its AGENTS.md. (3) Open the template for that type and complete its mandatory pre-steps (see [Mandatory pre-steps by task type](#mandatory-pre-steps-by-task-type)). (4) Then follow the rest of this guide and the template.
 
 ---
 
@@ -55,7 +55,13 @@ If the developer's message contains multiple distinct task types (for example, "
 **E. Understanding Architecture**
 - Developer needs to understand how something works
 - **Read:** That scope's `ai-docs/AGENTS.md` (usage) and `ai-docs/ARCHITECTURE.md` (technical details); use [Package and widget ai-docs reference](#package-and-widget-ai-docs-reference) to find the path.
-- **Available for:** station-login, user-state, store, cc-components, cc-widgets, ui-logging, test-fixtures; for task package use per-widget ai-docs (CallControl, IncomingTask, OutdialCall, TaskList).
+- **Available for:** station-login, user-state, store, cc-components, cc-widgets, ui-logging, test-fixtures, playwright; for task package use per-widget ai-docs (CallControl, IncomingTask, OutdialCall, TaskList).
+
+**F. Playwright E2E Test Work**
+- Developer wants to add/update/stabilize Playwright tests, suites, sets, or test framework docs
+- **Route to:** [templates/playwright/00-master.md](./ai-docs/templates/playwright/00-master.md)
+- **Follow:** Playwright template workflow (pre-questions → implementation → validation)
+- **⚠️ MANDATORY FIRST STEP:** Complete pre-questions in [templates/playwright/01-pre-questions.md](./ai-docs/templates/playwright/01-pre-questions.md)
 
 ---
 
@@ -169,6 +175,7 @@ Before generating or changing any code, you MUST complete the **pre-step section
 | **C. Add Feature** | [existing-widget/feature-enhancement.md](./ai-docs/templates/existing-widget/feature-enhancement.md) | [Pre-Enhancement Questions](./ai-docs/templates/existing-widget/feature-enhancement.md) (feature info, requirements, compatibility, design input) |
 | **D. Documentation only** | documentation templates | Optional: confirm scope with developer (no code change) |
 | **E. Understanding** | Package ai-docs | None (read-only) |
+| **F. Playwright E2E Test Work** | [playwright/00-master.md](./ai-docs/templates/playwright/00-master.md) | [Pre-Questions](./ai-docs/templates/playwright/01-pre-questions.md) (scope, scenarios, setup/utilities, stability expectations) |
 
 ---
 
@@ -202,6 +209,7 @@ Before generating or changing any code, you MUST complete the **pre-step section
 | **cc-widgets** | [packages/contact-center/cc-widgets/ai-docs/AGENTS.md](packages/contact-center/cc-widgets/ai-docs/AGENTS.md) | Same folder |
 | **ui-logging** | [packages/contact-center/ui-logging/ai-docs/AGENTS.md](packages/contact-center/ui-logging/ai-docs/AGENTS.md) | Same folder |
 | **samples-cc-react-app** | [widgets-samples/cc/samples-cc-react-app/ai-docs/AGENTS.md](widgets-samples/cc/samples-cc-react-app/ai-docs/AGENTS.md) | Same folder if present |
+| **playwright framework** | [playwright/ai-docs/AGENTS.md](playwright/ai-docs/AGENTS.md) | [playwright/ai-docs/ARCHITECTURE.md](playwright/ai-docs/ARCHITECTURE.md) |
 
 **Task package note:** The task package has multiple widgets (CallControl, IncomingTask, OutdialCall, TaskList). When working on one of them, use that widget's ai-docs path above, not a generic task path.
 
@@ -212,6 +220,11 @@ Before generating or changing any code, you MUST complete the **pre-step section
 - Find available methods, events, types
 - Check method signatures before using
 
+**If working on Playwright tests/framework:**
+- Read: `playwright/ai-docs/AGENTS.md`
+- Read: `playwright/ai-docs/ARCHITECTURE.md`
+- Use: `ai-docs/templates/playwright/00-master.md` and complete `01-pre-questions.md` before implementation
+
 ---
 
 ## Step 3: SDK API Consultation (Before Code Generation)
@@ -479,6 +492,11 @@ yarn build
 **If architecture changed:**
 - Update: Relevant architecture documentation as needed
 
+**If Playwright E2E framework/docs changed:**
+- Update: `playwright/ai-docs/AGENTS.md`
+- Update: `playwright/ai-docs/ARCHITECTURE.md`
+- Update relevant modules in: `ai-docs/templates/playwright/`
+
 ---
 
 ## Step 7: Validation & Review

ai-docs/README.md

@@ -176,6 +176,7 @@ Widget (Observer) → Custom Hook (Business Logic) → Component (UI) → Store
 
 **Repository Patterns:**
 - `ai-docs/patterns/` - TypeScript, MobX, React, Web Components, Testing patterns
+- `ai-docs/templates/` - Task templates (new widget, bug fix, feature enhancement, documentation, Playwright)
 
 **Component Documentation:**
 - `packages/*/ai-docs/README.md` - API and usage
@@ -199,4 +200,4 @@ See [AGENTS.md](./AGENTS.md) for AI navigation guidance, task-based workflows, a
 
 ---
 
-_Last Updated: 2025-11-23_
+_Last Updated: 2026-03-04_

ai-docs/templates/README.md

@@ -10,7 +10,8 @@ Templates for generating and maintaining contact center widgets and components.
 templates/
 ├── new-widget/          # Widget generation (7 modules)
 ├── existing-widget/     # Bug fixes, features (2 modules)
-└── documentation/       # Documentation generation (2 modules, reusable for all packages)
+├── documentation/       # Documentation generation (2 modules, reusable for all packages)
+└── playwright/          # Playwright E2E templates
 ```
 
 ## Templates
@@ -46,6 +47,17 @@ templates/
 - [create-agent-md.md](./documentation/create-agent-md.md) - Generate AGENTS.md
 - [create-architecture-md.md](./documentation/create-architecture-md.md) - Generate ARCHITECTURE.md
 
+### 4. Playwright E2E Work
+
+**Directory:** [playwright/](./playwright/)
+
+**Modules:**
+- [00-master.md](./playwright/00-master.md) - Orchestrator and workflow
+- [01-pre-questions.md](./playwright/01-pre-questions.md) - Mandatory intake
+- [02-test-implementation.md](./playwright/02-test-implementation.md) - Suites/tests/sets implementation
+- [03-framework-and-doc-updates.md](./playwright/03-framework-and-doc-updates.md) - Shared framework/docs updates
+- [04-validation.md](./playwright/04-validation.md) - Validation checklist
+
 ---
 
 ## Usage
@@ -58,6 +70,8 @@ templates/
 
 **Documentation Only:** Use [documentation/](./documentation/) templates
 
+**Playwright E2E Work:** Start with [playwright/00-master.md](./playwright/00-master.md)
+
 ## Pattern References
 
 - [TypeScript Patterns](../patterns/typescript-patterns.md)
@@ -68,4 +82,4 @@ templates/
 
 ---
 
-_Last Updated: 2025-11-26_
+_Last Updated: 2026-03-04_

ai-docs/templates/playwright/00-master.md

@@ -0,0 +1,59 @@
+# Playwright Test Work - Master Template
+
+## Purpose
+
+Orchestrator for Playwright E2E work in this repository.
+
+---
+
+## Workflow
+
+1. Gather complete requirements -> [01-pre-questions.md](./01-pre-questions.md)
+2. Implement tests/suites/sets -> [02-test-implementation.md](./02-test-implementation.md)
+3. Apply framework updates and documentation alignment -> [03-framework-and-doc-updates.md](./03-framework-and-doc-updates.md)
+4. Validate before completion -> [04-validation.md](./04-validation.md)
+
+Doc alignment is mandatory when any suite/test/set/framework behavior changes.
+
+---
+
+## Task Types
+
+Use one or more values from:
+
+- `new_test_suite`
+- `new_test_file`
+- `add_scenarios_to_existing_test`
+- `update_existing_test_logic`
+- `stabilize_flaky_tests`
+- `add_or_update_user_set`
+- `add_or_update_utils`
+- `add_or_update_test_manager`
+- `add_or_update_constants`
+- `add_or_update_global_setup`
+- `update_playwright_docs`
+
+---
+
+## Current Set-to-Suite Mapping
+
+Use `playwright/test-data.ts` as the source of truth for current set/suite mappings.
+
+Guidance:
+- Read existing `USER_SETS` entries before proposing changes
+- Reuse an existing set when possible
+- Create a new set only when required by scenario isolation, credentials, or participant count
+- Keep set design generic so any scenario can be added via requirements intake
+
+---
+
+## Execution Guidance
+
+- Always start with [01-pre-questions.md](./01-pre-questions.md).
+- Keep implementations aligned with current framework files (`playwright/suites`, `playwright/tests`, `playwright/Utils`, `playwright/test-manager.ts`, `playwright/test-data.ts`, `playwright/constants.ts`, `playwright/global.setup.ts`, `playwright.config.ts`).
+- For all test/suite/set/framework changes, update `playwright/ai-docs/AGENTS.md` and/or `playwright/ai-docs/ARCHITECTURE.md` as part of the same task.
+- End with [04-validation.md](./04-validation.md).
+
+---
+
+_Last Updated: 2026-03-05_

ai-docs/templates/playwright/01-pre-questions.md

@@ -0,0 +1,102 @@
+# Playwright Pre-Questions
+
+## Purpose
+
+Mandatory intake checklist to ensure the user provides complete implementation details before Playwright changes.
+
+---
+
+## Core Principles
+
+### 1. Root Cause Analysis Over Symptomatic Fixes
+- **NEVER** increase timeouts as a first response to flaky tests
+- **ALWAYS** investigate WHY a test is failing before applying fixes
+- Timeouts mask underlying issues (race conditions, incorrect selectors, state leakage)
+- Document the specific reason if timeout increases are necessary
+
+### 2. No Lazy Reasoning
+- **NEVER** assume "it probably works this way" - verify by reading code or testing
+- **NEVER** copy-paste patterns without understanding them
+- **NEVER** skip edge cases or error handling
+- **ALWAYS** ask clarifying questions when requirements are unclear
+
+### 3. Timeout Justification Required
+- Default timeouts should be sufficient for most operations
+- When increasing timeouts, document:
+  - What specific operation needs more time
+  - Why this operation requires more time (measured/observed duration)
+  - Why the operation cannot be optimized instead
+- Example GOOD reason: "Widget initialization requires loading external config (observed 15-20s in production)"
+- Example BAD reason: "Test was flaky, increased timeout to make it pass"
+
+### 4. Requirements Gathering First
+- Use questionnaire-driven approach
+- Understand full scope before implementation
+- Identify edge cases and error scenarios upfront
+- Don't start coding until requirements are clear
+
+---
+
+## Required Questions
+
+### 1. Task Scope
+
+- What exactly should be changed? (one sentence)
+- Is this a new suite, new test, update, or flaky-test stabilization?
+- Which current suite is impacted? (`playwright/suites/*.spec.ts`)
+
+### 2. Coverage Details
+
+- Exact scenarios to add/update (list each scenario title)
+- Expected assertions for each scenario
+- Out-of-scope scenarios
+
+### 3. Execution Target
+
+- Which set(s) should run this? (`SET_1`..`SET_N` or new set)
+- If new set is needed:
+  - What suite filename should `TEST_SUITE` map to?
+  - How many agents are required? (1-4)
+  - What entry points/queues/URLs are needed?
+
+### 4. Data and Environment
+
+- Required env keys (entry points, queue, chat URL, dial number, etc.)
+- How many agents are needed? (1-4)
+- Which roles are needed? (Agent1/Agent2/Agent3/Agent4/caller/extension/multi-session)
+- Any OAuth or token-related constraints?
+- Are there specific user credentials or permissions required?
+
+### 5. Setup and Utilities
+
+- Preferred `TestManager` setup method (if known)
+- Can existing `Utils/*` be reused, or is a new helper needed?
+
+### 6. Stability Expectations
+
+- Known flaky points today and their root causes (if known)
+- Have existing flaky tests been investigated for root cause?
+- Are there specific operations that legitimately require longer timeouts? (with justification)
+- What cleanup is required? (wrapup/end-state/agent cleanup)
+- Are there race conditions or state dependencies to address?
+
+**Important:** If user mentions timeout issues:
+1. First investigate: console logs, network traces, application state
+2. Identify root cause: race condition? slow operation? incorrect selector?
+3. Fix root cause: add proper state checks, optimize operation, fix selector
+4. Only increase timeout if justified and documented
+
+### 7. Documentation Expectations
+
+- Should `playwright/ai-docs/AGENTS.md` be updated?
+- Should `playwright/ai-docs/ARCHITECTURE.md` be updated?
+
+---
+
+## Completion Gate
+
+Do not start implementation until required questions are answered or explicitly assumed and documented.
+
+---
+
+_Last Updated: 2026-03-04_

ai-docs/templates/playwright/02-test-implementation.md

@@ -0,0 +1,63 @@
+# Playwright Test Implementation
+
+## Purpose
+
+Implement new or updated Playwright suites/tests/sets using current framework conventions.
+
+---
+
+## Implementation Paths
+
+### A. New Suite
+
+- Add `playwright/suites/<name>-tests.spec.ts`
+- Import one or more test factories from `playwright/tests/`
+- Wire `TEST_SUITE` in `playwright/test-data.ts`
+
+### B. New Test File
+
+- Add `playwright/tests/<feature>-test.spec.ts`
+- Export default factory: `create...Tests`
+- Register factory in target suite with `test.describe(...)`
+
+### C. Update Existing Tests
+
+- Update scenario logic in `playwright/tests/*.spec.ts`
+- Preserve existing factory export shape
+- Keep deterministic setup and cleanup
+
+### D. Add/Update User Set
+
+- Update `USER_SETS` in `playwright/test-data.ts`
+- Provide required set fields:
+  - `AGENTS`
+  - `QUEUE_NAME`
+  - `CHAT_URL`
+  - `EMAIL_ENTRY_POINT`
+  - `ENTRY_POINT`
+  - `TEST_SUITE`
+
+---
+
+## Required Patterns
+
+- Use `TestManager` convenience setup methods when possible
+- Reuse `playwright/Utils/*.ts` before adding new helper logic
+- Use shared constants from `playwright/constants.ts`
+- Keep set-scoped env access via `${testManager.projectName}_...`
+- For flaky test fixes, record root cause and update docs if behavior/expectations changed
+
+---
+
+## Done Criteria
+
+- [ ] Suite/test wiring complete
+- [ ] Set mapping correct (if changed)
+- [ ] Cleanup path present for new/changed scenarios
+- [ ] `playwright/ai-docs/AGENTS.md` baseline updated (if suites/sets/workflow changed)
+- [ ] `playwright/ai-docs/ARCHITECTURE.md` topology/mapping/runtime docs updated (if files/sets/framework behavior changed)
+- [ ] Fix/stabilization changes include a doc update loop when behavior or constraints changed
+
+---
+
+_Last Updated: 2026-03-05_

ai-docs/templates/playwright/03-framework-and-doc-updates.md

@@ -0,0 +1,42 @@
+# Playwright Framework and Docs Updates
+
+## Purpose
+
+Apply shared framework updates and keep Playwright docs aligned in the same task.
+
+---
+
+## Framework Files
+
+Update these as needed for reusable behavior changes:
+
+- `playwright/Utils/*.ts`
+- `playwright/test-manager.ts`
+- `playwright/constants.ts`
+- `playwright/global.setup.ts`
+- `playwright.config.ts`
+
+---
+
+## Doc Files (Required Alignment)
+
+- `playwright/ai-docs/AGENTS.md`
+- `playwright/ai-docs/ARCHITECTURE.md`
+
+`playwright/ai-docs/ARCHITECTURE.md` is the single source of truth for framework internals and scenario-level technical reference.
+
+If a task adds/changes suites, tests, sets, setup flows, runtime flags, or stability constraints, doc updates are mandatory.
+
+---
+
+## Checklist
+
+- [ ] Shared changes are reusable and not test-case specific
+- [ ] Existing tests remain backward compatible or intentionally migrated
+- [ ] AGENTS baseline reflects current suites/sets/workflow
+- [ ] ARCHITECTURE topology/mapping/runtime sections match current code
+- [ ] No references to non-existent files/suites/sets
+
+---
+
+_Last Updated: 2026-03-05_