agents-cli-automation 1.0.6 → 1.0.7

package/src/templates/playwright-agent.md

@@ -9,14 +9,20 @@ argument-hint: "framework requirements, e.g., 'JavaScript with UI tests'"
 This agent creates a production-ready Playwright framework optimized for UI automation.
 
 ## Capabilities
-- Playwright setup (JS / TS)
+- Playwright setup (JS / TS) - Chromium only with latest module syntax
+- TypeScript support with strictest config
 - UI, component, and end-to-end testing
-- Fixtures with proper configuration
+- **Playwright BDD** - Gherkin format with step definitions
+- **Page Object Model (POM)** - Reusable page classes
+- **Fixtures** - Pre-built browser & page fixtures
+- **Parallel execution** - Tests run simultaneously for speed
 - Sample tests (headless & headed modes)
-- Scalable folder structure
+- Scalable folder structure with best practices
 - WebServer configuration for running tests against local servers
 - Complete package.json with all required scripts
-- Visual regression testing ready
+- Modern ES modules with latest imports
+- Full TypeScript integration with types
+- Minimal setup - Developers only write test steps & scenarios
 
 ## Prerequisites
 - Node.js 18+ installed
@@ -24,12 +30,20 @@ This agent creates a production-ready Playwright framework optimized for UI auto
 
 ## Setup Instructions
 
-### 1. Install Dependencies
+### 1. Install Dependencies (Chromium Only + TypeScript)
 ```bash
 npm install
+npm install --save-dev typescript @types/node @playwright/test
+npx playwright install chromium
 ```
 
-### 2. Required package.json Scripts
+### 2. Install BDD & Data Handling Dependencies
+For Playwright BDD support and test data files:
+```bash
+npm install --save-dev @cucumber/cucumber csv-parser js-yaml @types/js-yaml
+```
+
+### 3. Required package.json Scripts
 Ensure your `package.json` includes these scripts:
 ```json
 {
@@ -38,76 +52,1368 @@ Ensure your `package.json` includes these scripts:
     "test": "playwright test",
     "test:headed": "playwright test --headed",
     "test:debug": "playwright test --debug",
-    "test:ui": "playwright test --ui"
+    "test:ui": "playwright test --ui",
+    "test:bdd": "npx @cucumber/cucumber-js",
+    "test:bdd:report": "npx @cucumber/cucumber-js --format json:cucumber-report.json"
   }
 }
 ```
 
