symfonia-ai-tools 1.0.0

package/templates/packs/playwright/_ai/skills/playwright/SKILL.md

@@ -0,0 +1,1245 @@
+---
+name: playwright
+description: Expert guidance for writing, maintaining, debugging, and reviewing Playwright E2E tests. Provides comprehensive knowledge about Page Object Model patterns, test organization, fixture management, data-testid selectors, tagging strategies, and best practices for a structured testing framework.
+---
+
+# Playwright E2E Testing - {{PROJECT_NAME}}
+
+Expert skill for writing, maintaining, and reviewing end-to-end tests using Playwright in the {{PROJECT_NAME}} frontend project. This skill provides specialized knowledge about the project's testing architecture, conventions, and best practices.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- **Asks to CONVERT recorded test from `tmp/` to production** (from `playwright-record` skill)
+  - **AI Agent MUST**: Convert test AND run it to verify it works
+  - **AI Agent MUST**: Debug failures and fix issues
+  - **AI Agent MUST**: Re-run until test passes
+  - **AI Agent MUST NOT**: Mark conversion as done without running test
+- Asks to write new Playwright E2E tests
+- Needs help debugging or fixing existing Playwright tests
+- Wants to understand test structure or Page Object Models
+- Asks about test organization, naming conventions, or file structure
+- Needs guidance on selectors (data-testid patterns)
+- Wants to configure test execution (tags, browsers, workers)
+- Requests test fixtures or test data management
+- Asks about running tests locally or in Docker
+- Needs help with authentication flows or session management
+- Wants to review test code quality or refactor tests
+
+**CRITICAL for AI Agents:**
+- **NEVER** consider conversion complete without running the test
+- **ALWAYS** use `make playwright-test` or `npx playwright test` to verify
+- **ALWAYS** check exit code and output for failures
+- **ALWAYS** debug and fix issues if test fails
+- **ALWAYS** re-run until test passes (exit code 0)
+
+## Converting Recorded Tests from tmp/
+
+**CRITICAL WORKFLOW**: When converting tests recorded by `playwright-record` skill:
+
+### Step 1: Check Existing Page Objects FIRST
+
+**BEFORE creating ANY new Page Objects**, you MUST:
+
+1. **Search** `{{PLAYWRIGHT_DIR}}/pages/` for existing POMs
+2. **Check** `{{PLAYWRIGHT_DIR}}/pages/index.ts` for available exports
+3. **Analyze** if existing POM can be reused or extended
+4. **Only create new POM** if NO suitable one exists
+
+**Example check**:
+```bash
+# Check if LoginPage exists
+ls {{PLAYWRIGHT_DIR}}/pages/login/LoginPage.ts
+
+# Check if a specific page object exists
+ls {{PLAYWRIGHT_DIR}}/pages/{{MODULE_PATH}}/SomePage.ts
+
+# Check index.ts exports
+grep "export.*Page" {{PLAYWRIGHT_DIR}}/pages/index.ts
+```
+
+### Step 2: Reuse Existing POMs When Possible
+
+**If Page Object EXISTS** -> **REUSE IT**:
+```typescript
+// CORRECT: Reuse existing LoginPage
+import { LoginPage } from '../../pages/login/LoginPage';
+
+test('My test', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+  await loginPage.login(email, password);
+});
+```
+
+**If Page Object DOES NOT EXIST** -> **CREATE NEW ONE**:
+```typescript
+// CORRECT: Create new POM only if nothing exists
+export class SomeModulePage {
+  // ... new implementation
+}
+```
+
+### Step 3: Full Conversion Workflow (3 Sub-Steps)
+
+#### Step 3A: Automatic JavaScript to TypeScript Conversion
+
+**AI Agent MUST automatically transform raw Codegen output:**
+
+**Before (Raw JavaScript from tmp/)**:
+```javascript
+test('test', async ({ page }) => {
+  await page.goto('{{BASE_URL}}/login');
+  await page.getByPlaceholder('Email').fill('test@example.com');
+  await page.getByRole('button', { name: 'Login' }).click();
+  // ... more raw interactions
+});
+```
+
+**After (Converted TypeScript with POMs)**:
+```typescript
+import { expect, test } from '@playwright/test';
+import { LoginPage, DashboardPage } from '../../pages';
+import { CredentialsLoader } from '../../fixtures/loader';
+import { clearBrowserStorage } from '../../utils/test-helpers';
+
+test.describe('05_ModuleName - Tests', { tag: ['@module-tag', '@verified'] }, () => {
+  let loginPage: LoginPage;
+  let dashboardPage: DashboardPage;
+
+  test.beforeEach(async ({ page }) => {
+    loginPage = new LoginPage(page);
+    dashboardPage = new DashboardPage(page);
+
+    await page.goto('/login');
+    await clearBrowserStorage(page);
+  });
+
+  test('05_01_01: Test scenario description', async ({ page }) => {
+    const credentials = await CredentialsLoader.getCredentials();
+
+    await test.step('Login', async () => {
+      await loginPage.login(credentials.email.right, credentials.password.right);
+    });
+
+    await test.step('Navigate to target page', async () => {
+      await dashboardPage.navigateToModule();
+    });
+
+    await test.step('Verify success', async () => {
+      await expect(page.getByText('Success')).toBeVisible();
+    });
+  });
+});
+```
+
+**Conversion checklist**:
+- Import proper types and POMs
+- Add test.describe() with tags
+- Initialize POMs in beforeEach
+- Add clearBrowserStorage()
+- Use CredentialsLoader for credentials
+- Add test.step() for each logical action
+- Use Page Object methods instead of raw interactions
+- Add proper assertions (expect)
+
+#### Step 3B: Update pages/index.ts for New POMs
+
+**When creating a NEW Page Object**, update exports file:
+
+**File**: `{{PLAYWRIGHT_DIR}}/pages/index.ts`
+
+**Template**:
+```typescript
+// Add this line for new POM
+export { NewPageName } from './module/NewPageName.ts';
+```
+
+**Example**:
+```typescript
+// existing
+export { LoginPage } from './login/LoginPage';
+export { DashboardPage } from './dashboard/DashboardPage';
+
+// ADD NEW LIKE THIS:
+export { SomeModulePage } from './some-module/SomeModulePage';  // <- NEW
+```
+
+**Why?** Allows clean imports in tests:
+```typescript
+// GOOD
+import { LoginPage, SomeModulePage } from '../../pages';
+
+// BAD - Don't do this
+import { LoginPage } from '../../pages/login/LoginPage';
+import { SomeModulePage } from '../../pages/some-module/SomeModulePage';
+```
+
+#### Step 3C: Create Test Directory Structure If Needed
+
+**If test module directory doesn't exist, create it:**
+
+```bash
+# From project root
+mkdir -p {{PLAYWRIGHT_DIR}}/tests/NN_Module/
+
+# Example: Create a module directory
+mkdir -p {{PLAYWRIGHT_DIR}}/tests/05_ModuleName/
+```
+
+**File placement**:
+```
+{{PLAYWRIGHT_DIR}}/tests/
+├── 05_ModuleName/                              # <- Module
+│   ├── 05_01_01_Scenario_one.spec.ts          # <- Test file
+│   ├── 05_01_02_Scenario_two.spec.ts          # <- Another test
+│   └── 05_01_03_Scenario_three.spec.ts        # <- Another test
+```
+
+**Naming Rules**:
+- **First NN** (01-99): Main module number
+- **Second NN** (01-99): Sub-module/category number
+- **Third NN** (01-99): Specific test scenario number
+- **Suffix**: Always `.spec.ts`
+
+---
+
+## Project Context
+
+**Framework**: Playwright for E2E testing
+**Location**: `{{PLAYWRIGHT_DIR}}/`
+**Architecture**: Page Object Model (POM) with modular organization
+**Target**: {{PROJECT_NAME}} frontend application
+**Environments**: Local development + Docker + CI/CD
+
+### Key Technologies
+
+- **@playwright/test** - Main testing framework
+- **TypeScript** - Type-safe test code
+- **Docker** - Containerized test execution
+- **Multiple browsers** - Chromium (default), Firefox, Webkit, Mobile
+
+### Configuration Files
+
+The project uses several configuration files for environment settings and test data:
+
+**1. `.env` file** (`{{PLAYWRIGHT_DIR}}/.env`):
+- Environment configuration for test execution
+- Key variables:
+  - `BASE_URL` - Application base URL (default: `{{BASE_URL}}`)
+  - `COMPANY_NAME` - Company/tenant to test
+  - `BROWSER` - Browser to use (chromium, firefox, webkit)
+  - `HEADLESS` - Run tests in headless mode (true/false)
+  - `WORKERS` - Number of parallel workers
+  - `RETRIES` - Number of test retries on failure
+  - `TIMEOUT` - Test timeout in milliseconds
+
+**2. Credentials file** (`{{PLAYWRIGHT_DIR}}/credentials.env.json`):
+- Secure credentials storage (**NOT in git**)
+- Contains login credentials for different tenants/environments
+- Structure:
+  ```json
+  {
+    "tenantName": {
+      "email": { "right": "valid@email.com", "wrong": "invalid@email.com" },
+      "password": { "right": "correctPassword", "wrong": "wrongPassword" },
+      "username": { "right": "validUser", "wrong": "invalidUser" }
+    }
+  }
+  ```
+- Loaded dynamically via `CredentialsLoader.getCredentials()`
+
+**3. `playwright.config.ts` file** (`{{PLAYWRIGHT_DIR}}/playwright.config.ts`):
+- Main Playwright configuration
+- Loads environment variables from `.env` using `dotenv`
+- Configures:
+  - Test directory (`testDir: './tests'`)
+  - Browser projects (Chromium, Firefox, Webkit, Mobile)
+  - Reporters (HTML, JSON, JUnit, Allure)
+  - Timeouts and retries
+  - Base URL and navigation settings
+  - Locale and timezone
+  - Screenshots and video recording
+- Dynamic configuration based on environment variables
+
+**Usage in tests**:
+```typescript
+// Load credentials from credentials file
+const credentials = await CredentialsLoader.getCredentials();
+// Uses COMPANY_NAME from .env to select tenant data
+
+// Base URL is automatically used from playwright.config.ts
+await page.goto('/login'); // Uses BASE_URL from .env
+```
+
+## Test Organization & Structure
+
+### Directory Structure
+
+```
+{{PLAYWRIGHT_DIR}}/
+├── tests/                          # Test files (organized by module)
+│   ├── 00_Setup/                  # Setup and initialization tests
+│   ├── 01_Login/                  # Login module tests
+│   │   ├── 01_01_01_Login_scenarios.spec.ts
+│   │   └── 01_01_02_Login_verification.spec.ts
+│   ├── 02_Settings/               # Settings module tests
+│   ├── 03_ModuleA/                # Module A tests
+│   ├── 10_ModuleB/                # Module B tests
+│   └── 11_ModuleC/                # Module C tests
+│       └── 01_SubModule/          # Sub-module
+├── tmp/                            # Temporary/recorded tests (gitignored)
+│   └── playwright-test-*.js       # Raw Codegen outputs
+├── pages/                          # Page Object Models
+│   ├── login/LoginPage.ts
+│   ├── dashboard/DashboardPage.ts
+│   ├── components/                # Reusable component POMs
+│   └── index.ts                   # Centralized exports
+├── fixtures/                       # Test data and fixtures
+│   ├── loader.ts                  # CredentialsLoader for dynamic data
+│   ├── users.ts                   # User fixtures
+│   ├── tenants/                   # Tenant-specific data
+│   └── types/                     # TypeScript type definitions
+├── utils/                          # Utility functions
+│   ├── locators.ts                # Selector helpers
+│   ├── test-helpers.ts            # Common test utilities
+│   └── commands/                  # Command utilities
+│       └── auth/                  # Authentication helpers
+├── helpers/                        # Global setup/teardown
+│   ├── global-setup.ts
+│   ├── global-teardown.ts
+│   └── archive-reports.ts
+├── playwright.config.ts            # Main config (Chromium only - fast)
+├── playwright.all-browsers.config.ts  # Full browser coverage
+├── playwright.chromium-only.config.ts # Explicit Chromium config
+├── .env                            # Local environment variables
+├── .gitignore                      # Git ignore rules (includes tmp/)
+└── credentials.env.json            # Secure credentials (not in git)
+```
+
+### Test File Naming Convention
+
+**Format**: `NN_NN_NN_Test_name.spec.ts`
+
+- **NN** - Module/category/test number (hierarchical)
+- **Test_name** - Descriptive name (using underscores)
+- **Extension**: Always `.spec.ts`
+
+**Examples**:
+```
+01_01_01_Login_scenarios.spec.ts
+01_01_02_Login_verification.spec.ts
+11_01_01_Add_item.spec.ts
+11_01_02_Edit_item.spec.ts
+```
+
+**Hierarchy**:
+- **First NN**: Main module (01 = Login, 02 = Settings, 11 = ModuleC)
+- **Second NN**: Sub-module or category
+- **Third NN**: Specific test scenario within category
+
+## Test Writing Guidelines
+
+### Basic Test Structure
+
+```typescript
+import { expect, test } from '@playwright/test';
+import { LoginPage } from '../../pages/login/LoginPage';
+import { DashboardPage } from '../../pages/dashboard/DashboardPage';
+import { CredentialsLoader } from '../../fixtures/loader';
+import { clearBrowserStorage } from '../../utils/test-helpers';
+
+test.describe('01_Login - tests', { tag: ['@login', '@verified', '@smoke'] }, () => {
+    let loginPage: LoginPage;
+    let dashboardPage: DashboardPage;
+
+    test.beforeEach(async ({ page }) => {
+        loginPage = new LoginPage(page);
+        dashboardPage = new DashboardPage(page);
+
+        // Navigate to login page
+        await page.goto('/login');
+
+        // Clear browser storage (localStorage, sessionStorage, cookies)
+        await clearBrowserStorage(page);
+
+        // Wait for page to be ready
+        await loginPage.waitForPageReady();
+    });
+
+    test('01_01_01: Login - positive result', async ({ page }) => {
+        // Load test data from fixtures
+        const credentials = await CredentialsLoader.getCredentials();
+
+        // Use test.step for better reporting
+        await test.step('Enter email and password', async () => {
+            await loginPage.login(
+                credentials.email.right,
+                credentials.password.right
+            );
+        });
+
+        await test.step('Verify successful login', async () => {
+            await loginPage.verifySuccessfulLogin();
+            await expect(page).toHaveURL(/\/dashboard/);
+        });
+    });
+
+    test('01_01_02: Login - wrong password', async ({ page }) => {
+        const credentials = await CredentialsLoader.getCredentials();
+
+        await test.step('Enter valid email', async () => {
+            await loginPage.fillEmail(credentials.email.right);
+            await loginPage.clickContinue();
+        });
+
+        await test.step('Enter wrong password', async () => {
+            await loginPage.passwordInputLocator.waitFor({ state: 'visible' });
+            await loginPage.fillPassword(credentials.password.wrong);
+            await loginPage.clickLoginButton();
+        });
+
+        await test.step('Verify error message', async () => {
+            await loginPage.verifyErrorAlert();
+            await loginPage.verifyStillOnLoginPage();
+        });
+    });
+});
+```
+
+### Key Patterns
+
+1. **Use `test.describe()` with tags** - Group related tests with descriptive tags
+2. **Initialize Page Objects in `beforeEach`** - Create fresh instances for each test
+3. **Use `test.step()` for clarity** - Break tests into logical steps for better reporting
+4. **Load data dynamically** - Use `CredentialsLoader` for credentials and test data
+5. **Clear browser state** - Always use `clearBrowserStorage()` in `beforeEach`
+6. **Wait for visibility** - Use `.waitFor({ state: 'visible' })` before interactions
+
+## Page Object Model (POM)
+
+### Creating a Page Object
+
+**Location**: `{{PLAYWRIGHT_DIR}}/pages/[module]/[PageName]Page.ts`
+
+```typescript
+import type { Locator, Page } from '@playwright/test';
+import { getByDataTestId } from '../../utils/locators';
+
+/**
+ * Page Object for Login page
+ * Handles email/password authentication flow
+ */
+export class LoginPage {
+    protected page: Page;
+
+    // Locators - private and readonly
+    private readonly emailInput: Locator;
+    private readonly passwordInput: Locator;
+    private readonly submitButton: Locator;
+    private readonly errorAlert: Locator;
+
+    constructor(page: Page) {
+        this.page = page;
+
+        // Initialize locators with fallbacks for legacy selectors
+        this.emailInput = page
+            .locator('[data-testid="loginViewEmailStepInput"], [data-testid="loginRightPanelEmailInput"]')
+            .first();
+
+        this.passwordInput = page
+            .locator('[data-testid="loginViewPasswordStepInput"]')
+            .first();
+
+        this.submitButton = page
+            .locator('[data-testid="loginViewSubmitButton"]')
+            .first();
+
+        this.errorAlert = page
+            .locator('[data-testid="loginViewErrorAlert"]')
+            .first();
+    }
+
+    /**
+     * Navigate to login page and wait for form to be visible
+     */
+    async navigate(): Promise<void> {
+        await this.page.goto('/login');
+        await this.emailInput.waitFor({ state: 'visible', timeout: 10000 });
+    }
+
+    /**
+     * Fill email input field
+     */
+    async fillEmail(email: string): Promise<void> {
+        await this.emailInput.waitFor({ state: 'visible' });
+        await this.emailInput.clear();
+        await this.emailInput.fill(email);
+    }
+
+    /**
+     * Fill password input field
+     */
+    async fillPassword(password: string): Promise<void> {
+        await this.passwordInput.waitFor({ state: 'visible' });
+        await this.passwordInput.clear();
+        await this.passwordInput.fill(password);
+    }
+
+    /**
+     * Complete login flow with email and password
+     */
+    async login(email: string, password: string): Promise<void> {
+        await this.fillEmail(email);
+        await this.submitButton.click();
+        await this.passwordInput.waitFor({ state: 'visible' });
+        await this.fillPassword(password);
+        await this.submitButton.click();
+    }
+
+    /**
+     * Verify successful login by checking URL redirect
+     */
+    async verifySuccessfulLogin(): Promise<void> {
+        await this.page.waitForURL(/\/dashboard/, { timeout: 15000 });
+        await this.page.waitForLoadState('networkidle');
+    }
+
+    /**
+     * Verify error alert is visible
+     */
+    async verifyErrorAlert(): Promise<void> {
+        await this.errorAlert.waitFor({ state: 'visible', timeout: 5000 });
+    }
+}
+```
+
+### POM Best Practices
+
+1. **One class per page/component** - Keep POMs focused and single-responsibility
+2. **Locators as private readonly** - Encapsulate selectors, expose methods
+3. **Descriptive method names** - `fillEmail()`, `clickSubmitButton()`, `verifyErrorAlert()`
+4. **Return void for actions** - Methods that perform actions return `Promise<void>`
+5. **JSDoc comments** - Document public methods for better IDE support
+6. **Export via index.ts** - Centralize exports in `pages/index.ts`
+7. **Use `getByDataTestId()` helper** - For consistent data-testid selection
+
+### Project Structure Example
+
+**Page Objects** in the project:
+
+```
+{{PLAYWRIGHT_DIR}}/pages/
+├── index.ts                    <- Centralized exports
+├── login/
+│   └── LoginPage.ts           <- Login module POM
+├── dashboard/
+│   └── DashboardPage.ts       <- Dashboard module POM
+├── profile/
+│   └── ProfilePage.ts         <- Profile module POM (User profile interactions)
+├── settings/
+│   ├── GlobalSettingsPage.ts
+│   ├── ModuleSettingsPage.ts
+│   └── BrowserSettingsPage.ts
+├── module-a/
+│   ├── ModuleAPage.ts
+│   ├── ModuleAFormPage.ts
+│   ├── ModuleADetailsPage.ts
+│   └── ModuleASettingsPage.ts
+└── components/
+    ├── SidebarComponent.ts
+    ├── DataTableComponent.ts
+    └── ModalComponent.ts
+```
+
+### pages/index.ts - Centralized Exports
+
+```typescript
+/**
+ * Page Object Models index file
+ * Central export point for all page objects
+ */
+
+// Login pages
+export { LoginPage } from './login/LoginPage';
+// Dashboard pages
+export { DashboardPage } from './dashboard/DashboardPage';
+// Profile pages
+export { ProfilePage } from './profile/ProfilePage';
+// Settings pages
+export { GlobalSettingsPage } from './settings/GlobalSettingsPage';
+// ... more exports
+```
+
+### Profile Module Example
+
+**File**: `{{PLAYWRIGHT_DIR}}/pages/profile/ProfilePage.ts`
+
+```typescript
+import type { Locator, Page } from '@playwright/test';
+import { expect } from '@playwright/test';
+import { getByDataTestId } from '../../utils/locators';
+
+/**
+ * Page Object for User Profile page
+ * Handles user profile navigation and interactions
+ */
+export class ProfilePage {
+    protected page: Page;
+
+    // Avatar selector with fallbacks for different UI versions
+    private readonly avatarSelectors = [
+        '[data-testid="mainLayoutTopMenuMobileAvatar"]',
+        '[data-testid="desktopMenuAvatar"]',
+        '[data-testid="mobileMenuAvatar"]',
+        '[data-testid="userMenuDropdownIcon"]',
+        '[data-testid="mainLayoutTopMenuDesktopAvatar"]',
+    ];
+
+    constructor(page: Page) {
+        this.page = page;
+    }
+
+    /**
+     * Navigate to user profile via avatar menu
+     * Tries multiple selectors for compatibility with different UI versions
+     */
+    async navigateToUserProfile(): Promise<void> {
+        let avatarFound = false;
+
+        for (const selector of this.avatarSelectors) {
+            const avatarButton = this.page.locator(selector).first();
+            const isVisible = await avatarButton.isVisible({ timeout: 2000 }).catch(() => false);
+            if (isVisible) {
+                await avatarButton.click();
+                avatarFound = true;
+                break;
+            }
+        }
+
+        if (!avatarFound) {
+            throw new Error(`Could not find avatar button. Tried selectors: ${this.avatarSelectors.join(', ')}`);
+        }
+
+        const profileOption = getByDataTestId(this.page, 'profilePopoverItemProfile');
+        await profileOption.waitFor({ state: 'visible', timeout: 5000 });
+        await profileOption.click();
+
+        await this.page.waitForLoadState('networkidle');
+    }
+
+    /**
+     * Find and open a specific item by content
+     */
+    async findAndOpenItem(itemContent: string): Promise<void> {
+        const itemElement = this.page.getByRole('paragraph').filter({ hasText: itemContent });
+        await itemElement.waitFor({ state: 'visible', timeout: 5000 });
+        await itemElement.click();
+    }
+
+    /**
+     * Add a comment to an item
+     */
+    async addComment(commentText: string): Promise<void> {
+        const commentInput = this.page.getByRole('textbox', { name: /Write a message/i });
+        await commentInput.waitFor({ state: 'visible', timeout: 5000 });
+        await commentInput.click();
+        await commentInput.fill(commentText);
+        await commentInput.press('Enter');
+        await this.page.waitForTimeout(500);
+    }
+
+    /**
+     * Verify comment is visible
+     */
+    async verifyCommentVisible(commentText: string): Promise<void> {
+        const commentElement = this.page.getByText(commentText, { exact: true });
+        await expect(commentElement).toBeVisible({ timeout: 5000 });
+    }
+}
+```
+
+### Test File Using Profile POM
+
+**File**: `tests/02_Profile/02_01_01_Profile_Comments.spec.ts`
+
+```typescript
+import { LoginPage, DashboardPage, ProfilePage } from '../../pages';
+import { CredentialsLoader } from '../../fixtures/loader';
+import { clearBrowserStorage } from '../../utils/test-helpers';
+
+describe('02_Profile - Comments Workflow',
+  { tag: ['@profile', '@messaging', '@verified'] },
+  () => {
+    let loginPage: LoginPage;
+    let dashboardPage: DashboardPage;
+    let profilePage: ProfilePage;
+
+    beforeEach(async ({ page }) => {
+        loginPage = new LoginPage(page);
+        dashboardPage = new DashboardPage(page);
+        profilePage = new ProfilePage(page);
+
+        // Load credentials from CredentialsLoader
+        const credentials = await CredentialsLoader.getCredentials();
+
+        // Login workflow
+        await loginPage.navigate();
+        await loginPage.fillEmail(credentials.email.right);
+        await loginPage.clickContinue();
+        await loginPage.fillPassword(credentials.password.right);
+        await loginPage.clickLoginButton();
+        await dashboardPage.navigate();
+    });
+
+    it('02_01_01: should login and add comment in user profile',
+      async ({ page }) => {
+        // Profile navigation and comment addition
+        await profilePage.navigateToUserProfile();
+        await profilePage.findAndOpenItem('TestItem');
+        await profilePage.addComment('test comment');
+        await profilePage.verifyCommentVisible('test comment');
+    });
+});
+```
+
+### Key Points for POM
+
+1. **Location**: `pages/[module]/[PageName]Page.ts` (matches pattern `pages/[module]/[PageName]Page.ts`)
+2. **Export**: Added to `pages/index.ts` for centralized import
+3. **Fallback Selectors**: Handles multiple UI versions (desktop, mobile, different layouts)
+4. **Semantic Methods**: `navigateToUserProfile()`, `addComment()`, `verifyCommentVisible()`
+5. **Type Safety**: Full TypeScript with proper return types
+6. **Documentation**: JSDoc for all public methods
+
+## Selectors & data-testid
+
+### Selector Priority
+
+1. **`[data-testid="value"]`** - **PREFERRED** for all new elements
+2. **`[test-id="value"]`** - Alternative (legacy support)
+3. **`#id`** - For elements with unique IDs
+4. **`input[type="email"]`** - For form elements
+5. **`.class-name`** - Last resort only
+
+### data-testid Naming Convention
+
+**Format**: `moduleName-element-type`
+
+**Rules**:
+- Write in **English**
+- Separate with **hyphens** (`-`)
+- First part: **module name**
+- Middle parts: **description**
+- Last part: **element type** (input, button, checkbox, etc.)
+
+**Examples**:
+```html
+<!-- Login module -->
+<input data-testid="login-email-input" />
+<input data-testid="login-password-input" />
+<input data-testid="login-remember-me-checkbox" />
+<button data-testid="login-submit-button" />
+
+<!-- Tasks module -->
+<button data-testid="tasks-add-new-button" />
+<input data-testid="tasks-search-input" />
+<select data-testid="tasks-status-filter-select" />
+```
+
+### Using the Locator Helper
+
+```typescript
+import { getByDataTestId } from '../../utils/locators';
+
+// In Page Object
+constructor(page: Page) {
+    this.page = page;
+
+    // Simple usage
+    this.submitButton = getByDataTestId(page, 'login-submit-button');
+
+    // With fallbacks for legacy selectors
+    this.emailInput = page
+        .locator('[data-testid="loginViewEmailStepInput"], [data-testid="loginRightPanelEmailInput"]')
+        .first();
+}
+```
+
+**Helper function** (`utils/locators.ts`):
+```typescript
+export function getByDataTestId(page: Page, value: string) {
+    return page.locator(
+        `[data-testid="${value}"], [data-testid="${value}"], [data-testId="${value}"]`
+    ).first();
+}
+```
+
+## Test Data & Fixtures
+
+### Using CredentialsLoader
+
+**Location**: `fixtures/loader.ts`
+
+The `CredentialsLoader` provides dynamic test data loading based on environment variables:
+
+```typescript
+import { CredentialsLoader } from '../../fixtures/loader';
+
+// Get credentials for current tenant (from COMPANY_NAME env var)
+const credentials = await CredentialsLoader.getCredentials();
+
+// Available credential fields:
+credentials.email.right        // Valid email
+credentials.email.wrong        // Invalid email
+credentials.password.right     // Valid password
+credentials.password.wrong     // Invalid password
+credentials.username.right     // Valid username (login)
+credentials.username.wrong     // Invalid username
+
+// Get all tenant data (users, departments, etc.)
+const tenantData = await CredentialsLoader.getAllData();
+
+// Get specific users
+const users = await CredentialsLoader.getUsers();
+
+// Get departments
+const departments = await CredentialsLoader.getDepartments();
+```
+
+### Environment Variables
+
+**File**: `.env` (local) or set via Docker/Makefile
+
+```bash
+# Tenant selection
+COMPANY_NAME=default
+
+# Base URL
+BASE_URL={{BASE_URL}}
+
+# Test execution
+PLAYWRIGHT_WORKERS=4
+PLAYWRIGHT_RETRIES=1
+PLAYWRIGHT_GREP_TAGS=@verified
+
+# Browser
+PLAYWRIGHT_BROWSERS=chromium        # chromium, firefox, webkit
+```
+
+### Tenant Data Structure
+
+**File**: `fixtures/tenants/default.ts`
+
+```typescript
+const tenantData = {
+    name: 'Default Tenant',
+    code: 'default',
+
+    // Credentials loaded from credentials.env.json (secure)
+    // Not stored in repository!
+
+    users: {
+        admin: {
+            fullName: 'Admin User',
+            id: 1,
+            position: 'Administrator',
+            department: 'IT',
+        },
+        manager1: {
+            fullName: 'Manager One',
+            id: 2,
+            position: 'Department Manager',
+            department: 'Sales',
+        },
+        // ... more users
+    },
+
+    departments: {
+        // Department data
+    }
+};
+
+module.exports = tenantData;
+```
+
+### Secure Credentials
+
+**File**: `credentials.env.json` (NOT in git, copy from `.example`)
+
+```json
+{
+    "default": {
+        "username": {
+            "right": "valid.user@example.com",
+            "wrong": "invalid@example.com"
+        },
+        "password": {
+            "right": "ValidPassword123!",
+            "wrong": "WrongPassword"
+        },
+        "email": {
+            "right": "test@example.com",
+            "wrong": "invalid@test.com"
+        }
+    }
+}
+```
+
+## Test Tags & Filtering
+
+### Available Tags
+Tags: English language, prefixed with `@` for filtering
+- **`@verified`** - Fully tested and verified tests (default for CI/CD)
+- **`@smoke`** - Critical smoke tests (subset of @verified)
+- **`@login`** - Login module tests
+- **`@settings`** - Settings module tests
+- **`@module-a`** - Module A tests
+- **`@module-b`** - Module B tests
+
+### Using Tags in Tests
+
+```typescript
+// Single tag
+test.describe('Login tests', { tag: '@login' }, () => {
+    // tests
+});
+
+// Multiple tags
+test.describe('Login tests', { tag: ['@login', '@verified', '@smoke'] }, () => {
+    // tests
+});
+
+// Individual test tags (overrides describe tags)
+test('Critical login flow', { tag: '@smoke' }, async ({ page }) => {
+    // test
+});
+```
+
+### Running Tests by Tags
+
+```bash
+# Run all verified tests
+npx playwright test --grep @verified
+
+# Run smoke tests only
+npx playwright test --grep @smoke
+
+# Run specific module
+npx playwright test --grep @login
+
+# Multiple tags (OR logic)
+npx playwright test --grep "@login|@smoke"
+
+# Via Makefile
+make playwright-test playwright_grep_tags="@login"
+make playwright-test playwright_grep_tags="@smoke"
+```
+
+## Running Tests
+
+### Local Execution
+
+```bash
+cd {{PLAYWRIGHT_DIR}}
+
+# Quick tests - Chromium only
+npx playwright test
+
+# With UI (like Cypress)
+npx playwright test --ui
+
+# Debug mode
+npx playwright test --debug
+
+# Specific file
+npx playwright test tests/01_Login/01_01_01_Login_scenarios.spec.ts
+
+# All browsers
+npx playwright test --config=playwright.all-browsers.config.ts
+
+# Specific browser
+npx playwright test --project=firefox
+
+# Parallel execution (4 workers)
+npx playwright test --workers=4
+```
+
+### Docker Execution (via Makefile)
+
+**From project root**:
+
+```bash
+# Default - verified tests on Chromium
+make playwright-test
+
+# Custom URL
+make playwright-test playwright_base_url="{{BASE_URL}}"
+
+# Specific tags
+make playwright-test playwright_grep_tags="@login"
+
+# Specific file
+make playwright-test playwright_spec_file="tests/01_Login/01_01_01_Login_scenarios.spec.ts"
+
+# Different browser
+make playwright-test playwright_browsers="firefox"
+
+# Parallel execution (5 workers)
+make playwright-test playwright_parallel_machines="5"
+
+# Different tenant
+make playwright-test playwright_client_name="tenant-name"
+```
+
+### Configuration Files
+
+- **`playwright.config.ts`** - Default (Chromium only, fast)
+- **`playwright.all-browsers.config.ts`** - All browsers (Chromium, Firefox, Webkit, Mobile)
+- **`playwright.chromium-only.config.ts`** - Explicit Chromium only
+
+## Authentication & Session Management
+
+### Session Manager
+
+**Location**: `utils/commands/auth/session.manager.ts`
+
+Provides session caching for efficient test execution:
+
+```typescript
+import { SessionManager } from '../../utils/commands/auth';
+
+// In test
+test.beforeEach(async ({ page }) => {
+    // Restore session if exists
+    await SessionManager.restoreSession(page, 'user-session');
+
+    // If no session, login manually
+    if (!await SessionManager.hasSession('user-session')) {
+        const loginPage = new LoginPage(page);
+        const credentials = await CredentialsLoader.getCredentials();
+        await loginPage.login(credentials.email.right, credentials.password.right);
+
+        // Save session
+        await SessionManager.saveSession(page, 'user-session');
+    }
+});
+```
+
+### Clear Browser Storage
+
+```typescript
+import { clearBrowserStorage } from '../../utils/test-helpers';
+
+test.beforeEach(async ({ page }) => {
+    await page.goto('/login');
+
+    // Clear localStorage, sessionStorage, cookies
+    await clearBrowserStorage(page);
+});
+```
+
+## Reporting & Debugging
+
+### Reports Location
+
+- **HTML Report**: `playwright-report/index.html`
+- **JSON Report**: `reports/summary.json`
+- **Screenshots**: `reports/screenshots/`
+- **Videos**: `test-results/` (on failure)
+- **Archives**: `reports/archives/run-TIMESTAMP/`
+
+### View Reports
+
+```bash
+# Open HTML report
+npx playwright show-report
+
+# Via Makefile
+make playwright-show-report
+
+# Custom port
+npx playwright show-report --port=9324
+```
+
+### Screenshots & Videos
+
+**Automatic**:
+- Screenshots: Taken for ALL tests (pass/fail)
+- Videos: Only on failure (local) or off (CI)
+- Traces: On first retry
+
+**Manual screenshots**:
+```typescript
+await page.screenshot({ path: 'screenshot.png', fullPage: true });
+```
+
+## Common Utilities
+
+### Test Helpers
+
+**File**: `utils/test-helpers.ts`
+
+```typescript
+// Clear browser storage
+await clearBrowserStorage(page);
+
+// Wait for stable state (no animations)
+await waitForStable(page, '[data-testid="element"]');
+
+// Timestamped screenshot
+await takeTimestampedScreenshot(page, 'login-error');
+```
+
+### Locator Helpers
+
+```typescript
+import { getByDataTestId } from '../../utils/locators';
+
+// Get element by data-testid (with fallbacks)
+const button = getByDataTestId(page, 'submit-button');
+```
+
+## Best Practices
+
+### 1. Test Organization
+- Use hierarchical numbering (NN_NN_NN)
+- Group related tests in `test.describe()`
+- Use descriptive test names
+- Tag tests appropriately
+
+### 2. Page Objects
+- One POM per page/component
+- Private readonly locators
+- Public methods for actions
+- Export via `pages/index.ts`
+
+### 3. Selectors
+- Prefer `data-testid`
+- Follow naming convention (module-element-type)
+- Use `getByDataTestId()` helper
+- Provide fallbacks for legacy selectors
+
+### 4. Test Data
+- Use `CredentialsLoader` for dynamic data
+- Never hardcode credentials
+- Store sensitive data in `credentials.env.json`
+- Use environment variables
+
+### 5. Assertions
+- Use `test.step()` for clarity
+- Wait for visibility before assertions
+- Use specific expectations (`toHaveURL`, `toBeVisible`)
+- Verify state changes
+
+### 6. Performance
+- Use Chromium-only config for fast feedback
+- Leverage parallel execution (workers)
+- Clear browser state in `beforeEach`
+- Use all-browsers config before release
+
+### 7. Debugging
+- Use `--ui` mode for interactive debugging
+- Use `--debug` for step-by-step execution
+- Check screenshots in reports
+- Review trace files on failures
+
+## Anti-Patterns (Avoid)
+
+- Hardcoding credentials in tests
+- Using CSS class selectors instead of data-testid
+- Not using Page Objects (direct page interactions in tests)
+- Missing test tags
+- Not clearing browser storage in beforeEach
+- Not waiting for visibility before interactions
+- Mixing business logic with test code
+- Not using `test.step()` for multi-step tests
+- Inconsistent naming conventions
+
+## Troubleshooting
+
+### Common Issues
+
+**1. Element not found**
+```typescript
+// Wrong
+await page.locator('.button').click();
+
+// Correct
+await page.locator('[data-testid="submit-button"]').waitFor({ state: 'visible' });
+await page.locator('[data-testid="submit-button"]').click();
+```
+
+**2. Flaky tests**
+```typescript
+// Wait for network idle
+await page.waitForLoadState('networkidle');
+
+// Wait for specific element
+await element.waitFor({ state: 'visible' });
+
+// Use test.step() to identify failure point
+await test.step('Login', async () => {
+    await loginPage.login(email, password);
+});
+```
+
+**3. Authentication issues**
+```typescript
+// Clear storage before each test
+test.beforeEach(async ({ page }) => {
+    await clearBrowserStorage(page);
+});
+
+// Verify credentials are loaded
+const credentials = await CredentialsLoader.getCredentials();
+console.log('Using email:', credentials.email.right);
+```
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# Local testing
+npx playwright test                              # Quick (Chromium only)
+npx playwright test --ui                         # GUI mode
+npx playwright test --debug                      # Debug mode
+
+# Docker testing
+make playwright-test                             # Default (@verified)
+make playwright-test playwright_grep_tags="@smoke"  # Smoke tests
+
+# Reports
+npx playwright show-report                       # View HTML report
+make playwright-show-report                      # Via Makefile
+
+# Cleanup
+make playwright-clean                            # Clean reports
+```
+
+### File Templates
+
+**Test file**: `tests/NN_Module/NN_NN_NN_Test_name.spec.ts`
+**Page Object**: `pages/module/ModulePage.ts`
+**Fixtures**: `fixtures/tenants/tenant.ts`
+
+### Key Imports
+
+```typescript
+import { expect, test } from '@playwright/test';
+import { LoginPage } from '../../pages/login/LoginPage';
+import { CredentialsLoader } from '../../fixtures/loader';
+import { clearBrowserStorage } from '../../utils/test-helpers';
+import { getByDataTestId } from '../../utils/locators';
+```
+
+## Resources
+
+- **Project README**: `{{PLAYWRIGHT_DIR}}/README.md`
+- **Docker Guide**: `{{PLAYWRIGHT_DIR}}/DEVOPS-DOCKER.md`
+- **Playwright Docs**: https://playwright.dev/docs/intro
+
+---
+
+**Remember**: Adapt this skill template to your specific project by replacing all `{{PLACEHOLDER}}` values with your project's actual paths, URLs, and naming conventions. Always follow the established patterns, naming conventions, and best practices documented here.