agents-cli-automation 1.0.5 → 1.0.7

package/src/templates/playwright-agent-js.md

@@ -0,0 +1,461 @@
+name: Create Playwright Framework - UI Testing (JavaScript)
+description: Creates a production-ready Playwright UI automation framework in JavaScript (ES Modules) with all dependencies, fixtures, and test configurations.
+argument-hint: "framework requirements, e.g., 'JavaScript with UI tests'"
+
+---
+
+# Playwright UI Testing Framework - JavaScript (ES Modules)
+
+This agent creates a production-ready Playwright framework in modern JavaScript (ES Modules) optimized for UI automation.
+
+## Capabilities
+- **JavaScript (ES Modules)** - Chromium only with latest syntax
+- No build step required - direct ES modules support
+- UI, component, and end-to-end testing
+- **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
+- Test data support (JSON, CSV, YAML)
+- Form helpers for complex interactions
+- Scalable folder structure with best practices
+
+## Prerequisites
+- Node.js 18+ installed
+- npm or yarn
+
+## Setup Instructions
+
+### 1. Install Dependencies (Chromium Only)
+```bash
+npm install
+npm install --save-dev @cucumber/cucumber csv-parser js-yaml
+npx playwright install chromium
+```
+
+### 2. Update package.json
+Add `"type": "module"` for ES modules support:
+```json
+{
+  "type": "module",
+  "scripts": {
+    "start": "node server.js",
+    "test": "playwright test",
+    "test:headed": "playwright test --headed",
+    "test:debug": "playwright test --debug",
+    "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 (playwright.config.js - ES Module)
+```javascript
+export default {
+  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' }],
+  ],
+};
+```
+
+### 4. Project Structure
+```
+project/
+├── tests/
+│   ├── fixtures/
+│   │   └── base.fixture.js          # Shared fixtures
+│   ├── pages/
+│   │   ├── BasePage.js              # Base page object
+│   │   ├── LoginPage.js             # Login page object
+│   │   ├── InventoryPage.js         # Inventory page object
+│   │   └── FormPage.js              # Form page object
+│   ├── utils/                       # Utility functions
+│   │   ├── dataReader.js
+│   │   ├── formHelper.js
+│   │   └── testData.js
+│   ├── data/                        # Test data files
+│   │   ├── users.json
+│   │   ├── formData.csv
+│   │   └── config.yaml
+│   ├── features/                    # BDD Gherkin scenarios
+│   │   ├── login.feature
+│   │   └── shopping.feature
+│   ├── steps/                       # BDD Step definitions
+│   │   ├── loginSteps.js
+│   │   └── shoppingSteps.js
+│   └── specs/
+│       ├── saucedemo.spec.js         # Traditional tests
+│       └── formTest.spec.js
+├── cucumber.js                      # Cucumber config
+├── playwright.config.js             # Playwright config
+└── package.json
+```
+
+### 5. Cucumber Configuration (cucumber.js)
+```javascript
+export default {
+  default: {
+    paths: ['tests/features/**/*.feature'],
+    require: ['tests/steps/**/*.js'],
+    format: ['progress', 'html:cucumber-report.html'],
+    parallel: 4,
+    worldParameters: {
+      appUrl: 'https://www.saucedemo.com/',
+    }
+  }
+};
+```
+
+### 6. Data Reader Utility (tests/utils/dataReader.js)
+```javascript
+import fs from 'fs';
+import path from 'path';
+import csv from 'csv-parser';
+import yaml from 'js-yaml';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DATA_DIR = path.join(path.resolve(__dirname, '..'), 'data');
+
+export class DataReader {
+  // Read JSON file
+  static readJSON(filename) {
+    const filePath = path.join(DATA_DIR, filename);
+    const data = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(data);
+  }
+
+  // Read YAML file
+  static readYAML(filename) {
+    const filePath = path.join(DATA_DIR, filename);
+    const data = fs.readFileSync(filePath, 'utf-8');
+    return yaml.load(data);
+  }
+
+  // Read CSV file (returns array of objects)
+  static async readCSV(filename) {
+    const filePath = path.join(DATA_DIR, filename);
+    return new Promise((resolve, reject) => {
+      const records = [];
+      fs.createReadStream(filePath)
+        .pipe(csv())
+        .on('data', (data) => records.push(data))
+        .on('end', () => resolve(records))
+        .on('error', reject);
+    });
+  }
+
+  // Get single record by ID or key
+  static getRecordByKey(data, key, value) {
+    if (Array.isArray(data)) {
+      return data.find(record => record[key] === value);
+    }
+    return undefined;
+  }
+}
+```
+
+### 7. Form Helper Utility (tests/utils/formHelper.js)
+```javascript
+export class FormHelper {
+  constructor(page) {
+    this.page = page;
+  }
+
+  // Fill text input
+  async fillInput(selector, value) {
+    await this.page.fill(selector, value);
+  }
+
+  // Fill textarea
+  async fillTextArea(selector, value) {
+    await this.page.locator(selector).clear();
+    await this.page.locator(selector).type(value, { delay: 50 });
+  }
+
+  // Select option from dropdown (non-select element)
+  async selectDropdown(dropdownSelector, optionText) {
+    await this.page.click(dropdownSelector);
+    await this.page.click(`text="${optionText}"`);
+  }
+
+  // Select radio button by label text
+  async selectRadioButton(labelText) {
+    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) {
+    const label = this.page.locator(`label:has-text("${labelText}")`);
+    const checkboxId = await label.getAttribute('for');
+    if (checkboxId) {
+      const checkbox = this.page.locator(`#${checkboxId}`);
+      if (!(await checkbox.isChecked())) {
+        await checkbox.click();
+      }
+    }
+  }
+
+  // Select multiple checkboxes
+  async checkMultiple(labels) {
+    for (const label of labels) {
+      await this.checkCheckbox(label);
+    }
+  }
+
+  // Verify form value
+  async getInputValue(selector) {
+    return await this.page.inputValue(selector);
+  }
+
+  // Verify checkbox is checked
+  async isCheckboxChecked(labelText) {
+    const label = this.page.locator(`label:has-text("${labelText}")`);
+    const checkboxId = await label.getAttribute('for');
+    return checkboxId ? await this.page.locator(`#${checkboxId}`).isChecked() : false;
+  }
+}
+```
+
+### 8. Test Data Manager (tests/utils/testData.js)
+```javascript
+import { DataReader } from './dataReader.js';
+
+export class TestDataManager {
+  static loadUsers() {
+    return DataReader.readJSON('users.json');
+  }
+
+  static async loadFormData() {
+    return await DataReader.readCSV('formData.csv');
+  }
+
+  static loadConfig() {
+    return DataReader.readYAML('config.yaml');
+  }
+
+  static getUserByUsername(username) {
+    const data = this.loadUsers();
+    return DataReader.getRecordByKey(data.users, 'username', username);
+  }
+
+  static async getFormDataByScenario(scenarioName) {
+    const data = await this.loadFormData();
+    return DataReader.getRecordByKey(data, 'scenario', scenarioName);
+  }
+}
+```
+
+### 9. Base Page (tests/pages/BasePage.js)
+```javascript
+export class BasePage {
+  constructor(page) {
+    this.page = page;
+  }
+
+  async navigateTo(url) {
+    await this.page.goto(url);
+  }
+
+  async click(selector) {
+    await this.page.click(selector);
+  }
+
+  async fill(selector, text) {
+    await this.page.fill(selector, text);
+  }
+
+  async getText(selector) {
+    return await this.page.textContent(selector);
+  }
+
+  async waitForElement(selector, timeout = 5000) {
+    await this.page.waitForSelector(selector, { timeout });
+  }
+
+  async isVisible(selector) {
+    return await this.page.locator(selector).isVisible();
+  }
+}
+```
+
+### 10. Page Object - Login (tests/pages/LoginPage.js)
+```javascript
+import { BasePage } from './BasePage.js';
+
+export class LoginPage extends BasePage {
+  constructor(page) {
+    super(page);
+    this.usernameField = '[data-test="username"]';
+    this.passwordField = '[data-test="password"]';
+    this.loginButton = '[data-test="login-button"]';
+  }
+
+  async goto() {
+    await this.page.goto('https://www.saucedemo.com/');
+  }
+
+  async login(username, password) {
+    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() {
+    return await this.page.locator(this.usernameField).isVisible();
+  }
+}
+```
+
+### 11. Fixtures Setup (tests/fixtures/base.fixture.js)
+```javascript
+import { test as base, expect } from '@playwright/test';
+import { LoginPage } from '../pages/LoginPage.js';
+import { InventoryPage } from '../pages/InventoryPage.js';
+import { FormPage } from '../pages/FormPage.js';
+
+export const test = base.extend({
+  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 });
+  },
+});
+
+export { expect };
+```
+
+### 12. Simple Test Example (tests/specs/saucedemo.spec.js)
+```javascript
+import { test, expect } from '../fixtures/base.fixture.js';
+
+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');
+  });
+});
+```
+
+### 13. BDD Feature Example (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
+
+  Scenario: User logs in with valid credentials
+    Given I navigate to the SauceDemo application
+    When I login with username "standard_user" and password "secret_sauce"
+    Then I should see the inventory page
+```
+
+### 14. 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"
+    }
+  ]
+}
+```
+
+**tests/data/config.yaml**
+```yaml
+app:
+  url: https://www.saucedemo.com/
+  timeout: 30000
+users:
+  standard:
+    username: standard_user
+    password: secret_sauce
+```
+
+## Run Tests
+
+```bash
+# Run all tests in parallel
+npm test
+
+# Run specific test file
+npm test tests/specs/saucedemo.spec.js
+
+# Run with headed browser
+npm run test:headed
+
+# Debug mode
+npm run test:debug
+
+# Run BDD scenarios
+npm run test:bdd
+```
+
+## Best Practices
+✅ **Page Object Model** - Encapsulate all selectors in page classes
+✅ **Fixtures** - Reusable page objects and setup/teardown
+✅ **Test Data** - Externalize data in JSON, CSV, YAML
+✅ **Form Helpers** - Handle dropdowns, radios, checkboxes
+✅ **BDD Support** - Write scenarios in Gherkin
+✅ **Parallel Execution** - 4 workers by default
+✅ **Chromium Only** - Single browser for consistency
+✅ **Modern ES Modules** - Clean import/export syntax
+✅ **No Build Step** - Node.js 18+ direct ES module support
+
+**Note:** This framework uses JavaScript with ES Modules, Chromium only, and parallel execution. Start by copying the project structure and customizing page objects for your application.