-### 3. Playwright Configuration
-Your `playwright.config.js` must include:
-```javascript
+### 4. TypeScript Configuration (`tsconfig.json`)
+```json
 {
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "baseUrl": ".",
+    "paths": {
+      "@pages/*": ["tests/pages/*"],
+      "@utils/*": ["tests/utils/*"],
+      "@fixtures/*": ["tests/fixtures/*"],
+      "@data/*": ["tests/data/*"]
+    }
+  },
+  "include": ["tests/**/*"],
+  "exclude": ["node_modules"]
+}
+```
+
+### 5. Project Structure (Scalable with BDD & TypeScript)
+```
+project/
+├── tests/
+│   ├── fixtures/
+│   │   └── base.fixture.ts          # Shared fixtures (TypeScript)
+│   ├── pages/
+│   │   ├── BasePage.ts              # Base page object (TypeScript)
+│   │   ├── LoginPage.ts             # Login page object (TypeScript)
+│   │   ├── InventoryPage.ts         # Inventory page object (TypeScript)
+│   │   └── FormPage.ts              # Form page object (TypeScript)
+│   ├── utils/                       # Utility functions (TypeScript)
+│   │   ├── dataReader.ts
+│   │   ├── formHelper.ts
+│   │   └── testData.ts
+│   ├── data/                        # Test data files
+│   │   ├── users.json
+│   │   ├── formData.csv
+│   │   └── config.yaml
+│   ├── features/                    # BDD Gherkin scenarios
+│   │   ├── login.feature
+│   │   └── shopping.feature
+│   ├── steps/                       # BDD Step definitions (TypeScript)
+│   │   ├── loginSteps.ts
+│   │   └── shoppingSteps.ts
+│   └── specs/
+│       ├── saucedemo.spec.ts         # Traditional tests (TypeScript)
+│       └── formTest.spec.ts
+├── cucumber.js                      # Cucumber config
+├── playwright.config.ts             # Playwright config (TypeScript)
+├── tsconfig.json                    # TypeScript config
+└── package.json
+```
+
+### 6. Cucumber Configuration (`cucumber.js` - for BDD)
+```javascript
+module.exports = {
+  default: {
+    paths: ['tests/features/**/*.feature'],
+    require: ['tests/steps/**/*.ts'],
+    requireModule: ['ts-node/register'],
+    format: ['progress', 'html:cucumber-report.html'],
+    parallel: 4,
+    worldParameters: {
+      appUrl: 'https://www.saucedemo.com/',
+    }
+  }
+};
+```
+
+### 7. Playwright Configuration (`playwright.config.ts`)
+```typescript
+import { defineConfig, devices, type PlaywrightTestOptions } from '@playwright/test';
+
+export default defineConfig<PlaywrightTestOptions>({
+  testDir: './tests/specs',
+  fullyParallel: true,
+  workers: process.env.CI ? 1 : 4,
+  retries: 1,
+  timeout: 30000,
+  expect: {
+    timeout: 5000,
+  },
+  use: {
+    browserName: 'chromium',
+    headless: true,
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    trace: 'on-first-retry',
+  },
   webServer: {
     command: 'npm start',
     url: 'http://localhost:3000',
     reuseExistingServer: !process.env.CI,
+  },
+  reporter: [
+    ['html'],
+    ['json', { outputFile: 'test-results/results.json' }],
+  ],
+});
+```
+
+### 8. Data Reader Utility (`tests/utils/dataReader.ts`) - TypeScript
+```typescript
+import fs from 'fs';
+import path from 'path';
+import csv from 'csv-parser';
+import yaml from 'js-yaml';
+
+const DATA_DIR = path.join(process.cwd(), 'tests', 'data');
+
+interface DataRecord {
+  [key: string]: string | number | boolean;
+}
+
+export class DataReader {
+  // Read JSON file
+  static readJSON<T = DataRecord>(filename: string): T {
+    const filePath = path.join(DATA_DIR, filename);
+    const data = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(data) as T;
+  }
+
+  // Read YAML file
+  static readYAML<T = DataRecord>(filename: string): T {
+    const filePath = path.join(DATA_DIR, filename);
+    const data = fs.readFileSync(filePath, 'utf-8');
+    return yaml.load(data) as T;
+  }
+
+  // Read CSV file (returns array of objects)
+  static async readCSV(filename: string): Promise<DataRecord[]> {
+    const filePath = path.join(DATA_DIR, filename);
+    return new Promise<DataRecord[]>((resolve, reject) => {
+      const records: DataRecord[] = [];
+      fs.createReadStream(filePath)
+        .pipe(csv())
+        .on('data', (data: DataRecord) => records.push(data))
+        .on('end', () => resolve(records))
+        .on('error', reject);
+    });
+  }
+
+  // Get single record by ID or key
+  static getRecordByKey<T extends DataRecord>(
+    data: T[],
+    key: keyof T,
+    value: string | number
+  ): T | undefined {
+    if (Array.isArray(data)) {
+      return data.find((record) => record[key] === value);
+    }
+    return undefined;
   }
 }
 ```
 
-### 4. Sample UI Test (Ready to Use)
-For testing UI automation, use this demo application:
+### 9. Form Helper Utility (`tests/utils/formHelper.ts`) - TypeScript
+```typescript
+import { Page, Locator } from '@playwright/test';
+
+interface FormFieldConfig {
+  type: 'text' | 'textarea' | 'dropdown' | 'radio' | 'checkbox';
+  selector?: string;
+  value: string | string[] | boolean;
+}
+
+export class FormHelper {
+  constructor(private page: Page) {}
+
+  // Fill text input
+  async fillInput(selector: string, value: string): Promise<void> {
+    await this.page.fill(selector, value);
+  }
+
+  // Fill textarea
+  async fillTextArea(selector: string, value: string): Promise<void> {
+    await this.page.locator(selector).clear();
+    await this.page.locator(selector).type(value, { delay: 50 });
+  }
+
+  // Select option from dropdown (not select element)
+  async selectDropdown(dropdownSelector: string, optionText: string): Promise<void> {
+    await this.page.click(dropdownSelector);
+    await this.page.click(`text="${optionText}"`);
+  }
+
+  // Select radio button by label text
+  async selectRadioButton(labelText: string): Promise<void> {
+    const label = this.page.locator(`label:has-text("${labelText}")`);
+    const radioId = await label.getAttribute('for');
+    if (radioId) {
+      await this.page.locator(`#${radioId}`).click();
+    }
+  }
+
+  // Check checkbox by label text
+  async checkCheckbox(labelText: string): Promise<void> {
+    const label = this.page.locator(`label:has-text("${labelText}")`);
+    const checkboxId = await label.getAttribute('for');
+    if (checkboxId) {
+      const checkbox = this.page.locator(`#${checkboxId}`);
+      const isChecked = await checkbox.isChecked();
+      if (!isChecked) {
+        await checkbox.click();
+      }
+    }
+  }
+
+  // Uncheck checkbox by label text
+  async uncheckCheckbox(labelText: string): Promise<void> {
+    const label = this.page.locator(`label:has-text("${labelText}")`);
+    const checkboxId = await label.getAttribute('for');
+    if (checkboxId) {
+      const checkbox = this.page.locator(`#${checkboxId}`);
+      const isChecked = await checkbox.isChecked();
+      if (isChecked) {
+        await checkbox.click();
+      }
+    }
+  }
+
+  // Select multiple checkboxes
+  async checkMultiple(labels: string[]): Promise<void> {
+    for (const label of labels) {
+      await this.checkCheckbox(label);
+    }
+  }
+
+  // Fill form with object data
+  async fillForm(formData: Record<string, FormFieldConfig>): Promise<void> {
+    for (const field of Object.values(formData)) {
+      if (field.type === 'text' && field.selector && typeof field.value === 'string') {
+        await this.fillInput(field.selector, field.value);
+      } else if (field.type === 'textarea' && field.selector && typeof field.value === 'string') {
+        await this.fillTextArea(field.selector, field.value);
+      } else if (field.type === 'dropdown' && field.selector && typeof field.value === 'string') {
+        await this.selectDropdown(field.selector, field.value);
+      } else if (field.type === 'radio' && typeof field.value === 'string') {
+        await this.selectRadioButton(field.value);
+      } else if (field.type === 'checkbox' && field.value) {
+        if (Array.isArray(field.value)) {
+          await this.checkMultiple(field.value);
+        } else if (typeof field.value === 'string') {
+          await this.checkCheckbox(field.value);
+        }
+      }
+    }
+  }
+
+  // Verify form value
+  async getInputValue(selector: string): Promise<string | null> {
+    return await this.page.inputValue(selector);
+  }
+
+  // Verify radio button is selected
+  async isRadioSelected(labelText: string): Promise<boolean> {
+    const label = this.page.locator(`label:has-text("${labelText}")`);
+    const radioId = await label.getAttribute('for');
+    return radioId ? await this.page.locator(`#${radioId}`).isChecked() : false;
+  }
+
+  // Verify checkbox is checked
+  async isCheckboxChecked(labelText: string): Promise<boolean> {
+    const label = this.page.locator(`label:has-text("${labelText}")`);
+    const checkboxId = await label.getAttribute('for');
+    return checkboxId ? await this.page.locator(`#${checkboxId}`).isChecked() : false;
+  }
+}
+```
+
+### 10. Test Data Manager (`tests/utils/testData.ts`) - TypeScript
+```typescript
+import { DataReader } from './dataReader';
+
+interface User {
+  id: string;
+  username: string;
+  password: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+}
+
+interface FormData {
+  scenario: string;
+  firstName: string;
+  lastName: string;
+  email: string;
+  country: string;
+  acceptTerms: string;
+  newsletter: string;
+}
+
+interface Config {
+  app: {
+    url: string;
+    timeout: number;
+  };
+  users: {
+    [key: string]: {
+      username: string;
+      password: string;
+    };
+  };
+  forms: {
+    [key: string]: {
+      [field: string]: string;
+    };
+  };
+}
+
+export class TestDataManager {
+  // Load user data from JSON
+  static loadUsers(): { users: User[] } {
+    return DataReader.readJSON<{ users: User[] }>('users.json');
+  }
+
+  // Load form data from CSV
+  static async loadFormData(): Promise<FormData[]> {
+    return await DataReader.readCSV('formData.csv') as unknown as FormData[];
+  }
+
+  // Load config from YAML
+  static loadConfig(): Config {
+    return DataReader.readYAML<Config>('config.yaml');
+  }
+
+  // Get specific user by username
+  static getUserByUsername(username: string): User | undefined {
+    const data = this.loadUsers();
+    return DataReader.getRecordByKey(data.users, 'username' as keyof User, username);
+  }
+
+  // Get form data by scenario name
+  static async getFormDataByScenario(scenarioName: string): Promise<FormData | undefined> {
+    const data = await this.loadFormData();
+    return DataReader.getRecordByKey(data, 'scenario' as keyof FormData, scenarioName);
+  }
+}
+```
+
+### 9. Test Data Files
+
+**`tests/data/users.json`**
+```json
+{
+  "users": [
+    {
+      "id": "1",
+      "username": "standard_user",
+      "password": "secret_sauce",
+      "email": "user@example.com",
+      "firstName": "John",
+      "lastName": "Doe"
+    },
+    {
+      "id": "2",
+      "username": "problem_user",
+      "password": "secret_sauce",
+      "email": "problem@example.com",
+      "firstName": "Jane",
+      "lastName": "Smith"
+    }
+  ]
+}
+```
+
+**`tests/data/formData.csv`**
+```csv
+scenario,firstName,lastName,email,country,acceptTerms,newsletter
+registration_valid,John,Doe,john@example.com,USA,true,true
+registration_minimal,Jane,Smith,jane@example.com,Canada,true,false
+registration_eu,Pierre,Martin,pierre@example.com,France,true,true
+```
+
+**`tests/data/config.yaml`**
+```yaml
+app:
+  url: https://www.saucedemo.com/
+  timeout: 30000
+  
+users:
+  standard:
+    username: standard_user
+    password: secret_sauce
+  admin:
+    username: admin
+    password: admin123
+
+forms:
+  registration:
+    firstName: '#firstName'
+    lastName: '#lastName'
+    email: '#email'
+    country: '.country-dropdown'
+    acceptTerms: '#terms'
+    newsletter: '#newsletter'
 
