agents-cli-automation 1.0.6 → 1.0.8

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.

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

@@ -0,0 +1,69 @@
+name: automation.md description: Describe what this custom agent does and when to use it. argument-hint: The inputs this agent expects, e.g., "a task to implement" or "a question to answer". tools: ['read', 'create_file', 'apply_patch', 'run_in_terminal', 'file_search', 'grep_search', 'manage_todo_list'] --- This agent documents and automates reproducing the repository layout, minimal file placeholders, and recommended developer commands so a new user can recreate the same workspace and run the test suites. When to use - When a new contributor needs to scaffold a local copy of this project structure and install the tooling to run tests and Playwright flows. Inputs (argument-hint) - task (required): one of scaffold, verify, describe. - targetPath (optional): filesystem path where scaffolding should be created. Defaults to repository root. - installDeps (optional boolean): when true, agent will install Node dependencies and Playwright browsers. - force (optional boolean): when true, allow overwriting placeholder files (use with caution). Capabilities / Behavior - Read the repo layout and create any missing directories listed in the standard layout. - Create placeholder files for missing source files (short header + file path + TODO notes). - Optionally install Node dependencies and Playwright browsers when installDeps=true. - Run verification commands (npm test, npx playwright test --list) and return concise logs. Prerequisites - Node.js (v16+) and npm (or pnpm) installed. - Internet access for package installation. Scaffolded layout (representative)
+bitbucket-pipelines.yml
+package.json
+playwright.config.ts
+tsconfig.json
+core/
+	api/
+		apiClient.ts
+	auth/
+		roles.ts
+	db/
+		connection.ts
+		queries.ts
+	permission/
+		permission.schd-group.ts
+		permission.types.ts
+playwright-report/
+index.html
+screenshots/
+test-results/
+tests/
+	api/
+		schd-group-create.api.spec.ts
+	data/
+		facilityFormData.json
+	db/
+		01-connection.db.spec.ts
+	fixtures/
+		pages.fixture.ts
+		test.fixture.ts
+	types/
+		formField.ts
+ui/
+	features/
+		booking.feature
+		scheduling-groups.feature
+	page/
+		HomePage.ts
+	steps/
+		booking.steps.ts
+		scheduling-groups.steps.ts
+utils/
+	formFiller.ts
+	readJson.ts
+workflows/
+	facilities/
+		api/
+		db/
+		invariants/
+	schd-group/
+		api/
+			schd-group.api.ts
+		db/
+			schd-group.queries.ts
+		invariants/
+			api.invariants.ts
+			db.invariants.ts
+			permission.invariants.ts
+Scaffold steps (task: scaffold) 1. Validate targetPath exists or create it. 2. Create the directory tree above (only new directories created). 3. For each file that exists in source repo, copy content. For files missing, create a placeholder containing: header, expected responsibilities, and TODO pointers. 4. If installDeps=true, run npm ci (or npm install) and npx playwright install (or npx playwright install --with-deps on some systems). 5. Run a lightweight verification: npm test or npx playwright test --list depending on scripts. Suggested commands (PowerShell / cross-platform)
+powershell
+# install dependencies
+npm ci
+# install Playwright browsers
+npx playwright install
+# run unit/api tests
+npm test
+# run Playwright E2E tests
+npx playwright test
+Outputs - Created directories and placeholder files in targetPath. - Verification logs for dependency install and sample test runs. - A summary list of any placeholders that require manual editing. Safety & constraints - The agent will not overwrite existing non-placeholder files unless force=true is set. - The agent will not embed secrets into scaffolded files; secrets must be provided separately. Example usages - Scaffold without installing deps: { "task": "scaffold", "installDeps": false } - Scaffold + install deps: { "task": "scaffold", "installDeps": true } - Describe repo: { "task": "describe" } Maintainer notes - Update this file when adding/removing top-level folders or CI config. - Keep prerequisites in sync with package.json and CI definitions. --- Automation agent specification end.