agents-cli-automation 1.0.9 → 1.0.10

package/package.json

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

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

@@ -1,232 +1,59 @@
+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'"
+
 ---
-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, creating a minimal, scalable Playwright-based UI test framework (targeting https://www.saucedemo.com/ by default), and providing recommended developer commands so a new contributor can recreate the workspace and run tests. When to use - When a new contributor needs to scaffold a local copy of this project structure, generate minimal UI test scaffolding (Playwright + page objects + sample tests), and install tooling to run tests and Playwright flows against Saucedemo. Inputs (argument-hint) - task (required): one of scaffold, verify, describe, create-sample-tests. - 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). - uiTarget (optional): URL to target for UI tests; defaults to https://www.saucedemo.com/. 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). - Create Playwright scaffolding when requested, including: - a playwright.config.ts sample if missing, - a tests/ui/saucedemo.spec.ts sample test that logs in and asserts inventory load, - a ui/page page-object for the login and inventory pages, - package.json script recommendations for test, test:ui, and install:browsers. - Optionally install Node dependencies and Playwright browsers when installDeps=true. - Run verification commands (npm test, npx playwright test --list, npx playwright test) and return concise logs. Prerequisites - Node.js (v16+) and npm (or pnpm) installed. - Internet access for package installation and Playwright browser download. Representative scaffolded layout
-package.json (sample scripts)
-playwright.config.ts (generated if missing)
-tests/
-  ui/
-	saucedemo.spec.ts  # sample UI test
-  api/
-	schd-group-create.api.spec.ts
-core/
-  api/
-  auth/
-  db/
-ui/
-  page/
-	LoginPage.ts
-	InventoryPage.ts
-  features/
-  steps/
-utils/
-  readJson.ts
-playwright-report/
-screenshots/
-test-results/
-Scaffold steps (task: scaffold) 1. Validate targetPath exists or create it. 2. Create the repository directory tree (only new directories created). 3. For each file present in the source repo, preserve content. For missing, create placeholders containing a header, responsibilities, and TODO notes. 4. When createSample=true or task=create-sample-tests, add Playwright scaffolding: - playwright.config.ts (simple config using chromium and testDir tests/ui). - tests/ui/saucedemo.spec.ts (sample test: navigate to uiTarget, perform login using standard Saucedemo credentials from sample data, assert inventory list visible). - ui/page/LoginPage.ts and ui/page/InventoryPage.ts page objects. - Update or create package.json scripts: test, test:ui, install:browsers. 5. If installDeps=true, run npm ci (or npm install) then npx playwright install (use --with-deps where appropriate). 6. Run verification: npm run test:ui -- --list or npx playwright test --list and optionally execute the sample test. 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
-npm run test:ui
-Sample tests/ui/saucedemo.spec.ts behavior (generated when requested) - Open uiTarget (defaults to https://www.saucedemo.com/). - Use LoginPage to enter standard_user / secret_sauce and submit. - Wait for InventoryPage to display and assert at least one product is visible. Outputs - Created directories and placeholder files in targetPath. - Generated Playwright UI scaffolding and a runnable sample test when requested. - Verification logs for dependency install and sample test runs. - A summary list of placeholders and recommended edits (e.g., secrets, environment overrides). 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 or via env vars. Example usages - Scaffold without installing deps: { "task": "scaffold", "installDeps": false } - Scaffold + install deps + create samples: { "task": "scaffold", "installDeps": true, "createSample": true } - Create only sample UI tests: { "task": "create-sample-tests", "targetPath": ".", "uiTarget": "https://www.saucedemo.com/" } - Describe repo: { "task": "describe" } Maintainer notes - Keep the generated playwright.config.ts and sample tests minimal — encourage contributors to migrate tests into the repository's existing structure and page objects. - When adding real credentials, instruct users to use environment variables or a secure secrets store. --- Automation agent specification end. Included file templates (drop-in ready) Below are copy-paste-ready templates for the key files you can generate from this agent to produce a runnable Playwright UI framework targeting https://www.saucedemo.com/. 1) package.json (merge with your existing package.json or use as a template)
-json
+
+# 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
 {
-  "name": "poc_bbc",
-  "version": "1.0.0",
-  "type": "commonjs",
   "scripts": {
-    "dbtest": "npx playwright test --project=db",
-    "uitest": "npx bddgen & npx playwright test --project=ui --headed",
+    "start": "node server.js",
+    "build": "tsc -p tsconfig.json",
     "test": "npx playwright test",
-    "test:ui": "npx playwright test --project=ui-plain",
-    "install:browsers": "npx playwright install"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.58.2",
-    "playwright-bdd": "^8.4.2",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
-  },
-  "dependencies": {
-    "dotenv": "^17.2.3",
-    "mssql": "^12.2.0"
+    "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"
   }
 }
-2) playwright.config.ts (the repo already has a BDD config; this snippet adds a plain UI project)
-typescript
-import 'dotenv/config';
-import { defineConfig, devices } from '@playwright/test';
-import { defineBddConfig } from 'playwright-bdd';
+```
 
-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: [
-    {
-      name: 'ui',
-      testDir: './.features-gen',
-      testMatch: '**/*.feature.spec.*',
-      use: { ...devices['Desktop Chrome'], headless: true, baseURL: process.env.UI_BASE_URL },
-    },
-    {
-      name: 'api',
-      testMatch: /.*\.api\.spec\.ts/,
-      use: { browserName: undefined, baseURL: process.env.API_BASE_URL, extraHTTPHeaders: { 'Content-Type': 'application/json' } },
-    },
-    {
-      name: 'db',
-      testMatch: /.*\.db\.spec\.ts/,
-      use: { browserName: undefined },
-    },
-    // Plain UI tests (non-BDD)
-    {
-      name: 'ui-plain',
-      testDir: './tests/ui',
-      use: { ...devices['Desktop Chrome'], headless: true, baseURL: process.env.UI_BASE_URL || 'https://www.saucedemo.com/' },
-    },
-  ],
-});
-3) ui/page/LoginPage.ts (page object)
-typescript
-import { Page } from '@playwright/test';
-
-export class LoginPage {
-  readonly page: Page;
-  constructor(page: Page) { this.page = page; }
-  async goto() { await this.page.goto('/'); }
-  async login(username: string, password: string) {
-    await this.page.fill('#user-name', username);
-    await this.page.fill('#password', password);
-    await this.page.click('#login-button');
-  }
-}
-4) ui/page/InventoryPage.ts (page object)
-typescript
-import { Page, Locator } from '@playwright/test';
-
-export class InventoryPage {
-  readonly page: Page;
-  readonly items: Locator;
-  constructor(page: Page) { this.page = page; this.items = page.locator('.inventory_item'); }
-  async isLoaded(): Promise<boolean> { return await this.items.first().isVisible(); }
-  getItems(): Locator { return this.items; }
-}
-5) tests/ui/saucedemo.spec.ts (plain Playwright test)
-typescript
-import { test, expect } from '@playwright/test';
-import { LoginPage } from '../../ui/page/LoginPage';
-import { InventoryPage } from '../../ui/page/InventoryPage';
-
-test.describe('Saucedemo smoke', () => {
-  test('login and inventory visible', async ({ page, baseURL }) => {
-    const login = new LoginPage(page);
-    const inventory = new InventoryPage(page);
-    await page.goto(baseURL || 'https://www.saucedemo.com/');
-    await login.login('standard_user', 'secret_sauce');
-    await expect(page.locator('.inventory_list')).toBeVisible();
-    await expect(inventory.getItems().first()).toBeVisible();
-  });
-});
-6) .env.example (environment variables sample)
-text
-UI_BASE_URL=https://www.saucedemo.com/
-API_BASE_URL=http://localhost:3000
-Usage notes - The templates above are ready to paste into files. The agent's scaffold task may create them automatically when createSample=true. - To run locally after creating files:
-powershell
-npm ci
-npm run install:browsers
-npm run test:ui
-- The test uses Saucedemo public credentials: standard_user / secret_sauce. If you want, I can now: (choose one) - Generate these files automatically in the repo (I will create the files listed above). - Or leave this agent file as the canonical template and not modify the filesystem. Repository file list and embedded key file contents Below is a repository file list (captured from the workspace) followed by the full contents of selected key files (UI, tests, core helpers). Use these as drop-in references when running the agent's create/scaffold actions. File list (workspace snapshot):
-c:\poc_bbc\workflows\schd-group\api\schd-group.api.ts
-c:\poc_bbc\workflows\schd-group\invariants\db.invariants.ts
-c:\poc_bbc\workflows\schd-group\invariants\api.invariants.ts
-c:\poc_bbc\workflows\schd-group\invariants\permission.invariants.ts
-c:\poc_bbc\core\permission\permission.types.ts
-c:\poc_bbc\core\permission\permission.schd-group.ts
-c:\poc_bbc\workflows\schd-group\db\schd-group.queries.ts
-c:\poc_bbc\core\auth\roles.ts
-c:\poc_bbc\core\db\queries.ts
-c:\poc_bbc\core\db\connection.ts
-c:\poc_bbc\tsconfig.json
-c:\poc_bbc\core\api\apiClient.ts
-c:\poc_bbc\playwright.config.ts
-c:\poc_bbc\package.json
-c:\poc_bbc\package-lock.json
-c:\poc_bbc\bitbucket-pipelines.yml
-c:\poc_bbc\.gitignore
-c:\poc_bbc\.github\agents\automation.md.agent.md
-c:\poc_bbc\tests\utils\readJson.ts
-c:\poc_bbc\tests\utils\formFiller.ts
-c:\poc_bbc\tests\fixtures\test.fixture.ts
-c:\poc_bbc\tests\fixtures\pages.fixture.ts
-c:\poc_bbc\tests\types\formField.ts
-c:\poc_bbc\tests\ui\steps\scheduling-groups.steps.ts
-c:\poc_bbc\tests\ui\steps\booking.steps.ts
-c:\poc_bbc\tests\ui\features\scheduling-groups.feature
-c:\poc_bbc\tests\ui\features\booking.feature
-c:\poc_bbc\tests\ui\page\HomePage.ts
-c:\poc_bbc\tests\db\01-connection.db.spec.ts
-c:\poc_bbc\tests\api\schd-group-create.api.spec.ts
-c:\poc_bbc\.bitbucket\README.md
-c:\poc_bbc\.bitbucket\pull_request_template.md
-c:\poc_bbc\tests\data\facilityFormData.json
-Embedded key file contents 1) package.json
-json
-{
-  "name": "poc_bbc",
-  "version": "1.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "dbtest": "npx playwright test --project=db",
-    "uitest": "npx bddgen & npx playwright test --project=ui --headed"
-
-    
-  },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs",
-  "devDependencies": {
-    "@playwright/test": "^1.58.2",
-    "@types/mssql": "^9.1.9",
-    "@types/node": "^25.2.3",
-    "playwright-bdd": "^8.4.2",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
-  },
-  "dependencies": {
-    "dotenv": "^17.2.3",
-    "mssql": "^12.2.0"
-  }
-}
-2) playwright.config.ts
-typescript
+### 3. Playwright Configuration (playwright.config.ts)
+```typescript
 import 'dotenv/config';
 import { defineConfig, devices } from '@playwright/test';
 import { defineBddConfig } from 'playwright-bdd';
@@ -300,437 +127,352 @@ export default defineConfig({
     },
   ],
 });
