agents-cli-automation 1.0.16 → 1.0.17

package/package.json

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

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

@@ -4,163 +4,157 @@ description: Snapshot and quick guide for the Playwright + TypeScript+BDD setup
 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
+# Playwright + TypeScript (BDD) — repo snapshot
 
-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`.
+## Current Setup
 
-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.
+- **@playwright/test**: v1.36.0 (or later)
+- **playwright-bdd**: v8.4.2 (latest) — generator that converts Gherkin `.feature` files into Playwright specs
+- **TypeScript**: v5.1.0 (or later)
+
+This repository uses a **generator-based BDD flow**: Gherkin feature files in `tests/features/` are converted to Playwright specs by `bddgen`, and those specs are executed with `@playwright/test`.
+
+## Key Points
+
+- **Generator flow**: the `test` script runs `npx bddgen` (generates specs from features) followed by `npx playwright test` (runs generated specs).
+- **Features**: place Gherkin files in `tests/features/*.feature`.
+- **Steps**: implement step definitions in `tests/steps/*.ts`.
+- **Fixtures**: `tests/fixtures/base.fixture.ts` extends the `playwright-bdd` `test` with custom fixtures like `loginPage`, and is included in the `steps` pattern so `bddgen` can wire fixtures to step handlers.
+- **Config**: `playwright.config.ts` defines BDD config with `defineBddConfig()`, specifying `features`, `steps` (including fixtures first), and `outputDir`.
+
+## Quick Files to Review
 
-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)
 
-Quick runnable example (Sauce Demo)
-----------------------------------
+## Setup & Run Tests
 
-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:
+Install dependencies:
 
 ```bash
-npx playwright test tests/example.spec.ts  # or run `npm test`
+npm install
+npx playwright install
 ```
 
-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
+npm test
+```
 
-## Current setup 
+This runs `npx bddgen` to generate Playwright specs from `.feature` files, then `npx playwright test` to execute them.
 
-- **@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.
+## Example: Sauce Demo Login
 
-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`.
+A working example is included that tests login at https://www.saucedemo.com/ using demo credentials:
+- username: `standard_user`
+- password: `secret_sauce`
 
-## Key points
+**Feature file** (`tests/features/login.feature`):
+```gherkin
+Feature: Login
+  Scenario: Successful login to SauceDemo
+    Given I open the login page
+    When I login with "standard_user" and "secret_sauce"
+    Then I should see the inventory page
+```
 
-- **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.
+**Step definitions** (`tests/steps/loginSteps.ts`):
+```ts
+import { createBdd } from 'playwright-bdd';
+import { expect } from '@playwright/test';
+import { test } from '../fixtures/base.fixture';
 
-## Quick files to review
+const { Given, When, Then } = createBdd(test);
 
-- 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)
+Given('I open the login page', async ({ page }) => {
+  await page.goto('/');
+});
 
-## Run the tests (generator BDD flow)
+When('I login with {string} and {string}', async ({ loginPage }, username: string, password: string) => {
+  await loginPage.login(username, password);
+});
 
-```bash
-npm install
-npm install -D playwright-bdd
-npx playwright install
-npm test
+Then('I should see the inventory page', async ({ page }) => {
+  await expect(page).toHaveURL(/inventory.html/);
+});
 ```
 
-Handling missing bddgen
------------------------
+**Fixtures** (`tests/fixtures/base.fixture.ts`):
+```ts
+import { test as base } from 'playwright-bdd';
+import { LoginPage } from '../pages/login.page';
 
-If you see the message "To get \"bddgen\" CLI please install \"playwright-bdd\" package", you have two options:
+type Fixtures = {
+  loginPage: LoginPage;
+};
 
-- Install the generator (recommended if you use Gherkin features):
+export const test = base.extend<Fixtures>({
+  loginPage: async ({ page }, use) => {
+    await use(new LoginPage(page));
+  },
+});
 
-```bash
-npm install -D playwright-bdd
-npx playwright install
-npm test
+export { expect } from '@playwright/test';
 ```
 
-- 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:
+## Playwright Config
 
-```bash
-npx playwright test
-```
-
-2. Example `package.json` scripts without `bddgen`:
+**Key sections** (`playwright.config.ts`):
+```ts
+import { defineConfig } from '@playwright/test';
+import { defineBddConfig } from 'playwright-bdd';
+
+export default defineConfig({
+  testDir: 'tests',
+  timeout: 30_000,
+  use: {
+    headless: true,
+    viewport: { width: 1280, height: 720 },
+    baseURL: 'https://www.saucedemo.com'
+  }
+});
 
-```json
-"scripts": {
-	"test": "npx playwright test",
-	"playwright:install": "npx playwright install"
-}
+export const bdd = defineBddConfig({
+  features: 'tests/features/**/*.feature',
+  steps: ['tests/fixtures/**/*.ts', 'tests/steps/**/*.ts'],
+  outputDir: 'tests',
+});
 ```
 
+**Important**: Include `tests/fixtures/**/*.ts` **before** `tests/steps/**/*.ts` in the `steps` pattern so fixtures are loaded first and available to step definitions.
 
-## Notes
+## Common Patterns
 
-- 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.
+### Using Fixtures in Steps
 
-## How to enable generator-based BDD later
+To use a custom fixture in step definitions, import the fixture-extended `test` from your fixture file and pass it to `createBdd()`:
 
-- 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.
+```ts
+import { createBdd } from 'playwright-bdd';
+import { test } from '../fixtures/base.fixture';
 
