agents-cli-automation 1.0.9 → 1.0.11

package/package.json

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

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

@@ -1,736 +1,61 @@
----
-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
-{
-  "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",
-    "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"
-  }
-}
-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
-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,
-      },
-    },
-  ],
-});
-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,
-  },
-};
-
-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,
-  },
-
-  [UserRole.AREA_ADMIN]: {
-    view: Scope.OWN_AREA,
-    create: Scope.OWN_AREA,
-    edit: Scope.OWN_AREA,
-    delete: Scope.NONE,
-  },
-
-  [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;
-  }
-) {
-  return apiPost(api, '/scheduling-groups', payload);
-}
-
-export function editSchedulingGroup(
-  api: APIRequestContext,
-  id: number,
-  payload: {
-    area?: string;
-    groupName?: string;
-    allocationsMenu?: boolean;
-    notes?: string;
-  }
-) {
-  return apiPut(api, `/scheduling-groups/${id}`, payload);
-}
-
-export function deleteSchedulingGroup(
-  api: APIRequestContext,
-  id: number
-) {
-  return apiDelete(api, `/scheduling-groups/${id}`);
-}
-
-export function listSchedulingGroups(
-  api: APIRequestContext
-) {
-  return apiGet(api, '/scheduling-groups');
-}
-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];
-  }
-
-  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];
-  }
-
-  static async exists(
-    db: sql.ConnectionPool,
-    name: string
-  ): Promise<boolean> {
-    const record = await this.getByName(db, name);
-    return !!record;
-  }
-
-  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;
-  }
+name: Playwright UI Testing - TypeScript (current repo)
+description: Snapshot and quick guide for the Playwright + TypeScript + BDD setup present in this repository.
+argument-hint: "(no args)"
 