-3) core/api/apiClient.ts
-typescript
-import type { APIRequestContext, APIResponse } from "@playwright/test";
-
-export const apiGet = (
-  request: APIRequestContext,
-  url: string,
-): Promise<APIResponse> => {
-  return request.get(url);
-};
-
-export const apiPost = <T>(
-  request: APIRequestContext,
-  url: string,
-  payload?: T,
-): Promise<APIResponse> => {
-  return request.post(url, { data: payload });
-};
-
-export const apiPut = <T>(
-  request: APIRequestContext,
-  url: string,
-  payload?: T,
-): Promise<APIResponse> => {
-  return request.put(url, { data: payload });
-};
-
-export const apiDelete = (
-  request: APIRequestContext,
-  url: string,
-): Promise<APIResponse> => {
-  return request.delete(url);
-};
-4) core/db/connection.ts
-typescript
-import sql from 'mssql';
-
-const config: sql.config = {
-  server: process.env.DB_HOST!,
-  database: process.env.DB_NAME!,
-  user: process.env.DB_USER,
-  password: process.env.DB_PASSWORD,
-  options: {
-    trustServerCertificate: true,
-  },
-};
+```
+
+### 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';
 
-export async function getDbPool(): Promise<sql.ConnectionPool> {
-  return sql.connect(config);
-}
-5) core/db/queries.ts
-typescript
-import type { ConnectionPool } from 'mssql';
-
-export async function listTables(db: ConnectionPool) {
-  const result = await db.request().query(`
-    SELECT TABLE_SCHEMA, TABLE_NAME
-    FROM INFORMATION_SCHEMA.TABLES
-    WHERE TABLE_TYPE = 'BASE TABLE'
-  `);
-
-  return result.recordset;
-}
-6) core/auth/roles.ts
-typescript
-export enum UserRole {
-  SYSTEM_ADMIN = 'SYSTEM_ADMIN',
-  AREA_ADMIN = 'AREA_ADMIN',
-  VIEW_ONLY = 'VIEW_ONLY',
-}
-7) core/permission/permission.types.ts
-typescript
-export enum Scope {
-  ANY = 'ANY',
-  OWN_AREA = 'OWN_AREA',
-  NONE = 'NONE',
-}
-8) core/permission/permission.schd-group.ts
-typescript
-import { UserRole } from '../auth/roles';
-import { Scope } from './permission.types';
-
-export type SchedulingGroupPermissions = {
-  view: Scope;
-  create: Scope;
-  edit: Scope;
-  delete: Scope;
-};
-
-export const schedulingGroupPermissions: Record<
-  UserRole,
-  SchedulingGroupPermissions
-> = {
-  [UserRole.SYSTEM_ADMIN]: {
-    view: Scope.ANY,
-    create: Scope.ANY,
-    edit: Scope.ANY,
-    delete: Scope.ANY,
-  },
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DATA_DIR = path.join(path.resolve(__dirname, '..'), 'data');
 
-  [UserRole.AREA_ADMIN]: {
-    view: Scope.OWN_AREA,
-    create: Scope.OWN_AREA,
-    edit: Scope.OWN_AREA,
-    delete: Scope.NONE,
-  },
+export type JsonObject = Record<string, unknown>;
 
-  [UserRole.VIEW_ONLY]: {
-    view: Scope.OWN_AREA,
-    create: Scope.NONE,
-    edit: Scope.NONE,
-    delete: Scope.NONE,
-  },
-};
-9) workflows/schd-group/api/schd-group.api.ts
-typescript
-import { APIRequestContext } from '@playwright/test';
-import {
-  apiGet,
-  apiPost,
-  apiPut,
-  apiDelete,
-} from '../../../core/api/apiClient';
-
-export function createSchedulingGroup(
-  api: APIRequestContext,
-  payload: {
-    area: string;
-    groupName: string;
-    allocationsMenu?: boolean;
-    notes?: string;
+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);
+    });
   }
-) {
-  return apiPost(api, '/scheduling-groups', payload);
-}
 
-export function editSchedulingGroup(
-  api: APIRequestContext,
-  id: number,
-  payload: {
-    area?: string;
-    groupName?: string;
-    allocationsMenu?: boolean;
-    notes?: string;
+  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;
   }
-) {
-  return apiPut(api, `/scheduling-groups/${id}`, payload);
 }
+```
 
