agents-cli-automation 1.0.12 → 1.0.14

package/package.json

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

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

@@ -6,6 +6,14 @@ argument-hint: "(no args)"
 
 # 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
@@ -13,13 +21,15 @@ This document explains the current Playwright + TypeScript scaffold and details
 - Step definitions that consume fixtures via `playwright-bdd`
 
 **Key points (current state and recommended layout)**
-- Playwright config exports both the regular `PlaywrightTestConfig` and a `bddConfig` used by generators: see [playwright.config.ts](playwright.config.ts).
+- 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/test` and registers fixtures (for example `loginPage`) — when using BDD, expose those fixtures so step files can receive them.
+- 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` by default when using `npx bddgen` and the exported `bddConfig` globs.
+- 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
 - Playwright config: [playwright.config.ts](playwright.config.ts)
@@ -35,35 +45,49 @@ Files to inspect or add quickly
 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`) so both direct specs and generated BDD specs can reuse them.
+- 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`). Note: some generator tools require specific versions of `@cucumber/cucumber` or other peer deps; if generator errors occur, either install the missing peer or use the direct-spec option below.
+- 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):
 
 ```bash
-npm install
 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
 ```
 
-Generator flow (if you want `.features-gen` generated specs):
+Or use the npm test script (auto-runs bddgen + test together):
 
 ```bash
-npm install
-npx bddgen
-npx playwright test --project=ui
+npm test
 ```
-
-Notes & tips
+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.
-- If `npx bddgen` errors with a missing module like `@cucumber/cucumber`, install the required peer dependency (for example `npm install --save-dev @cucumber/cucumber`) or prefer the direct-spec flow until generator versions are aligned.
+- 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, or
-- Add full `tests/steps/*.ts` step definitions wired to the fixtures and attempt to re-run `npx bddgen` to regenerate specs, or
-- Initialize Git + CI and wire the test into a workflow.
+- 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