-**Application:** https://www.saucedemo.com/
-**Credentials:**
-- Username: `standard_user`
-- Password: `secret_sauce`
+```
 
-Example test file (`tests/saucedemo.spec.js`):
+### 10. Enhanced Page Object with Form Helper (`tests/pages/FormPage.js`)
 ```javascript
-import { test, expect } from '@playwright/test';
+import { BasePage } from './BasePage';
+import { FormHelper } from '../utils/formHelper.js';
+import { TestDataManager } from '../utils/testData.js';
+
+export class FormPage extends BasePage {
+  constructor(page) {
+    super(page);
+    this.formHelper = new FormHelper(page);
+    this.config = TestDataManager.loadConfig();
+  }
+
+  async fillRegistrationForm(testDataKey) {
+    const formData = await TestDataManager.getFormDataByScenario(testDataKey);
+    
+    const formConfig = {
+      firstName: {
+        type: 'text',
+        selector: this.config.forms.registration.firstName,
+        value: formData.firstName
+      },
+      lastName: {
+        type: 'text',
+        selector: this.config.forms.registration.lastName,
+        value: formData.lastName
+      },
+      email: {
+        type: 'text',
+        selector: this.config.forms.registration.email,
+        value: formData.email
+      },
+      country: {
+        type: 'dropdown',
+        selector: this.config.forms.registration.country,
+        value: formData.country
+      },
+      acceptTerms: {
+        type: 'checkbox',
+        value: 'I accept the terms'
+      },
+      newsletter: {
+        type: 'checkbox',
+        value: formData.newsletter === 'true' ? 'Subscribe to newsletter' : null
+      }
+    };
+
+    for (const field of Object.values(formConfig)) {
+      if (field.value === null) continue;
+      
+      if (field.type === 'text') {
+        await this.formHelper.fillInput(field.selector, field.value);
+      } else if (field.type === 'dropdown') {
+        await this.formHelper.selectDropdown(field.selector, field.value);
+      } else if (field.type === 'checkbox') {
+        await this.formHelper.checkCheckbox(field.value);
+      }
+    }
+  }
+}
+```
+
+### 11. Enhanced Page Object with Form Helper (`tests/pages/FormPage.ts`) - TypeScript
+```typescript
+import { Page } from '@playwright/test';
+import { BasePage } from './BasePage';
+import { FormHelper } from '@utils/formHelper';
+import { TestDataManager } from '@utils/testData';
+
+export class FormPage extends BasePage {
+  readonly formHelper: FormHelper;
+  private config: any;
+
+  constructor(page: Page) {
+    super(page);
+    this.formHelper = new FormHelper(page);
+    this.config = TestDataManager.loadConfig();
+  }
+
+  async fillRegistrationForm(testDataKey: string): Promise<void> {
+    const formData = await TestDataManager.getFormDataByScenario(testDataKey);
+    if (!formData) throw new Error(`Form data not found for: ${testDataKey}`);
+
+    const formConfig = {
+      firstName: {
+        type: 'text' as const,
+        selector: this.config.forms.registration.firstName,
+        value: formData.firstName
+      },
+      lastName: {
+        type: 'text' as const,
+        selector: this.config.forms.registration.lastName,
+        value: formData.lastName
+      },
+      email: {
+        type: 'text' as const,
+        selector: this.config.forms.registration.email,
+        value: formData.email
+      },
+      country: {
+        type: 'dropdown' as const,
+        selector: this.config.forms.registration.country,
+        value: formData.country
+      },
+      acceptTerms: {
+        type: 'checkbox' as const,
+        value: 'I accept the terms'
+      },
+      newsletter: {
+        type: 'checkbox' as const,
+        value: formData.newsletter === 'true' ? 'Subscribe to newsletter' : null
+      }
+    };
+
+    for (const field of Object.values(formConfig)) {
+      if (field.value === null) continue;
+
+      if (field.type === 'text') {
+        await this.formHelper.fillInput(field.selector!, field.value as string);
+      } else if (field.type === 'dropdown') {
+        await this.formHelper.selectDropdown(field.selector!, field.value as string);
+      } else if (field.type === 'checkbox') {
+        await this.formHelper.checkCheckbox(field.value as string);
+      }
+    }
+  }
+}
+```
 
-test('Login to SauceDemo', async ({ page }) => {
-  await page.goto('https://www.saucedemo.com/');
-  await page.fill('[data-test="username"]', 'standard_user');
-  await page.fill('[data-test="password"]', 'secret_sauce');
-  await page.click('[data-test="login-button"]');
-  await expect(page).toHaveURL('**/inventory.html');
+### 12. Fixtures Setup (`tests/fixtures/base.fixture.ts`) - TypeScript
+```typescript
+import { test as base, expect } from '@playwright/test';
+import { LoginPage } from '@pages/LoginPage';
+import { InventoryPage } from '@pages/InventoryPage';
+import { FormPage } from '@pages/FormPage';
+
+type AuthFixtures = {
+  loginPage: LoginPage;
+  inventoryPage: InventoryPage;
+  formPage: FormPage;
+  authenticatedUser: { page: any; loginPage: LoginPage };
+};
+
+export const test = base.extend<AuthFixtures>({
+  loginPage: async ({ page }, use) => {
+    const loginPage = new LoginPage(page);
+    await use(loginPage);
+  },
+
+  inventoryPage: async ({ page }, use) => {
+    const inventoryPage = new InventoryPage(page);
+    await use(inventoryPage);
+  },
+
+  formPage: async ({ page }, use) => {
+    const formPage = new FormPage(page);
+    await use(formPage);
+  },
+
+  authenticatedUser: async ({ page, loginPage }, use) => {
+    await loginPage.goto();
+    await loginPage.login('standard_user', 'secret_sauce');
+    await use({ page, loginPage });
+  },
 });
 