-export function deleteSchedulingGroup(
-  api: APIRequestContext,
-  id: number
-) {
-  return apiDelete(api, `/scheduling-groups/${id}`);
+### 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);
+  }
 
-export function listSchedulingGroups(
-  api: APIRequestContext
-) {
-  return apiGet(api, '/scheduling-groups');
+  static async getFormDataByScenario(scenarioName: string) {
+    const data = await this.loadFormData();
+    return DataReader.getRecordByKey(data, 'scenario', scenarioName);
+  }
 }
-10) workflows/schd-group/db/schd-group.queries.ts
-typescript
-import sql from 'mssql';
-
-export class SchedulingGroupQueries {
-  static async getByName(
-    db: sql.ConnectionPool,
-    name: string
-  ) {
-    const result = await db
-      .request()
-      .input('name', sql.VarChar, name)
-      .query(`
-        SELECT *
-        FROM scheduling_groups
-        WHERE scheduling_group_name = @name
-      `);
-
-    return result.recordset[0];
+```
+
+### 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;
   }
 
-  static async getById(
-    db: sql.ConnectionPool,
-    id: number
-  ) {
-    const result = await db
-      .request()
-      .input('id', sql.Int, id)
-      .query(`
-        SELECT *
-        FROM scheduling_groups
-        WHERE id = @id
-      `);
-
-    return result.recordset[0];
+  async navigateTo(url: string) {
+    await this.page.goto(url);
   }
 
-  static async exists(
-    db: sql.ConnectionPool,
-    name: string
-  ): Promise<boolean> {
-    const record = await this.getByName(db, name);
-    return !!record;
+  async click(selector: string) {
+    await this.page.click(selector);
   }
 
-  static async listByArea(
-    db: sql.ConnectionPool,
-    area: string
-  ) {
-    const result = await db
-      .request()
-      .input('area', sql.VarChar, area)
-      .query(`
-        SELECT *
-        FROM scheduling_groups
-        WHERE area = @area
-      `);
-
-    return result.recordset;
+  async fill(selector: string, text: string) {
+    await this.page.fill(selector, text);
   }
 
-  static async getHistory(
-    db: sql.ConnectionPool,
-    groupId: number
-  ) {
-    const result = await db
-      .request()
-      .input('id', sql.Int, groupId)
-      .query(`
-        SELECT *
-        FROM scheduling_group_history
-        WHERE scheduling_group_id = @id
-        ORDER BY amended_date DESC
-      `);
-
-    return result.recordset;
+  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();
   }
 }
-11) tests/fixtures/pages.fixture.ts
-typescript
-import { test as bddTest } from 'playwright-bdd';
-import { expect } from '@playwright/test';
-import { HomePage } from '../ui/page/HomePage'; 
+```
 
-export type PageFixtures = {
-  homePage: HomePage;
-};
+### 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"]';
 
-export const test = bddTest.extend<PageFixtures>({
-  homePage: async ({ page }, use) => {
-    const homePage = new HomePage(page);
-    await use(homePage);
-  },
-});
+  constructor(page: import('@playwright/test').Page) {
+    super(page);
+  }
 
-export { expect };
-12) tests/fixtures/test.fixture.ts
-typescript
-import {
-  test as base,
-  expect,
-  request,
-  APIRequestContext,
-} from '@playwright/test';
-import sql from 'mssql';
-import { getDbPool } from '../../core/db/connection';
-
-type TestFixtures = {
-  apiAsSystemAdmin: APIRequestContext;
-  apiAsAreaAdmin: APIRequestContext;
-  db: sql.ConnectionPool;
-};
-
-export const test = base.extend<TestFixtures>({
-  apiAsSystemAdmin: async ({}, use) => {
-    const api = await request.newContext({
-      baseURL: process.env.API_BASE_URL,
-      storageState: 'storage/system-admin.json',
-    });
+  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');
+  }
 
-    await use(api);
-    await api.dispose();
+  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);
   },
 
-  apiAsAreaAdmin: async ({}, use) => {
-    const api = await request.newContext({
-      baseURL: process.env.API_BASE_URL,
-      storageState: 'storage/area-admin.json',
-    });
+  inventoryPage: async ({ page }, use) => {
+    const inventoryPage = new InventoryPage(page);
+    await use(inventoryPage);
+  },
 
-    await use(api);
-    await api.dispose();
+  formPage: async ({ page }, use) => {
+    const formPage = new FormPage(page);
+    await use(formPage);
   },
 
-  db: async ({}, use) => {
-    const pool = await getDbPool();
-    await use(pool);
-    await pool.close();
+  authenticatedUser: async ({ page, loginPage }, use) => {
+    await loginPage.goto();
+    await loginPage.login('standard_user', 'secret_sauce');
+    await use({ page, loginPage });
   },
 });
 
 export { expect };
-13) tests/ui/steps/booking.steps.ts
-typescript
-import { createBdd } from 'playwright-bdd';
-import {test} from '@fixtures/pages.fixture'
+```
 
+### 12. Simple Test Example
+This template focuses on Playwright-BDD generated tests (`tests/.features-gen`).
 
-const { Given, When, Then } = createBdd(test);
+### 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
 
-Given('user opens the Allocate application', async ({ homePage }) => {
-  await homePage.open();
-  await homePage.isBbcMenuLoaded();
+  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
+```
 
