agents-cli-automation 1.0.14 → 1.0.16

package/package.json

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

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

@@ -1,93 +1,225 @@
+
 name: Playwright UI Testing - TypeScript (current repo)
-description: Snapshot and quick guide for the Playwright + TypeScript + BDD setup present in this repository.
+description: Snapshot and quick guide for the Playwright + TypeScript+BDD setup present in this repository.
 argument-hint: "(no args)"
 
----
+----
+# Playwright + TypeScript — repo snapshot
+**Current Setup**
+- **@playwright/test**: pinned to a verified stable version
+- **playwright-bdd**: used in this repo; the `test` script runs `bddgen` to convert Gherkin features into Playwright specs
+- **TypeScript**: pinned to a verified stable version
+
+This scaffold uses a generator-based BDD flow: Gherkin feature files in `tests/features/` are converted to Playwright specs by `bddgen` (from `playwright-bdd`), and those specs are executed with `@playwright/test`.
 
-# Playwright + TypeScript (BDD-capable) — repo snapshot
-
-**Current Setup (Feb 2026) — Latest Pinned**
-- **@playwright/test**: pinned to verified stable version
-- **playwright-bdd**: pinned to verified stable version
-- **typescript**: pinned to verified stable version
-- **@types/node**: pinned to verified stable version
-
-Initial setup installs latest versions, then locks them to prevent unexpected updates.
-
-This document explains the current Playwright + TypeScript scaffold and details the recommended layout for:
-- Page Object Models using `@playwright/test`
-- A small JSON data util
-- Fixtures wired for `playwright-bdd`
-- Step definitions that consume fixtures via `playwright-bdd`
-
-**Key points (current state and recommended layout)**
-- Playwright config uses `defineBddConfig()` from `playwright-bdd` to export the BDD configuration: see [playwright.config.ts](playwright.config.ts). The config includes `features`, `steps`, and `outputDir` patterns with reporter configuration for HTML, JSON, and JUnit outputs.
-- The `ui` project has `testDir: '.features-gen'` and `testMatch: '**/*.feature.spec.{ts,js}'` to discover generated specs.
-- Place Gherkin features in `tests/features/*.feature` (example: [tests/features/login.feature](tests/features/login.feature)).
-- Page Objects: implement page classes under `tests/pages/` (example: `tests/pages/login.page.ts`) and import `Page` from `@playwright/test`.
-- Test data util: add a JSON reader like `tests/utils/data.ts` that loads `tests/data/*.json` so tests/steps can read credentials and fixtures.
-- Fixtures: create `tests/fixtures/base.fixture.ts` that extends `test` from `playwright-bdd` with proper TypeScript type definitions via `CustomFixtures` interface. This ensures fixtures are properly typed (for example `loginPage`). Include the fixtures file in the `steps` pattern in `bddConfig` so the generator can discover them.
-- Steps: implement step definitions under `tests/steps/*.ts`. Use `createBdd(test)` from `playwright-bdd` and register Given/When/Then handlers that accept fixtures (e.g., `loginPage`) and call page object methods.
-- Generated specs: the generator writes Playwright specs into `.features-gen` (configured via `outputDir` in `bddConfig`) when using `npx bddgen`. The generated files are `.feature.spec.js` (or `.ts`) and are discovered by the `ui` project via `testMatch: '**/*.feature.spec.{ts,js}'`.
-- Reporters: HTML (in `playwright-report/`), JSON (for CI integration), and JUnit (for CI/CD pipelines) are configured by default.
-
-Files to inspect or add quickly
+Key points
+- Generator flow: the `test` script runs `npx bddgen` followed by `npx playwright test` to generate specs and run them.
+- Features: put Gherkin files in `tests/features/*.feature`.
+- Steps: add step definitions in `tests/steps/*.ts`. Include fixtures (for example `tests/fixtures/**/*.ts`) in the generator `steps` pattern so `bddgen` can connect them to the test instance.
+- Fixtures: `tests/fixtures/base.fixture.ts` provides typed page-object fixtures used by generated specs and step handlers.
+
+Quick files to review
 - Playwright config: [playwright.config.ts](playwright.config.ts)
