agents-cli-automation 1.0.8 → 1.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-cli-automation",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Agents CLI",
   "type": "module",
   "bin": {

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

@@ -1,69 +1,478 @@
-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
+name: Create Playwright Framework - UI Testing (TypeScript)
+description: Creates a production-ready Playwright UI automation framework in TypeScript with fixtures, configs, and test examples.
+argument-hint: "framework requirements, e.g., 'TypeScript with UI tests'"
+
+---
+
+# Playwright UI Testing Framework - TypeScript
+
+This agent creates a production-ready Playwright framework in TypeScript optimized for UI automation and developer DX.
+
+## Capabilities
+- **TypeScript** - typed page objects, helpers, and fixtures
+- First-class `@playwright/test` integration with `playwright.config.ts`
+- UI, component, and end-to-end testing
+- **Playwright BDD** (optional) - Gherkin scenarios with TypeScript step definitions
+- **Page Object Model (POM)** - Typed page classes
+- **Fixtures** - Pre-built browser & page fixtures
+- **Parallel execution** - Tests run concurrently 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
+- TypeScript knowledge (basic)
+
+## Setup Instructions
+
+### 1. Install Dependencies (Chromium Only)
+```bash
+npm install
+npm install --save-dev typescript ts-node @types/node @playwright/test playwright
+npm install --save-dev playwright-bdd csv-parser js-yaml @types/csv-parser
+npx playwright install chromium
+```
+
+### 2. Update package.json
+Add TypeScript-related scripts and keep Playwright commands:
+```json
+{
+  "scripts": {
+    "start": "node server.js",
+    "build": "tsc -p tsconfig.json",
+    "test": "npx playwright test",
+    "test:headed": "npx playwright test --headed",
+    "test:debug": "npx playwright test --debug",
+    "test:ui": "npx playwright show-report",
+    "test:bdd": "npx playwright test --project=ui",
+    "test:bdd:report": "npx playwright test --project=ui --reporter=json"
+  }
+}
+```
+
+### 3. Playwright Configuration (playwright.config.ts)
+```typescript
+import 'dotenv/config';
+import { defineConfig, devices } from '@playwright/test';
+import { defineBddConfig } from 'playwright-bdd';
+
+// BDD config for UI tests
+export const bddConfig = defineBddConfig({
+  features: ['tests/ui/features/**/*.feature'],
+  steps: [
+    'tests/ui/steps/**/*.steps.ts',
+    'tests/fixtures/pages.fixture.ts',
+  ],
+});
+
+export default defineConfig({
+  testDir: './tests',
+  timeout: 20 * 1000,
+  expect: {
+    timeout: 10 * 1000,
+  },
+  retries: process.env.CI ? 1 : 0,
+  reporter: [
+    ['html', { open: 'never' }],
+    ['list'],
+  ],
+  use: {
+    trace: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure'
+  },
+
+  projects: [
+    // =======================
+    // UI BDD TESTS
+    // =======================
+    {
+      name: 'ui',
+      testDir: './.features-gen',       // folder where Playwright-BDD generates .feature.spec.ts
+      testMatch: '**/*.feature.spec.*', // match .ts or .js files
+      use: {
+        ...devices['Desktop Chrome'],
+        headless: true,
+        baseURL: process.env.UI_BASE_URL,
+      },
+
+    },
+
+    // =======================
+    // API TESTS
+    // =======================
+    {
+      name: 'api',
+      testMatch: /.*\.api\.spec\.ts/,
+      use: {
+        browserName: undefined,
+        baseURL: process.env.API_BASE_URL,
+        extraHTTPHeaders: {
+          'Content-Type': 'application/json',
+        },
+      },
+    },
+
+    // =======================
+    // DB TESTS (NO BROWSER)
+    // =======================
+    {
+      name: 'db',
+      testMatch: /.*\.db\.spec\.ts/,
+      use: {
+        browserName: undefined,
+      },
+    },
+  ],
+});
+```
+
+### 4. Project Structure (TypeScript)
+```
+project/
+├── tests/
+│   ├── fixtures/
+│   │   └── base.fixture.ts          # Shared fixtures (typed)
+│   ├── pages/
+│   │   ├── BasePage.ts              # Base page object
+│   │   ├── LoginPage.ts             # Login page object
+│   │   ├── InventoryPage.ts         # Inventory page object
+│   │   └── FormPage.ts              # Form page object
+│   ├── utils/                       # Utility functions
+│   │   ├── 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
+│   ├── .features-gen/               # Generated Playwright-BDD tests (.feature.spec.ts)
+├── playwright.config.ts             # Playwright config (TypeScript)
+├── tsconfig.json
+└── package.json
+```
+
+
+
+### 6. Data Reader Utility (tests/utils/dataReader.ts)
+```typescript
+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 type JsonObject = Record<string, unknown>;
+
+export class DataReader {
+  static readJSON<T = any>(filename: string): T {
+    const filePath = path.join(DATA_DIR, filename);
+    const data = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(data) as T;
+  }
+
+  static readYAML<T = any>(filename: string): T {
+    const filePath = path.join(DATA_DIR, filename);
+    const data = fs.readFileSync(filePath, 'utf-8');
+    return yaml.load(data) as T;
+  }
+
+  static async readCSV(filename: string): Promise<Record<string, string>[]> {
+    const filePath = path.join(DATA_DIR, filename);
+    return new Promise((resolve, reject) => {
+      const records: Record<string, string>[] = [];
+      fs.createReadStream(filePath)
+        .pipe(csv())
+        .on('data', (data: Record<string, string>) => records.push(data))
+        .on('end', () => resolve(records))
+        .on('error', reject);
+    });
+  }
+
+  static getRecordByKey<T extends Record<string, any>>(data: T[] | undefined, key: string, value: any) {
+    if (Array.isArray(data)) {
+      return data.find(record => record[key] === value);
+    }
+    return undefined;
+  }
+}
+```
+
+### 7. Form Helper Utility (tests/utils/formHelper.ts)
+```typescript
+import type { Page } from '@playwright/test';
+
+export class FormHelper {
+  readonly page: Page;
+  constructor(page: Page) {
+    this.page = page;
+  }
+
+  async fillInput(selector: string, value: string) {
+    await this.page.fill(selector, value);
+  }
+
+  async fillTextArea(selector: string, value: string) {
+    await this.page.locator(selector).fill('');
+    await this.page.locator(selector).type(value, { delay: 50 });
+  }
+
+  async selectDropdown(dropdownSelector: string, optionText: string) {
+    await this.page.click(dropdownSelector);
+    await this.page.click(`text=\"${optionText}\"`);
+  }
+
+  async selectRadioButton(labelText: string) {
+    const label = this.page.locator(`label:has-text(\"${labelText}\")`);
+    const radioId = await label.getAttribute('for');
+    if (radioId) await this.page.locator(`#${radioId}`).click();
+  }
+
+  async checkCheckbox(labelText: string) {
+    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();
+    }
+  }
+
+  async checkMultiple(labels: string[]) {
+    for (const label of labels) await this.checkCheckbox(label);
+  }
+
+  async getInputValue(selector: string) {
+    return await this.page.inputValue(selector);
+  }
+
+  async isCheckboxChecked(labelText: string) {
+    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.ts)
+```typescript
+import { DataReader } from './dataReader';
+
+export class TestDataManager {
+  static loadUsers() {
+    return DataReader.readJSON<{ users: any[] }>('users.json');
+  }
+
+  static async loadFormData() {
+    return await DataReader.readCSV('formData.csv');
+  }
+
+  static loadConfig() {
+    return DataReader.readYAML('config.yaml');
+  }
+
+  static getUserByUsername(username: string) {
+    const data = this.loadUsers();
+    return DataReader.getRecordByKey(data.users, 'username', username);
+  }
+
+  static async getFormDataByScenario(scenarioName: string) {
+    const data = await this.loadFormData();
+    return DataReader.getRecordByKey(data, 'scenario', scenarioName);
+  }
+}
+```
+
+### 9. Base Page (tests/pages/BasePage.ts)
+```typescript
+import type { Page } from '@playwright/test';
+
+export class BasePage {
+  readonly page: Page;
+  constructor(page: Page) {
+    this.page = page;
+  }
+
+  async navigateTo(url: string) {
+    await this.page.goto(url);
+  }
+
+  async click(selector: string) {
+    await this.page.click(selector);
+  }
+
+  async fill(selector: string, text: string) {
+    await this.page.fill(selector, text);
+  }
+
+  async getText(selector: string) {
+    return await this.page.textContent(selector);
+  }
+
+  async waitForElement(selector: string, timeout = 5000) {
+    await this.page.waitForSelector(selector, { timeout });
+  }
+
+  async isVisible(selector: string) {
+    return await this.page.locator(selector).isVisible();
+  }
+}
+```
+
+### 10. Page Object - Login (tests/pages/LoginPage.ts)
+```typescript
+import { BasePage } from './BasePage';
+
+export class LoginPage extends BasePage {
+  readonly usernameField = '[data-test="username"]';
+  readonly passwordField = '[data-test="password"]';
+  readonly loginButton = '[data-test="login-button"]';
+
+  constructor(page: import('@playwright/test').Page) {
+    super(page);
+  }
+
+  async goto() {
+    await this.page.goto('https://www.saucedemo.com/');
+  }
+
+  async login(username: string, password: string) {
+    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.ts)
+```typescript
+import { test as base, expect } from '@playwright/test';
+import { LoginPage } from '../pages/LoginPage';
+import { InventoryPage } from '../pages/InventoryPage';
+import { FormPage } from '../pages/FormPage';
+
+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
+This template focuses on Playwright-BDD generated tests (`tests/.features-gen`).
+
+### 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"
+    }
+  ]
+}
+```
+
+Note: Playwright-BDD generates test files into `tests/.features-gen` (via `npx bddgen`) and the `ui` project in `playwright.config.ts` points at `./.features-gen`. Run BDD generation before running the `ui` project.
+
+**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 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.
+
+# Run with headed browser
+npm run test:headed
+
+# Debug mode
+npm run test:debug
+
+# Run BDD scenarios (uses ts-node)
+npm run test:bdd
+```
+
+# BDD generation + run
+
+```bash
+# Generate Playwright-BDD test files (outputs to tests/.features-gen)
+npx bddgen
+
+# Run only the UI BDD project (Playwright picks up generated files in .features-gen)
+npx playwright test --project=ui
+```
+
+## Best Practices
+
+- **Page Object Model**: Encapsulate selectors and flows in typed page classes
+- **Fixtures**: Use `base.fixture.ts` for shared setup/teardown
+- **Test Data**: Externalize in JSON/CSV/YAML and load via `DataReader`
+- **Form Helpers**: Keep complex interactions in `FormHelper` with strong types
+- **BDD Support**: Add Gherkin scenarios and TypeScript step defs when needed
+- **Parallel Execution**: Configure `workers` in `playwright.config.ts`
+- **Type Safety**: Prefer typed interfaces for test data and page objects
+
+Note: This template is TypeScript-first. Copy the structure, install the devDependencies listed, and adjust types/interfaces for your application.