-});
-When('user create new facility', async ({homePage}) => {
+### 14. Test Data Files
 
-  await homePage.createFacility()
+**tests/data/users.json**
+```json
+{
+  "users": [
+    {
+      "id": "1",
+      "username": "standard_user",
+      "password": "secret_sauce",
+      "email": "user@example.com",
+      "firstName": "John",
+      "lastName": "Doe"
+    }
+  ]
+}
+```
 
-  await homePage.verifyFacilityAdded()
+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.
 
-  await homePage.assertViewFacility()
+**tests/data/config.yaml**
+```yaml
+app:
+  url: https://www.saucedemo.com/
+  timeout: 30000
+users:
+  standard:
+    username: standard_user
+    password: secret_sauce
+```
 
-  await homePage.deleteFacility()
-  
-});
-14) tests/ui/steps/scheduling-groups.steps.ts
-typescript
+# Run Tests
 
-import { createBdd } from 'playwright-bdd';
-import { test,expect } from '@fixtures/pages.fixture';
+```bash
+# Run all tests in parallel
+npm test
 
-const { Given, When, Then } = createBdd(test);
+# Run with headed browser
+npm run test:headed
 
-Given('user switches to System Admin role', async ({homePage}) => {
- await homePage.open();
-  const isBbcMenuLoaded = await homePage.isBbcMenuLoaded();
-  expect(isBbcMenuLoaded).toBe(true);
-});
+# Debug mode
+npm run test:debug
 
-// When('user navigates to Scheduling Groups page', async ({homePage}) => {
-//   // From: tests\ui\features\scheduling-groups.feature:16:5
-// });
-
-// When('user creates a scheduling group {string} in {string} with allocations menu {string}', async ({}, arg: string, arg1: string, arg2: string) => {
-//   // Step: And user creates a scheduling group "Auto_SystemAdmin_" in "Manchester" with allocations menu "Yes"
-//   // From: tests\ui\features\scheduling-groups.feature:17:5
-// });
-
-// Then('user can see the new scheduling group in the list', async ({}) => {
-//   // Step: Then user can see the new scheduling group in the list
-//   // From: tests\ui\features\scheduling-groups.feature:18:5
-// });
-15) tests/ui/features/booking.feature
-feature
-@smoke
-Feature: Booking navigation
-
-  Scenario: Navigate to Facility Catalogue
-    Given user opens the Allocate application
-    When user create new facility
-16) tests/ui/features/scheduling-groups.feature
-feature
-@smoke @scheduling-groups
-Feature: Scheduling Groups Management
-
-  @system-admin
-  Scenario: System Admin - Create a new Scheduling Group in any area
-    Given user opens the Allocate application
-    And user switches to System Admin role
-    When user navigates to Scheduling Groups page
-    And user creates a scheduling group "Auto_SystemAdmin_" in "Area" 
-    Then user can see the new scheduling group in the list
-17) tests/ui/page/HomePage.ts (already present in repo)
-typescript
-<content from existing file - see repo for full source>
-18) tests/api/schd-group-create.api.spec.ts
-typescript
-import { test, expect } from "../../tests/fixtures/test.fixture";
-import { createSchedulingGroup } from "../../workflows/schd-group/api/schd-group.api";
-import { SchedulingGroupQueries } from "../../workflows/schd-group/db/schd-group.queries";
-import { assertGroupExists } from "../../workflows/schd-group/invariants/db.invariants";
-
-test("System Admin can create Scheduling Group in any Area", async ({apiAsSystemAdmin,db}) => {
-  const payload = {
-    area: "Manchester",
-    groupName: `Auto_${Date.now()}`,
-  };
-
-
-  //api
-  const res = await createSchedulingGroup(apiAsSystemAdmin, payload);
-  expect(res.status()).toBe(201);
-
-  const record = await SchedulingGroupQueries.getByName(db, payload.groupName);
-
-  //db
-  assertGroupExists(record);
-});
+# Run BDD scenarios (uses ts-node)
+npm run test:bdd
+```
 