-- TS config / aliases: [tsconfig.json](tsconfig.json)
+- TypeScript config: [tsconfig.json](tsconfig.json)
 - Page object example: [tests/pages/login.page.ts](tests/pages/login.page.ts)
-- JSON data util: [tests/utils/data.ts](tests/utils/data.ts)
-- Test data: [tests/data/users.json](tests/data/users.json)
+- JSON data utility: [tests/utils/data.ts](tests/utils/data.ts)
 - Fixtures: [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)
-- Direct Playwright spec (optional): [tests/specs/login.spec.ts](tests/specs/login.spec.ts)
-
-How the flow works here
-- Create page classes that import `Page` from `@playwright/test`; page methods should perform simple interactions and checks (for example, `LoginPage.goto()`, `LoginPage.login()`, `LoginPage.isInventoryVisible()`).
-- Add a small data helper `readTestData(path)` that loads JSON from `tests/data/` so credentials are not hard-coded in steps or specs.
-- Implement `tests/fixtures/base.fixture.ts` that extends Playwright's `test` to provide page-object fixtures (e.g., `loginPage`) with proper TypeScript types using a `CustomFixtures` type definition. This ensures type safety and IDE support for all fixtures.
-- Write step definitions in `tests/steps/*.ts` using `playwright-bdd`'s `createBdd(test)` helper. Example pattern:
-  - import `createBdd` and your `test` fixture: `const { Given, When, Then } = createBdd(test)`
-  - register steps that accept fixtures: `Given('I open login page', async ({ loginPage }) => { await loginPage.goto(); })`.
-- Option A — Generator flow: use `npx bddgen` to turn `.feature` files into Playwright specs in `.features-gen` (generator reads `bddConfig` in `playwright.config.ts`). The `bddConfig` must include:
-  - `features`: glob pattern pointing to `.feature` files
-  - `steps`: glob patterns for step definitions **and fixtures** (e.g., `['tests/steps/**/*.ts', 'tests/fixtures/**/*.ts']`)
-  - `outputDir`: where generated specs are written (default `.features-gen`)
-- Option B — Direct spec flow (recommended for quick runs): write a small `tests/specs/*.ts` Playwright test that imports your fixtures and page objects (no generation). This bypasses generator compatibility issues and runs immediately with `npx playwright test`.
-- Test reports are automatically generated in `playwright-report/` (HTML), `test-results/results.json` (JSON), and `test-results/results.xml` (JUnit) after each run.
-
-Run the direct Playwright spec (no generator required):
+- Features: [tests/features/login.feature](tests/features/login.feature)
+
+Quick runnable example (Sauce Demo)
+----------------------------------
+
+Use https://www.saucedemo.com/ with these demo credentials to get a working test quickly:
+
+- username: `standard_user`
+- password: `secret_sauce`
+
+Here's a minimal Playwright test that performs a login and asserts the inventory page loads:
+
+```ts
+import { test, expect } from '@playwright/test';
+
+test('saucedemo login works', async ({ page }) => {
+	await page.goto('https://www.saucedemo.com/');
+	await page.fill('[data-test="username"]', 'standard_user');
+	await page.fill('[data-test="password"]', 'secret_sauce');
+	await page.click('[data-test="login-button"]');
+	await expect(page).toHaveURL(/inventory.html/);
+	await expect(page.locator('.inventory_list')).toBeVisible();
+});
+```
+
+To run this example locally:
 
 ```bash
+npx playwright test tests/example.spec.ts  # or run `npm test`
+```
+
+If you want, I can update the existing `tests/example.spec.ts` and `tests/pages/login.page.ts` to use this Sauce Demo flow and run the tests here.
+
+
+Run the tests (generator BDD flow):
+
+```bash
+npm install
+npm install -D playwright-bdd
+# Playwright + TypeScript — repo snapshot
+
+## Current setup 
+
+- **@playwright/test** — pinned to a verified stable version.
+- **playwright-bdd** — optional generator used in this repo; the `test` script runs `bddgen` to convert Gherkin features into Playwright specs.
+- **TypeScript** — pinned to a verified stable version.
+
+This repository uses a generator-based BDD flow: Gherkin feature files in `tests/features/` are converted to Playwright specs by `bddgen` (from `playwright-bdd`), and those specs are executed with `@playwright/test`.
+
+## Key points
+
+- **Generator flow**: the `test` script runs `npx bddgen` followed by `npx playwright test` to generate specs and run them.
+- **Features**: place Gherkin files in `tests/features/*.feature`.
+- **Steps**: implement step definitions in `tests/steps/*.ts`. Include fixtures (for example `tests/fixtures/**/*.ts`) in the generator `steps` pattern so `bddgen` can wire them to the test instance.
+- **Fixtures**: `tests/fixtures/base.fixture.ts` provides typed page-object fixtures used by generated specs and step handlers.
+
+## Quick files to review
+
+- Playwright config: [playwright.config.ts](playwright.config.ts)
+- TypeScript config: [tsconfig.json](tsconfig.json)
+- Page object example: [tests/pages/login.page.ts](tests/pages/login.page.ts)
+- JSON data utility: [tests/utils/data.ts](tests/utils/data.ts)
+- Fixtures: [tests/fixtures/base.fixture.ts](tests/fixtures/base.fixture.ts)
+- Steps: [tests/steps/loginSteps.ts](tests/steps/loginSteps.ts)
+- Features: [tests/features/login.feature](tests/features/login.feature)
+
+## Run the tests (generator BDD flow)
+
+```bash
+npm install
+npm install -D playwright-bdd
 npx playwright install