----
+const { Given, When, Then } = createBdd(test);
 
-_Generated: Playwright + TypeScript snapshot and quick guide._
+When('I do something', async ({ myCustomFixture }) => {
+  // myCustomFixture is now available
+});
+```
 
-## Data utilities (read JSON / YAML)
+### Data Utilities
 
-You can add a small utility to load test data from JSON or YAML. Install the YAML parser and optional types:
+Load test data from JSON or YAML files:
 
 ```bash
 npm install js-yaml
 npm install -D @types/js-yaml
 ```
 
-Example TypeScript utility (`tests/utils/readData.ts`):
+Example utility (`tests/utils/readData.ts`):
 
 ```ts
 import fs from 'fs';
@@ -168,58 +162,56 @@ 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}`);
+  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:
+Usage in steps:
 
 ```ts
 import { readData } from '../utils/readData';
 
-const login = readData('tests/data/login.yaml');
-// use `login.username`, `login.password` in your steps
+const loginData = readData('tests/data/users.yaml');
+When('I login as {string}', async ({ page }, username: string) => {
+  const user = loginData[username];
+  // use user.password, etc.
+});
 ```
 
-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
+## Dependency Updates
 
-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`:
+To update dev dependencies to compatible latest versions:
 
 ```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:
+If you encounter peer dependency conflicts or need a fresh install:
 
 ```bash
-# remove lockfile and node_modules then reinstall (cross-platform idea)
+# Windows PowerShell:
+Remove-Item -Recurse -Force node_modules
+Remove-Item package-lock.json
+npm install
+
+# Or on macOS/Linux:
 rm -rf node_modules package-lock.json
 npm install
 ```
 
-- On Windows PowerShell use:
+## Troubleshooting
 
-```powershell
-Remove-Item -Recurse -Force node_modules
-Remove-Item package-lock.json
-npm install
-```
+**"BDD config not found" error**: Ensure `playwright.config.ts` exports `bdd = defineBddConfig({...})` and the `testDir` matches your `outputDir`.
+
+**"Unknown parameter" in generated tests**: Make sure custom fixture files are included in the `steps` pattern **before** step definition files, so fixtures are loaded and available.
 
-- If `npm install` reports peer dependency conflicts or fails, it's usually due to incompatible major versions; I can help resolve those selectively.
+**Tests not found**: Verify `outputDir` in `defineBddConfig()` points to a directory inside (or at) Playwright's `testDir`, typically `'tests'`.
+
+---
 
-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.
+_Updated: Playwright + TypeScript + BDD setup snapshot_