-test("Scheduling Group Name is mandatory", async ({ apiAsSystemAdmin }) => {
-  const res = await apiAsSystemAdmin.post("/scheduling-groups", {
-    data: { area: "London" },
-  });
+# BDD generation + run
 
-  expect(res.status()).toBe(400);
-});
-19) tests/db/01-connection.db.spec.ts
-typescript
-import { test, expect } from '../../tests/fixtures/test.fixture';
-import { listTables } from '../../core/db/queries';
-
-test('Tables exist', async ({ db }) => {
-  const tables = await listTables(db);
-  expect(tables.length).toBeGreaterThan(0);
-});
-20) tests/utils/readJson.ts
-typescript
-import fs from 'fs';
-import path from 'path';
-import { FormField } from '../types/formField';
+```bash
+# Generate Playwright-BDD test files (outputs to tests/.features-gen)
+npx bddgen
 
-export async function readJSON(fileName: string): Promise<Record<string, FormField>> {
-  const filePath = path.resolve(__dirname, `../data/${fileName}`);
-  const rawData = fs.readFileSync(filePath, 'utf-8');
-  const data: Record<string, FormField> = JSON.parse(rawData);
-  return data;
-}
-21) tests/utils/formFiller.ts (full implementation included in repo)
-typescript
-<content from existing file - see repo for full source>
-22) tests/types/formField.ts (included above) 23) tests/data/facilityFormData.json (included above) --- Notes - I embedded the full contents of many small files above; for very large source files (like formFiller.ts and HomePage.ts) I included a placeholder pointer to the existing file since the full content is already present in the repository and shown earlier in this document. If you'd like, I can paste their complete contents here as well. - Next I can: (choose) - Auto-generate the Playwright UI scaffold files from the templates (create the files in the repo). - Leave this agent file as the single source of templates and not modify the filesystem.
+# 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.