-test('Add product to cart', async ({ page }) => {
-  await page.goto('https://www.saucedemo.com/');
-  await page.fill('[data-test="username"]', 'standard_user');
-  await page.fill('[data-test="password"]', 'secret_sauce');
-  await page.click('[data-test="login-button"]');
-  await page.click('[data-test="add-to-cart-sauce-labs-backpack"]');
-  await expect(page.locator('[data-test="shopping-cart-badge"]')).toContainText('1');
+export { expect };
+```
+
+### 13. Base Page (`tests/pages/BasePage.ts`) - TypeScript
+```typescript
+import { Page, Locator } from '@playwright/test';
+
+export class BasePage {
+  protected readonly page: Page;
+
+  constructor(page: Page) {
+    this.page = page;
+  }
+
+  async navigateTo(url: string): Promise<void> {
+    await this.page.goto(url);
+  }
+
+  async click(selector: string): Promise<void> {
+    await this.page.click(selector);
+  }
+
+  async fill(selector: string, text: string): Promise<void> {
+    await this.page.fill(selector, text);
+  }
+
+  async getText(selector: string): Promise<string | null> {
+    return await this.page.textContent(selector);
+  }
+
+  async getLocator(selector: string): Locator {
+    return this.page.locator(selector);
+  }
+
+  async waitForElement(selector: string, timeout: number = 5000): Promise<void> {
+    await this.page.waitForSelector(selector, { timeout });
+  }
+
+  async isVisible(selector: string): Promise<boolean> {
+    return await this.page.locator(selector).isVisible();
+  }
+}
+```
+
+### 14. Page Object Model (`tests/pages/LoginPage.ts`) - TypeScript
+```typescript
+import { BasePage } from './BasePage';
+
+export class LoginPage extends BasePage {
+  private readonly usernameField = '[data-test="username"]';
+  private readonly passwordField = '[data-test="password"]';
+  private readonly loginButton = '[data-test="login-button"]';
+  private readonly appUrl = 'https://www.saucedemo.com/';
+
+  async goto(): Promise<void> {
+    await this.page.goto(this.appUrl);
+  }
+
+  async login(username: string, password: string): Promise<void> {
+    await this.page.fill(this.usernameField, username);
+    await this.page.fill(this.passwordField, password);
+    await this.page.click(this.loginButton);
+    await this.page.waitForURL('**/inventory.html');
+  }
+
+  async isLoaded(): Promise<boolean> {
+    return await this.page.locator(this.usernameField).isVisible();
+  }
+}
+```
+
+### 15. Inventory Page (`tests/pages/InventoryPage.ts`) - TypeScript
+```typescript
+import { BasePage } from './BasePage';
+
+export class InventoryPage extends BasePage {
+  private readonly cartBadge = '[data-test="shopping-cart-badge"]';
+  private readonly addToCartBtn = '[data-test="add-to-cart-sauce-labs-backpack"]';
+  private readonly menuButton = '[data-test="bm-menu-button"]';
+  private readonly logoutLink = '[data-test="logout-sidebar-link"]';
+
+  async addProductToCart(): Promise<void> {
+    await this.click(this.addToCartBtn);
+  }
+
+  async getCartCount(): Promise<string | null> {
+    return await this.getText(this.cartBadge);
+  }
+
+  async isProductAdded(): Promise<string | null> {
+    await this.waitForElement(this.cartBadge);
+    return await this.getText(this.cartBadge);
+  }
+
+  async logout(): Promise<void> {
+    await this.click(this.menuButton);
+    await this.click(this.logoutLink);
+    await this.page.waitForURL('https://www.saucedemo.com/');
+  }
+}
+```
+
+### 16. Clean Test File with TypeScript (`tests/specs/saucedemo.spec.ts`)
+```typescript
+import { test, expect } from '@fixtures/base.fixture';
+
+test.describe('SauceDemo E2E Tests', () => {
+  test('Login with valid credentials', async ({ loginPage, page }) => {
+    await loginPage.goto();
+    await loginPage.login('standard_user', 'secret_sauce');
+    expect(page.url()).toContain('inventory.html');
+  });
+
+  test('Add product to cart', async ({ authenticatedUser, inventoryPage }) => {
+    await inventoryPage.addProductToCart();
+    const cartCount = await inventoryPage.getCartCount();
+    expect(cartCount).toBe('1');
+  });
+
+  test('Logout from inventory', async ({ authenticatedUser, inventoryPage, page }) => {
+    await inventoryPage.logout();
+    expect(page.url()).toBe('https://www.saucedemo.com/');
+  });
 });
 ```
 
-### 5. Run Tests
+### 17. Form Test with Data (`tests/specs/formTest.spec.ts`)
+```typescript
+import { test, expect } from '@fixtures/base.fixture';
+import { TestDataManager } from '@utils/testData';
+
+test.describe('Form Registration Tests with TypeScript', () => {
+  test('Register with JSON user data', async ({ formPage, page }) => {
+    const user = TestDataManager.getUserByUsername('standard_user');
+    expect(user).toBeDefined();
+
+    await page.goto('https://example.com/register');
+    await formPage.formHelper.fillInput('#firstName', user!.firstName);
+    await formPage.formHelper.fillInput('#lastName', user!.lastName);
+    await formPage.formHelper.fillInput('#email', user!.email);
+
+    await page.click('button[type="submit"]');
+    await expect(page).toHaveURL('**/success');
+  });
+
+  test.describe.configure({ mode: 'parallel' });
+
+  test('Register with CSV test data - Valid', async ({ formPage, page }) => {
+    await page.goto('https://example.com/register');
+    await formPage.fillRegistrationForm('registration_valid');
+    await page.click('button[type="submit"]');
+    await expect(page).toHaveURL('**/success');
+  });
+
+  test('Register with CSV test data - Minimal', async ({ formPage, page }) => {
+    await page.goto('https://example.com/register');
+    await formPage.fillRegistrationForm('registration_minimal');
+    await page.click('button[type="submit"]');
+    await expect(page).toHaveURL('**/success');
+  });
+});
+```
+
+### 18. Run Tests
 ```bash
-# Run all tests
+# Run all tests in parallel (4 workers)
 npm test
 
-# Run tests with UI
+# Run specific test file
+npm test tests/specs/saucedemo.spec.ts
+
+# Run tests with UI (single worker)
 npm run test:headed
 
 # Debug mode
 npm run test:debug
+
+# Run with custom worker count
+npm test -- --workers=2
+
+# Run BDD scenarios
+npm run test:bdd
+
+# Run BDD scenarios with JSON report
+npm run test:bdd:report
+
+# Run specific BDD feature
+npx @cucumber/cucumber-js tests/features/login.feature
+```
+
+### 19. BDD Feature File (`tests/features/login.feature`)
+```gherkin
+Feature: Login to SauceDemo
+  As a user
+  I want to login to the application
+  So that I can access the inventory
+
+  Background:
+    Given I navigate to the SauceDemo application
+
+  Scenario: User logs in with valid credentials
+    When I login with username "standard_user" and password "secret_sauce"
+    Then I should see the inventory page
+    And the page title should contain "Inventory"
+
+  Scenario: User logs in and adds product to cart
+    When I login with username "standard_user" and password "secret_sauce"
+    And I add "Sauce Labs Backpack" to cart
+    Then the cart count should show "1"
+    And the product should be in the cart
+
+  Scenario: User can logout
+    When I login with username "standard_user" and password "secret_sauce"
+    And I click the menu button
+    And I click logout
+    Then I should be back on the login page
+```
+
+### 20. BDD Step Definitions with TypeScript (`tests/steps/loginSteps.ts`)
+```typescript
+import { Given, When, Then, Before, After } from '@cucumber/cucumber';
+import { chromium, Browser, Page } from '@playwright/test';
+import { LoginPage } from '@pages/LoginPage';
+import { InventoryPage } from '@pages/InventoryPage';
+
+let browser: Browser;
+let page: Page;
+let loginPage: LoginPage;
+let inventoryPage: InventoryPage;
+
+Before(async function() {
+  browser = await chromium.launch();
+  page = await browser.newPage();
+  loginPage = new LoginPage(page);
+  inventoryPage = new InventoryPage(page);
+});
+
+After(async function() {
+  await page.close();
+  await browser.close();
+});
+
+Given('I navigate to the SauceDemo application', async function() {
+  await loginPage.goto();
+});
+
+When('I login with username {string} and password {string}', async function(username: string, password: string) {
+  await loginPage.login(username, password);
+});
+
+Then('I should see the inventory page', async function() {
+  await page.waitForURL('**/inventory.html');
+});
+
+Then('the page title should contain {string}', async function(title: string) {
+  const pageTitle = await page.title();
+  if (!pageTitle.includes(title)) {
+    throw new Error(`Expected title to contain "${title}" but got "${pageTitle}"`);
+  }
+});
+
+When('I add {string} to cart', async function(productName: string) {
+  const addBtn = '[data-test="add-to-cart-sauce-labs-backpack"]';
+  await page.click(addBtn);
+});
+
+Then('the cart count should show {string}', async function(count: string) {
+  const cartCount = await inventoryPage.getCartCount();
+  if (cartCount !== count) {
+    throw new Error(`Expected cart count "${count}" but got "${cartCount}"`);
+  }
+});
+
+When('I click the menu button', async function() {
+  await page.click('[data-test="bm-menu-button"]');
+});
+
+When('I click logout', async function() {
+  await page.click('[data-test="logout-sidebar-link"]');
+});
+
+Then('I should be back on the login page', async function() {
+  await page.waitForURL('https://www.saucedemo.com/');
+});
 ```
+});
+
+test('Logout from inventory', async ({ authenticatedUser, page }) => {
+  await page.click('[data-test="bm-menu-button"]');
+  await page.click('[data-test="logout-sidebar-link"]');
+  await expect(page).toHaveURL('https://www.saucedemo.com/');
+});
+```
+
+### 17. BDD Feature File (`tests/features/login.feature`)
+```gherkin
+Feature: Login to SauceDemo
+  As a user
+  I want to login to the application
+  So that I can access the inventory
+
+  Background:
+    Given I navigate to the SauceDemo application
+
+  Scenario: User logs in with valid credentials
+    When I login with username "standard_user" and password "secret_sauce"
+    Then I should see the inventory page
+    And the page title should contain "Inventory"
+
+  Scenario: User logs in and adds product to cart
+    When I login with username "standard_user" and password "secret_sauce"
+    And I add "Sauce Labs Backpack" to cart
+    Then the cart count should show "1"
+    And the product should be in the cart
+
+  Scenario: User can logout
+    When I login with username "standard_user" and password "secret_sauce"
+    And I click the menu button
+    And I click logout
+    Then I should be back on the login page
+```
+
+### 18. BDD Shopping Feature (`tests/features/shopping.feature`)
+```gherkin
+Feature: Shopping Cart
+  As a user
+  I want to manage my shopping cart
+  So that I can purchase items
+
+  Background:
+    Given I am logged into the application
+
+  Scenario: Add single item to cart
+    When I add "Sauce Labs Backpack" to cart
+    Then the cart count should show "1"
+
+  Scenario: Add multiple items to cart
+    When I add "Sauce Labs Backpack" to cart
+    And I add "Sauce Labs Bike Light" to cart
+    Then the cart count should show "2"
+
+  Scenario: Remove item from cart
+    When I add "Sauce Labs Backpack" to cart
+    And I remove "Sauce Labs Backpack" from cart
+    Then the cart should be empty
+```
+
+### 19. BDD Step Definitions (`tests/steps/loginSteps.js`)
+```javascript
+import { Given, When, Then, Before, After } from '@cucumber/cucumber';
+import { chromium } from 'playwright';
+import { LoginPage } from '../pages/LoginPage';
+import { InventoryPage } from '../pages/InventoryPage';
+
+let browser;
+let page;
+let loginPage;
+let inventoryPage;
+
+Before(async function() {
+  browser = await chromium.launch();
+  page = await browser.newPage();
+  loginPage = new LoginPage(page);
+  inventoryPage = new InventoryPage(page);
+});
+
+After(async function() {
+  await page.close();
+  await browser.close();
+});
+
+Given('I navigate to the SauceDemo application', async function() {
+  await loginPage.goto();
+});
+
+When('I login with username {string} and password {string}', async function(username, password) {
+  await loginPage.login(username, password);
+});
+
+Then('I should see the inventory page', async function() {
+  await page.waitForURL('**/inventory.html');
+});
+
+Then('the page title should contain {string}', async function(title) {
+  const pageTitle = await page.title();
+  if (!pageTitle.includes(title)) {
+    throw new Error(`Expected title to contain "${title}" but got "${pageTitle}"`);
+  }
+});
+
+When('I add {string} to cart', async function(productName) {
+  const addBtn = '[data-test="add-to-cart-sauce-labs-backpack"]';
+  await page.click(addBtn);
+});
+
+Then('the cart count should show {string}', async function(count) {
+  const cartCount = await inventoryPage.getCartCount();
+  if (cartCount !== count) {
+    throw new Error(`Expected cart count "${count}" but got "${cartCount}"`);
+  }
+});
+
+When('I click the menu button', async function() {
+  await page.click('[data-test="bm-menu-button"]');
+});
+
+When('I click logout', async function() {
+  await page.click('[data-test="logout-sidebar-link"]');
+});
+
+Then('I should be back on the login page', async function() {
+  await page.waitForURL('https://www.saucedemo.com/');
+});
+```
+
+### 20. BDD Shopping Steps (`tests/steps/shoppingSteps.js`)
+```javascript
+import { Given, When, Then } from '@cucumber/cucumber';
+import { LoginPage } from '../pages/LoginPage';
+
+let page;
+let loginPage;
+
+Given('I am logged into the application', async function() {
+  const { page: gherkinPage } = this;
+  page = gherkinPage;
+  loginPage = new LoginPage(page);
+  await loginPage.goto();
+  await loginPage.login('standard_user', 'secret_sauce');
+});
+
+When('I remove {string} from cart', async function(productName) {
+  const removeBtn = '[data-test="remove-sauce-labs-backpack"]';
+  await page.click(removeBtn);
+});
+
+Then('the cart should be empty', async function() {
+  const cartBadge = page.locator('[data-test="shopping-cart-badge"]');
+  const isHidden = await cartBadge.isHidden().catch(() => true);
+  if (!isHidden) {
+    throw new Error('Cart is not empty');
+  }
+});
+
+Then('the product should be in the cart', async function() {
+  const badge = await page.locator('[data-test="shopping-cart-badge"]').isVisible();
+  if (!badge) {
+    throw new Error('Product not found in cart');
+  }
+});
+```
+
+### 21. Run Tests
+```bash
+# Run all tests in parallel (4 workers)
+npm test
+
+# Run specific test file
+npm test tests/specs/saucedemo.spec.js
+
+# Run tests with UI (single worker)
+npm run test:headed
+
+# Debug mode
+npm run test:debug
+
+# Run with custom worker count
+npm test -- --workers=2
+
+# Run BDD scenarios
+npm run test:bdd
+
+# Run BDD scenarios with JSON report
+npm run test:bdd:report
+
+# Run specific BDD feature
+npx @cucumber/cucumber-js tests/features/login.feature
+```
+
+### 22. Example Test Using Utilities (`tests/specs/formTest.spec.js`)
+```javascript
+import { test, expect } from '../fixtures/base.fixture';
+import { FormPage } from '../pages/FormPage';
+import { TestDataManager } from '../utils/testData';
+
+test.describe('Form Registration with Test Data', () => {
+  let formPage;
+
+  test.beforeEach(async ({ page }) => {
+    formPage = new FormPage(page);
+    await page.goto('https://example.com/register');
+  });
+
+  test('Register with JSON user data', async ({ page }) => {
+    const user = TestDataManager.getUserByUsername('standard_user');
+    
+    await formPage.formHelper.fillInput('#firstName', user.firstName);
+    await formPage.formHelper.fillInput('#lastName', user.lastName);
+    await formPage.formHelper.fillInput('#email', user.email);
+    
+    await page.click('button[type="submit"]');
+    await expect(page).toHaveURL('**/success');
+  });
+
+  test('Register with CSV test scenarios', async ({ page }) => {
+    await formPage.fillRegistrationForm('registration_valid');
+    
+    await page.click('button[type="submit"]');
+    await expect(page).toHaveURL('**/success');
+  });
+
+  test('Fill complex form with multiple field types', async ({ page }) => {
+    const formConfig = {
+      firstName: {
+        type: 'text',
+        selector: '#firstName',
+        value: 'John'
+      },
+      country: {
+        type: 'dropdown',
+        selector: '.country-select',
+        value: 'United States'
+      },
+      gender: {
+        type: 'radio',
+        value: 'Male'
+      },
+      interests: {
+        type: 'checkbox',
+        value: ['Sports', 'Gaming', 'Reading']
+      },
+      terms: {
+        type: 'checkbox',
+        value: 'I accept terms'
+      }
+    };
+
+    // Use helper to fill entire form
+    for (const field of Object.values(formConfig)) {
+      if (field.type === 'text') {
+        await formPage.formHelper.fillInput(field.selector, field.value);
+      } else if (field.type === 'dropdown') {
+        await formPage.formHelper.selectDropdown(field.selector, field.value);
+      } else if (field.type === 'radio') {
+        await formPage.formHelper.selectRadioButton(field.value);
+      } else if (field.type === 'checkbox') {
+        if (Array.isArray(field.value)) {
+          await formPage.formHelper.checkMultiple(field.value);
+        } else {
+          await formPage.formHelper.checkCheckbox(field.value);
+        }
+      }
+    }
+
+    await page.click('button[type="submit"]');
+    await expect(page).toHaveURL('**/success');
+  });
+
+  test('Verify form values after filling', async ({ page }) => {
+    await formPage.formHelper.fillInput('#firstName', 'John');
+    await formPage.formHelper.checkCheckbox('I accept terms');
+    
+    const firstName = await formPage.formHelper.getInputValue('#firstName');
+    const isTermsChecked = await formPage.formHelper.isCheckboxChecked('I accept terms');
+    
+    expect(firstName).toBe('John');
+    expect(isTermsChecked).toBe(true);
+  });
+});
+```
+
+### 23. BDD Step with Test Data Integration
+```gherkin
+Feature: Registration with Test Data
+  As a new user
+  I want to register using predefined test data
+  So that I can access the application
+
+  Scenario: Register with JSON test data
+    Given I navigate to the registration page
+    When I fill the form with user data "standard_user"
+    And I accept the terms and conditions
+    And I submit the form
+    Then I should see the success message
+
+  Scenario Outline: Register with CSV test scenarios
+    Given I navigate to the registration page
+    When I fill first name with "<firstName>"
+    And I fill last name with "<lastName>"
+    And I fill email with "<email>"
+    And I select country "<country>"
+    And I check "<acceptTerms>"
+    And I submit the form
+    Then I should see the success message
+
+    Examples:
+      | firstName | lastName | email          | country | acceptTerms |
+      | John      | Doe      | john@test.com  | USA     | true        |
+      | Jane      | Smith    | jane@test.com  | Canada  | true        |
+      | Pierre    | Martin   | pierre@test.fr | France  | true        |
+```
+
+## Developer Quick Start
+
+### Using Test Data & Form Helpers
+**Step 1:** Create test data files in `tests/data/` (JSON, CSV, YAML)
+**Step 2:** Use `DataReader` to load test data:
+```javascript
+const users = DataReader.readJSON('users.json');
+const formData = await DataReader.readCSV('formData.csv');
+const config = DataReader.readYAML('config.yaml');
+```
+
+**Step 3:** Use `FormHelper` for complex form interactions:
+```javascript
+const formHelper = new FormHelper(page);
+await formHelper.fillInput('#name', 'John');
+await formHelper.selectDropdown('.country', 'USA');
+await formHelper.checkMultiple(['Option1', 'Option2']);
+```
+
+**Step 4:** Create page objects that combine both:
+```javascript
+const formPage = new FormPage(page);
+await formPage.fillRegistrationForm('registration_valid');
+```
+
+### Traditional Playwright Tests
+**Step 1:** Copy project structure from Section 4
+**Step 2:** Create page objects in `tests/pages/` (copy LoginPage & InventoryPage)
+**Step 3:** Import fixtures in your tests: `import { test, expect } from '../fixtures/base.fixture'`
+**Step 4:** Use fixtures in tests: `test('my test', async ({ loginPage, authenticatedUser }) => { ... })`
+**Step 5:** Run: `npm test`
+
+### BDD Scenarios
+**Step 1:** Create `.feature` files in `tests/features/` with Gherkin scenarios
+**Step 2:** Create step definitions in `tests/steps/` (copy loginSteps & shoppingSteps)
+**Step 3:** Map steps to page objects (reuse LoginPage, InventoryPage)
+**Step 4:** Configure `cucumber.js` for parallel execution
+**Step 5:** Run: `npm run test:bdd`
 
 ## Verification Checklist
-✅ All dependencies installed (`npm install`)
-✅ "start" script defined in package.json
-✅ Local server running on configured port
-✅ Playwright config has webServer setup
-✅ Tests execute without webServer errors
-
-## Use Cases
-- New automation projects
-- E2E testing frameworks
-- Integration testing setup
-- CI/CD pipeline automation
-
-**Note:** If you see "Missing script: start" error, add the `start` script to your package.json before running tests.
+✅ Chromium browser installed (`npx playwright install chromium`)
+✅ TypeScript configured (`typescript @types/node` installed + `tsconfig.json` created)
+✅ All dependencies installed (`npm install` + `@cucumber/cucumber` + `csv-parser`, `js-yaml`, `@types/js-yaml`)
+✅ TypeScript paths configured in `tsconfig.json` (@pages/*, @utils/*, @fixtures/*, @data/*)
+✅ Playwright config in TypeScript (`playwright.config.ts` with latest imports)
+✅ Folder structure created (all `.ts` files: `tests/pages/`, `tests/fixtures/`, `tests/specs/`, `tests/features/`, `tests/steps/`, `tests/utils/`, `tests/data/`)
+✅ Base fixtures created with TypeScript typing (`base.fixture.ts`)
+✅ Cucumber configuration created (`cucumber.js` with ts-node support)
+✅ Page Object Model classes in TypeScript with type safety
+✅ Step definitions in TypeScript with proper typing
+✅ Feature files created (login.feature, shopping.feature)
+✅ Utilities created in TypeScript (dataReader.ts, formHelper.ts, testData.ts with interfaces)
+✅ Test data files created (users.json, formData.csv, config.yaml)
+✅ Enhanced page objects in TypeScript (FormPage.ts with utilities integrated)
+✅ Modern ES module imports throughout (import/export)
+✅ Parallel execution enabled (`fullyParallel: true` & Cucumber parallel: 4)
+✅ Tests execute in parallel against single Chromium browser
+✅ Both Playwright & BDD tests configured with full TypeScript support
+
+## Best Practices for Scalability & TypeScript
+✅ **Use Fixtures** - Pre-set up authenticated users, page objects (base.fixture.ts with types)
+✅ **Page Object Model** - Encapsulate selectors & actions in TypeScript classes
+✅ **Type Safety** - Full TypeScript typing for all utilities, pages, and tests
+✅ **Test Data Management** - Use JSON, CSV, YAML with DataReader (fully typed)
+✅ **Form Helpers** - Reusable FormHelper for all form interactions (typed interfaces)
+✅ **BDD for Non-Technical Stakeholders** - Write scenarios in Gherkin (Feature files)
+✅ **Parallel Execution** - Tests & scenarios run simultaneously (4 workers by default)
+✅ **Minimal Developer Effort** - Write only test logic, reuse fixtures, pages, steps & utilities
+✅ **Chromium Only** - Single browser reduces flakiness & speeds up execution
+✅ **Retry Failed Tests** - Automatic retries improve reliability
+✅ **Capture Failures** - Screenshots & videos on failures for debugging
+✅ **Dual Approach** - Mix traditional tests & BDD scenarios based on needs
+✅ **Module Path Aliases** - Use @pages/, @utils/, @fixtures/, @data/ for clean imports
+✅ **Latest Playwright** - Uses latest Playwright APIs with modern module syntax
+✅ **Parameterized Tests** - Use CSV data for scenario outlines (data-driven testing)
+✅ **Form Helpers** - Reusable FormHelper for all form interactions (text, dropdown, radio, checkbox)
+✅ **BDD for Non-Technical Stakeholders** - Write scenarios in Gherkin (Feature files)
+✅ **Parallel Execution** - Tests & scenarios run simultaneously (4 workers by default)
+✅ **Minimal Developer Effort** - Write only test logic, reuse fixtures, pages, steps & utilities
+✅ **Chromium Only** - Single browser reduces flakiness & speeds up execution
+✅ **Retry Failed Tests** - Automatic retries improve reliability
+✅ **Capture Failures** - Screenshots & videos on failures for debugging
+✅ **Dual Approach** - Mix traditional tests & BDD scenarios based on needs
+✅ **Parameterized Tests** - Use CSV data for scenario outlines (data-driven testing)
+✅ **Full TypeScript Support** - All code written in TypeScript with strict mode enabled
+✅ **Path Aliases** - Clean imports using @pages/, @utils/, @fixtures/, @data/ prefixes
+
+## How to Use Test Data & Utilities (TypeScript)
+
+### 1. Loading Test Data
+```typescript
+import { TestDataManager } from '@utils/testData';
+
+// Get user by username (fully typed)
+const user = TestDataManager.getUserByUsername('standard_user');
+
+// Get form data by scenario
+const formData = await TestDataManager.getFormDataByScenario('registration_valid');
+
+// Load all config with type safety
+const config = TestDataManager.loadConfig();
+```
+
+### 2. Form Interactions with Type Safety
+```typescript
+import { FormHelper } from '@utils/formHelper';
+import { Page } from '@playwright/test';
+
+const formHelper = new FormHelper(page);
+
+// Text input
+await formHelper.fillInput('#firstName', 'John');
+
+// Dropdown (non-select)
+await formHelper.selectDropdown('.country-dropdown', 'USA');
+
+// Radio button
+await formHelper.selectRadioButton('Male');
+
+// Single checkbox
+await formHelper.checkCheckbox('I accept terms');
+
+// Multiple checkboxes
+await formHelper.checkMultiple(['Option1', 'Option2', 'Option3']);
+
+// Get and verify values (fully typed)
+const firstName = await formHelper.getInputValue('#firstName');
+const isChecked = await formHelper.isCheckboxChecked('I accept terms');
+```
+
+### 3. Data-Driven Tests in TypeScript
+```typescript
+import { test, expect } from '@fixtures/base.fixture';
+import { FormPage } from '@pages/FormPage';
+
+test.describe('Data-Driven Form Tests', () => {
+  const testCases = [
+    { scenario: 'registration_valid' as const },
+    { scenario: 'registration_minimal' as const },
+    { scenario: 'registration_eu' as const }
+  ];
+
+  testCases.forEach((testCase) => {
+    test(`Register with ${testCase.scenario}`, async ({ page, formPage }: any) => {
+      await formPage.fillRegistrationForm(testCase.scenario);
+      // Assert...
+    });
+  });
+});
+```
+
+### 4. Using Module Path Aliases
+```typescript
+// Clean imports with path aliases
+import { LoginPage } from '@pages/LoginPage';
+import { FormHelper } from '@utils/formHelper';
+import { DataReader } from '@utils/dataReader';
+import { test, expect } from '@fixtures/base.fixture';
+
+// Old way (avoid)
+// import { LoginPage } from '../pages/LoginPage';
+```
+
+## When to Use Traditional vs BDD
+**Use Traditional Tests (`npm test`)** when:
+- Writing complex technical validations
+- Need direct access to page objects with full typing
+- Testing internal APIs or utilities
+- Data-driven test variations
+- Using TypeScript for type safety
+
+**Use BDD (`npm run test:bdd`)** when:
+- Collaborating with non-technical stakeholders
+- Business logic needs clear documentation
+- Multiple teams working on same scenarios
+- Acceptance criteria need to be testable
+
+**Note:** This setup uses Chromium only with parallel execution, full TypeScript support with strict mode, and modern ES module imports. Both Playwright & BDD tests can run simultaneously with complete type safety. All utilities and page objects are fully typed. Module path aliases (@pages/, @utils/, etc.) provide clean imports. Latest Playwright features and APIs are used throughout. If you see "Missing script: start" error, add the `start` script to your package.json before running tests.