-npx playwright test --project=ui tests/specs/login.spec.ts
-npx playwright show-report  # View HTML report
-npx playwright test --project=ui tests/specs/login.spec.ts
+npm test
 ```
 
-Or use the npm test script (auto-runs bddgen + test together):
+Handling missing bddgen
+-----------------------
+
+If you see the message "To get \"bddgen\" CLI please install \"playwright-bdd\" package", you have two options:
+
+- Install the generator (recommended if you use Gherkin features):
 
 ```bash
+npm install -D playwright-bdd
+npx playwright install
 npm test
 ```
-2"`) to lock dependencies. This prevents unexpected breaking changes on future installs while still allowing patch/minor updates.
-- **Initial Setup Flow**: 
-  1. Install with `"latest"` to get current stable versions
-  2. Verify tests pass with `npm test` or `npx playwright test`
-  3. Replace `"latest"` with the installed versions (run `npm list` to see them)
-  4. Commit pinned versions to version control
-- **Type Safety for Fixtures**: Always create a `CustomFixtures` type interface in `tests/fixtures/base.fixture.ts` that defines all custom fixtures. Extend `test.extend<CustomFixtures>()` for proper TypeScript support.
-- Keep fixtures stable: generated specs import your fixture module, so keep `tests/fixtures/base.fixture.ts` API stable.
-- Always include fixtures in the `steps` pattern (e.g., `steps: [..., 'tests/fixtures/**/*.ts']`) so the generator can detect and use your custom `test` instance.
-- Steps should not import `@playwright/test` directly for test helpers — they should use the fixtures passed by `playwright-bdd` (the `test` instance you pass to `createBdd(test)`). Page objects, however, should import `Page` and be created inside fixtures.
-- The `testMatch` in the `ui` project should match `**/*.feature.spec.{ts,js}` to discover generated specs regardless of language (TypeScript or JavaScript output).
-- Do not spread `bddConfig` properties directly into `defineConfig()` — let `bddConfig` handle its own routing; just pass it as `...bddConfig` and define projects separately to avoid TypeScript conflicts.
-- View reports after test runs: run `npx playwright show-report` to open the HTML report in your browser
-- Steps should not import `@playwright/test` directly for test helpers — they should use the fixtures passed by `playwright-bdd` (the `test` instance you pass to `createBdd(test)`). Page objects, however, should import `Page` and be created inside fixtures.
-- The `testMatch` in the `ui` project should match `**/*.feature.spec.{ts,js}` to discover generated specs regardless of language (TypeScript or JavaScript output).
-
-If you'd like, I can now:
-- Run the direct spec and show results: `npm run test`
-- Troubleshoot BDD generation or test failures
-- Add more page objects and step definitions  
-- Initialize Git + CI and wire automation tests into GitHub Actions workflow
+
+- Skip the generator and run Playwright directly (if you don't use Gherkin features):
+
+1. Remove `npx bddgen &&` from your `test` script in `package.json`, or run Playwright directly:
+
+```bash
+npx playwright test
+```
+
+2. Example `package.json` scripts without `bddgen`:
+
+```json
+"scripts": {
+	"test": "npx playwright test",
+	"playwright:install": "npx playwright install"
+}
+```
+
+
+## Notes
+
+- The `test` script runs `npx bddgen` and then `npx playwright test`. If `playwright-bdd` is not installed, you'll be prompted to run `npm install -D playwright-bdd`.
+- Generated specs are written to the configured output directory (commonly `.features-gen`) and then executed by Playwright.
+
+## How to enable generator-based BDD later
+
+- Install `playwright-bdd` as a dev dependency and add `npx bddgen` to the `test` script.
+- Add step definitions under `tests/steps/` and include fixtures in the generator `steps` pattern.
+
+## Ways I can help
+
+- Add `playwright-bdd` to `devDependencies` and update `package.json` so `npm install` installs it automatically.
+- Add a GitHub Actions workflow that runs `npm test` on push.
+- Expand page objects, feature coverage, or step definitions.
+
+---
+
+_Generated: Playwright + TypeScript snapshot and quick guide._
+
+## Data utilities (read JSON / YAML)
+
+You can add a small utility to load test data from JSON or YAML. Install the YAML parser and optional types:
+
+```bash
+npm install js-yaml
+npm install -D @types/js-yaml
+```
+
+Example TypeScript utility (`tests/utils/readData.ts`):
+
+```ts
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+
+export function readData(filePath: string): any {
+	const ext = path.extname(filePath).toLowerCase();
+	const raw = fs.readFileSync(filePath, 'utf8');
+	if (ext === '.json') return JSON.parse(raw);
+	if (ext === '.yml' || ext === '.yaml') return yaml.load(raw);
+	throw new Error(`Unsupported data format: ${ext}`);
+}
+```
+
+Usage example in a test or step definition:
+
+```ts
+import { readData } from '../utils/readData';
+
+const login = readData('tests/data/login.yaml');
+// use `login.username`, `login.password` in your steps
+```
+
+Tips
+
+- If you prefer importing JSON directly, enable `resolveJsonModule` in `tsconfig.json`.
+- For large or frequently-modified data files, consider caching the parsed result in the utility.
+
+## Dependency updates & provisioning
+
+To update dev dependencies in `package.json` to the latest compatible versions you can use `npm-check-updates` (ncu). The command below updates `devDependencies` in `package.json`:
+
+```bash
+# update devDependencies in package.json
+npx npm-check-updates -u '/.*/' --dep dev
+
+# install updates
+npm install
+```
+
+Notes and troubleshooting
+
+- `npx npm-check-updates -u` only modifies `package.json`. If `package-lock.json` or `node_modules` pin old versions, run a fresh install:
+
+```bash
+# remove lockfile and node_modules then reinstall (cross-platform idea)
+rm -rf node_modules package-lock.json
+npm install
+```
+
+- On Windows PowerShell use:
+
+```powershell
+Remove-Item -Recurse -Force node_modules
+Remove-Item package-lock.json
+npm install
+```
+
+- If `npm install` reports peer dependency conflicts or fails, it's usually due to incompatible major versions; I can help resolve those selectively.
+
+Would you like me to run the `npx npm-check-updates -u '/.*/' --dep dev` and `npm install` commands now, or create a commit/update `package.json` myself? If you prefer, I can also open a PR with the changes.