-  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;
-  }
-}
-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;
-};
-
-
-export const test = bddTest.extend<PageFixtures>({
-  homePage: async ({ page }, use) => {
-    const homePage = new HomePage(page);
-    await use(homePage);
-  },
-});
-
-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',
-    });
-
-    await use(api);
-    await api.dispose();
-  },
-
-  apiAsAreaAdmin: async ({}, use) => {
-    const api = await request.newContext({
-      baseURL: process.env.API_BASE_URL,
-      storageState: 'storage/area-admin.json',
-    });
-
-    await use(api);
-    await api.dispose();
-  },
-
-  db: async ({}, use) => {
-    const pool = await getDbPool();
-    await use(pool);
-    await pool.close();
-  },
-});
-
-export { expect };
-13) tests/ui/steps/booking.steps.ts
-typescript
-import { createBdd } from 'playwright-bdd';
-import {test} from '@fixtures/pages.fixture'
-
-
-const { Given, When, Then } = createBdd(test);
-
-Given('user opens the Allocate application', async ({ homePage }) => {
-  await homePage.open();
-  await homePage.isBbcMenuLoaded();
-
-});
-When('user create new facility', async ({homePage}) => {
-
-  await homePage.createFacility()
-
-  await homePage.verifyFacilityAdded()
-
-  await homePage.assertViewFacility()
-
-  await homePage.deleteFacility()
-  
-});
-14) tests/ui/steps/scheduling-groups.steps.ts
-typescript
-
-import { createBdd } from 'playwright-bdd';
-import { test,expect } from '@fixtures/pages.fixture';
-
-const { Given, When, Then } = createBdd(test);
-
-Given('user switches to System Admin role', async ({homePage}) => {
- await homePage.open();
-  const isBbcMenuLoaded = await homePage.isBbcMenuLoaded();
-  expect(isBbcMenuLoaded).toBe(true);
-});
-
-// 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);
-});
-
-test("Scheduling Group Name is mandatory", async ({ apiAsSystemAdmin }) => {
-  const res = await apiAsSystemAdmin.post("/scheduling-groups", {
-    data: { area: "London" },
-  });
-
-  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';
+---
 
-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.
+# Playwright + TypeScript (BDD-capable) — repo snapshot
+
+This file documents the current Playwright + TypeScript testing scaffold in the repository and explains how the BDD workflow is wired right now.
+
+**Key points (current state)**
+- Playwright config exports a BDD config and a standard config: see [playwright.config.ts](playwright.config.ts).
+- Feature files live under `tests/features` (example: [tests/features/login.feature](tests/features/login.feature)).
+- Generated BDD test output (from Playwright-BDD / generator) appears under `.features-gen` (example: [.features-gen/tests/features/login.feature.spec.js](.features-gen/tests/features/login.feature.spec.js)).
+- Fixtures are defined in [tests/fixtures/base.fixture.ts](tests/fixtures/base.fixture.ts). The repository uses the `playwright-bdd` test extension so steps can access fixtures like `loginPage`.
+- Step definitions live in [tests/steps](tests/steps). Example: [tests/steps/loginSteps.ts](tests/steps/loginSteps.ts) — it uses `createBdd(test)` from `playwright-bdd` and registers Given/When/Then steps that operate on the `loginPage` fixture.
+- TypeScript path aliases are configured in [tsconfig.json](tsconfig.json) for convenience (e.g. `@steps/*`, `@pages/*`, `@fixtures/*`).
+
+Files to inspect quickly
+- Playwright config: [playwright.config.ts](playwright.config.ts)
+- TS config / aliases: [tsconfig.json](tsconfig.json)
+- Main fixture: [tests/fixtures/base.fixture.ts](tests/fixtures/base.fixture.ts)
+- Steps: [tests/steps/loginSteps.ts](tests/steps/loginSteps.ts)
+- Feature: [tests/features/login.feature](tests/features/login.feature)
+- Generated spec: [.features-gen/tests/features/login.feature.spec.js](.features-gen/tests/features/login.feature.spec.js)
+- Package scripts: [package.json](package.json)
+
+How the BDD flow works here
+- Edit or add Gherkin features in `tests/features/*.feature` and step implementations in `tests/steps/*.ts`.
+- Generate Playwright specs from features/steps with either Playwright-BDD's generator or a local generator (if present). Common commands:
+  - Use the Playwright-BDD generator (fetches CLI via npx):
+    ```bash
+    npx bddgen
+    ```
+  - Or run a local generator script if your `package.json` defines one (check `package.json` for `generate:bdd`).
+- Generated specs are written to `.features-gen` (this repo currently contains generated files under `.features-gen/tests/features/`). Those generated specs import the repository fixtures and call `Given/When/Then` using the BDD test helpers.
+
+Run the UI BDD tests
+```bash
+# install deps (first time)
+npm install
+npx playwright install chromium
+
+# generate specs (use either bddgen or local generator)
+npx bddgen
+# or (if present) npm run generate:bdd
+
+# run UI project (headed)
+npx playwright test --project=ui --headed
+```
+
+Notes & tips
+- If `npx bddgen` is used it will read `bddConfig` exported from [playwright.config.ts](playwright.config.ts) (the `features` and `steps` globs) and will output generated `.feature.spec.*` files into the configured location.
+- The generated specs reference the repository fixtures (so keep `tests/fixtures/base.fixture.ts` exports stable).
+- If TypeScript path aliases are used, ensure editors and build tooling pick up `tsconfig.json` aliases.
+- If you want me to update any generated-spec import style (e.g. prefer `.ts` vs `.js`, or use path aliases inside generator output), tell me which style you prefer and I will patch the generator and re-generate specs.
+
+If you'd like, I can now:
+- Run `npx bddgen` and then `npx playwright test --project=ui --headed` and show the test output, or
+- Adjust where the `ui` project looks for generated specs (e.g. change `testDir` to `tests/.features-gen`), or
+- Update the generator output to use TypeScript aliases for cleaner imports.