@immense/vue-pom-generator 1.0.58 → 1.0.60

package/README.md

@@ -12,10 +12,11 @@ If you already use Playwright with `getByTestId`, the point is simple: this pack
 - **Injects test ids during Vue compilation, not at runtime.** It hooks into the Vue template compiler and rewrites the compiled template output.
 - **Uses real template signals to name ids and methods.** Click handlers, `v-model`, `id`/`name`, `:to`, wrapper configuration, and a few targeted fallbacks all feed the generated API.
 - **Generates TypeScript POM output as either one aggregate or split per class, always with a stable `index.ts` barrel.**
+- **Describes generated Playwright locators** with deterministic human-readable labels via `Locator.describe()`.
 - **Can generate Playwright fixtures** so tests can request `userListPage` instead of constructing `new UserListPage(page)` manually.
 - **Can fail fast on unnameable wrapper-button actions** so complex inline handlers do not silently degrade into low-signal generated APIs.
 - **Can emit a single C# POM file** for Playwright .NET consumers.
-- **Exposes `virtual:testids`** so your app can import the current collected test-id manifest at runtime.
+- **Exposes `virtual:testids` and `virtual:pom-manifest`** so your app can inspect collected ids and generated POM metadata at runtime.
 - **Ships ESLint rules** to remove legacy manually-authored test ids, ban raw `page` fixture usage in spec callbacks, and discourage raw locator actions on generated getters.
 
 ## What this does not do
@@ -69,12 +70,13 @@ That example is intentionally small, but it shows the real contract:
 The generator does not use one naming trick. It layers several signals.
 
 - **Click actions** prefer semantic handler names such as `save`, `openDetails`, or `runImport`.
+- **Click handlers are instrumented** so generated Playwright helpers can wait on deterministic `__testid_event__` runtime events.
 - **Inputs and wrapper components** prefer `v-model`, wrapper `valueAttribute`, or related model-like bindings.
 - **Native elements** also consider `id` / `name` attributes.
 - **Router links / `:to` bindings** can contribute route-based naming and typed navigation return types when the target can be resolved.
 - **Wrapper components** can be explicit (`nativeWrappers`) or inferred from simple local SFC templates.
 - **Fallback naming exists, but it is intentionally conservative.** That is why `generation.nameCollisionBehavior` exists.
-- **Wrapper-action generation fails fast by default.** The generator blocks button-like wrapper `:handler` expressions that it cannot turn into a semantic action name; set `errorBehavior: "ignore"` if you explicitly want the old permissive fallback.
+- **Wrapper-action generation fails fast.** The generator blocks button-like wrapper `:handler` expressions that it cannot turn into a semantic action name.
 
 Important limit: wrapper inference is helpful, not magical. The current implementation recursively inspects simple local SFC templates for the first inferable primitive (`input`, `textarea`, `select`, `button`, `vselect`, radio/checkbox inputs). It also recognizes some naming patterns like `*Button`. For anything more complex, configure `nativeWrappers` explicitly.
 
@@ -205,7 +207,6 @@ const pomConfig = defineVuePomGeneratorConfig({
     script: { defineModel: true, propsDestructure: true },
   },
   logging: { verbosity: "info" },
-  errorBehavior: "error",
   injection: {
     attribute: "data-testid",
     viewsDir: "src/views",
@@ -218,7 +219,7 @@ const pomConfig = defineVuePomGeneratorConfig({
       AppRadioGroup: { role: "radio", requiresOptionDataTestIdPrefix: true },
     },
     excludeComponents: ["LegacyWidget"],
-    existingIdBehavior: "preserve",
+    existingIdBehavior: "error",
   },
   generation: {
     emit: ["ts", "csharp"],
@@ -226,7 +227,7 @@ const pomConfig = defineVuePomGeneratorConfig({
       namespace: "MyProject.Tests.Generated",
     },
     outDir: "tests/playwright/__generated__",
-    nameCollisionBehavior: "suffix",
+    nameCollisionBehavior: "error",
     router: {
       entry: "src/router/index.ts",
       moduleShims: {
@@ -347,8 +348,8 @@ This is important if you are deciding whether the tool will fit into a real code
 
 - **Dev server:** on startup, it scans the configured Vue page/component/layout directories (or the directories resolved from Nuxt config in Nuxt mode), compiles each `.vue` file into a snapshot, writes the configured TypeScript outputs once, then batches add/change/delete events and regenerates incrementally.
 - **Build:** it generates from the richest build pass it sees, which matters because Vite can run multiple passes (for example SSR plus client). The generator avoids letting a thinner pass clobber a richer one.
-- **Always-on virtual module:** `virtual:testids` is registered whether generation is enabled or disabled.
-- **Generation can be disabled:** `generation: false` still keeps compile-time test-id injection and the virtual module, but skips emitted POM files.
+- **Always-on virtual modules:** `virtual:testids` and `virtual:pom-manifest` are registered whether generation is enabled or disabled.
+- **Generation can be disabled:** `generation: false` still keeps compile-time test-id injection and the virtual modules, but skips emitted POM files.
 
 ## Router-aware navigation: the real semantics
 
@@ -680,27 +681,49 @@ This package registers a Vite virtual module named `virtual:testids`.
 Usage:
 
 ```ts
-import { testIdManifest } from "virtual:testids";
+import { pomManifest, testIdManifest } from "virtual:testids";
 
 console.log(testIdManifest.UserEditorPage);
+console.log(pomManifest.UserEditorPage.entries);
 ```
 
 What it contains:
 
 - an object keyed by component name
-- each value is a sorted array of collected test ids for that component
+- `testIdManifest`: each value is a sorted array of collected test ids for that component
+- `pomManifest`: richer per-component metadata including source file, generated locator/property names, and generated action names
+- each manifest entry also carries `locatorDescription`, which matches the human-readable label used by generated Playwright locators
 
 What it is good for:
 
 - runtime inspection
 - analytics / logging helpers that need the current generated ids
-- debugging what the generator has collected
+- debugging what the generator has collected and generated
+- keeping manifest-driven tools aligned with the same locator descriptions shown in Playwright traces
 
 What it is not:
 
-- a full metadata export
 - a generated source file on disk
 
+## `virtual:pom-manifest`
+
+This package also registers `virtual:pom-manifest` for consumers that only want the richer discoverability surface.
+
+Usage:
+
+```ts
+import { pomManifest } from "virtual:pom-manifest";
+
+console.log(pomManifest.UserEditorPage.sourceFile);
+console.log(pomManifest.UserEditorPage.entries.map(entry => entry.generatedActionNames));
+```
+
+What it contains:
+
+- an object keyed by component/page object model class name
+- for each component: source file, whether it is a view or component, sorted test ids, and rich entry metadata
+- for each entry: test id, semantic name, inferred role, generated property name, generated action names, and collected compiler metadata when available
+
 ## ESLint rules that actually ship
 
 The package exports `@immense/vue-pom-generator/eslint`.
@@ -849,18 +872,6 @@ The sections below follow the actual `VuePomGeneratorPluginOptions` shape from `
   logging: { verbosity: "debug" }
   ```
 
-#### `errorBehavior`
-
-- **What it does:** Controls strict/error behavior for generator checks.
-- **Why it exists:** complex inline handlers can otherwise fall through to generic naming, which makes generated APIs harder to discover and review.
-- **Benefit:** fail-fast behavior is the default, while `"ignore"` or the object form let you opt back into only the permissive checks you want.
-- **Without it:** the default is `"error"`, so unsupported button-wrapper handlers stop generation instead of silently falling back.
-- **Accepted values:**
-  - `"ignore"` — keep permissive defaults for all supported checks
-  - `"error"` — enable error-on-failure behavior for all supported checks (default)
-  - `{ missingSemanticNameBehavior: "ignore" }` — opt out only of the button-wrapper semantic-name check
-- **Current scope:** this first pass is intentionally narrow. The object form currently supports `missingSemanticNameBehavior`, which targets button-like wrappers with `:handler`; value/model-driven wrappers still use their existing naming flow.
-
 ### `injection`
 
 `injection` controls compile-time test-id derivation and template rewriting.
@@ -983,7 +994,7 @@ The sections below follow the actual `VuePomGeneratorPluginOptions` shape from `
 - **What it does:** Chooses what happens when a template already has the target attribute.
 - **Why it exists:** migrations usually start from a mixed codebase with manual ids already present.
 - **Benefit:** lets you migrate gradually (`preserve`), force replacement (`overwrite`), or enforce cleanup (`error`).
-- **Without it:** default is `"preserve"`.
+- **Without it:** default is `"error"`.
 - **Current options:**
   - `"preserve"` — keep the existing attribute
   - `"overwrite"` — replace it with the generated one
@@ -1030,7 +1041,7 @@ Set `generation: false` to keep injection and `virtual:testids` but skip emitted
 - **What it does:** Controls what happens when two generated members inside the same class want the same name.
 - **Why it exists:** collisions happen in real templates, especially when multiple elements share the same handler or weak fallback signals.
 - **Benefit:** lets you decide between strictness and convenience.
-- **Without it:** the generator silently suffixes (`"suffix"`).
+- **Without it:** the generator fails fast (`"error"`).
 - **Current options:**
   - `"error"` — fail fast
   - `"warn"` — warn and suffix

package/RELEASE_NOTES.md

@@ -1,47 +1,45 @@
-● I'll fetch the actual commits and PRs between v1.0.57 and HEAD to generate accurate release
-  notes.
+● ## Highlights
 
-● Based on the commit range v1.0.57..HEAD, only PR #19 is included in this release. Here are the
-  release notes:
+  - **Manifest and locator descriptions**: Page Object Model (POM) manifests now include
+  human-readable descriptions for both routes and locators, improving discoverability and
+  developer experience
+  - **New discoverability module**: Added `pom-discoverability.ts` to centralize description
+  generation and introspection logic
+  - **Enhanced test coverage**: Expanded tests for class generation, virtual modules, and base
+  page functionality
 
-  ---
-
-  ## Highlights
+  ## Changes
 
-  - Pass annotation text through generated click helpers for better test documentation
-  - Resolve Vue compiler and Nuxt kit dependencies from consuming app setups instead of the
-  plugin's own tree
-  - Centralize Playwright video dimension configuration for consistent local and CI test
-  recordings
+  **Core Features**
+  - Added manifest and locator description generation for improved POM documentation (#24)
+  - Implemented new `pom-discoverability.ts` module for centralized description handling
 
-  ## Changes
+  **Generator Improvements**
+  - Enhanced `manifest-generator.ts` with description support (+256 lines)
+  - Updated method generation to include locator descriptions
+  - Improved base page class generation with description metadata
 
-  **Local integration hardening:**
-  - Generated click helpers now accept and document annotation text parameters
-  - Resolve `@vue/compiler-sfc.parse` and `@nuxt/kit` from real consuming-app setups to avoid
-  version mismatches
-  - Add centralized Playwright video dimensions configuration (`playwright-video-dimensions.json`)
-  - Add script to normalize Playwright video settings across local config and CI environments
+  **Plugin & Integration**
+  - Updated virtual module system to support description exports
+  - Enhanced Vite plugin integration for description handling
 
-  **Test coverage improvements:**
-  - Add regression tests for project-local Nuxt kit loading
-  - Enhance Nuxt discovery test coverage with real-world integration scenarios
+  **Testing & Documentation**
+  - Added class generation coverage tests
+  - Expanded virtual test ID tests with description validation
+  - Updated README with new feature documentation
+  - Refreshed generated TypeScript fixtures
 
   ## Breaking Changes
 
-  None.
+  None
 
   ## Pull Requests Included
 
-  - [#19](https://github.com/immense/vue-pom-generator/pull/19) fix: harden local app integration
+  - #24 feat: add manifest and locator descriptions
+  (https://github.com/immense/vue-pom-generator/pull/24)
 
   ## Testing
 
-  Validated with:
-  - `npm run lint`
-  - `npm run typecheck`
-  - `npm run build`
-  - `npm test`
-
-  All tests passing with 258 net lines added across 13 files.
+  All changes include corresponding test coverage. Added new test suites for class generation
+  coverage and expanded virtual module tests to validate description functionality.
 

package/class-generation/base-page.ts

@@ -1,5 +1,5 @@
 import type { PwLocator, PwPage } from "./playwright-types";
-import { TESTID_CLICK_EVENT_NAME, TESTID_CLICK_EVENT_STRICT_FLAG } from "../click-instrumentation";
+import { TESTID_CLICK_EVENT_NAME } from "../click-instrumentation";
 import type { TestIdClickEventDetail } from "../click-instrumentation";
 import { Callout } from "./callout";
 import type { CalloutRenderer } from "./callout";
@@ -118,6 +118,10 @@ export class BasePage {
     this.pointer = new Pointer(this.page, this.testIdAttribute, this.callout, pointerRenderer);
   }
 
+  public get screencast(): PwPage["screencast"] {
+    return this.page.screencast;
+  }
+
   private async waitForTestIdClickEventAfter(testId: string, options?: { timeoutMs?: number }): Promise<void> {
     if (!REQUIRE_CLICK_EVENT) {
       return;
@@ -135,7 +139,7 @@ export class BasePage {
     // In that scenario, the click already did its job; don't fail the test infra.
     try {
       await this.page.evaluate(
-        ({ eventName, strictFlagName, expectedTestId, timeoutMs, requireEvent, debug }) => {
+        ({ eventName, expectedTestId, timeoutMs, requireEvent, debug }) => {
           return new Promise<void>((resolve, reject) => {
             const g = globalThis;
             if (!g || typeof g.addEventListener !== "function") {
@@ -143,16 +147,6 @@ export class BasePage {
               return;
             }
 
-            // Mark strict mode in the page so the injected click wrapper can
-            // fail fast (no fallback) when instrumentation is expected.
-            if (requireEvent) {
-              try {
-                type GlobalWithFlag = typeof globalThis & { [k: string]: boolean | undefined };
-                (g as GlobalWithFlag)[strictFlagName] = true;
-              }
-              catch { /* noop */ }
-            }
-
             const cleanup = (timer: ReturnType<typeof setTimeout>, onEvent: (evt: Event) => void) => {
               clearTimeout(timer);
               try {
@@ -216,7 +210,6 @@ export class BasePage {
         },
         {
           eventName: TESTID_CLICK_EVENT_NAME,
-          strictFlagName: TESTID_CLICK_EVENT_STRICT_FLAG,
           expectedTestId: testId,
           timeoutMs,
           requireEvent,
@@ -240,12 +233,22 @@ export class BasePage {
     return `[${this.testIdAttribute}="${testId}"]`;
   }
 
-  protected locatorByTestId(testId: string): PwLocator {
-    return this.page.locator(this.selectorForTestId(testId));
+  protected describeLocator(locator: PwLocator, description?: string): PwLocator {
+    const normalizedDescription = description?.trim();
+    return normalizedDescription ? locator.describe(normalizedDescription) : locator;
+  }
+
+  protected locatorByTestId(testId: string, description?: string): PwLocator {
+    return this.describeLocator(this.page.locator(this.selectorForTestId(testId)), description);
   }
 
-  protected locatorWithinTestIdByLabel(rootTestId: string, label: string, options?: { exact?: boolean }): PwLocator {
-    return this.locatorByTestId(rootTestId).getByLabel(label, { exact: options?.exact ?? true });
+  protected locatorWithinTestIdByLabel(
+    rootTestId: string,
+    label: string,
+    options?: { exact?: boolean; description?: string },
+  ): PwLocator {
+    const locator = this.locatorByTestId(rootTestId).getByLabel(label, { exact: options?.exact ?? true });
+    return this.describeLocator(locator, options?.description);
   }
 
   /**
@@ -495,8 +498,14 @@ export class BasePage {
    * Clicks on an element with the specified data-testid
    * @param testId The data-testid of the element to click
    */
-  public async clickByTestId(testId: string, annotationText: string = "", wait: boolean = true): Promise<void> {
-    await this.pointer.animateCursorToElement(this.selectorForTestId(testId), true, 200, annotationText, {
+  public async clickByTestId(
+    testId: string,
+    annotationText: string = "",
+    wait: boolean = true,
+    description?: string,
+  ): Promise<void> {
+    const locator = this.locatorByTestId(testId, description);
+    await this.pointer.animateCursorToElement(locator, true, 200, annotationText, {
       afterClick: async ({ testId: clickedTestId, instrumented }: AfterPointerClickInfo) => {
         if (!wait) return;
         if (!clickedTestId || !instrumented) return;
@@ -520,14 +529,23 @@ export class BasePage {
     label: string,
     annotationText: string = "",
     wait: boolean = true,
-    options?: { exact?: boolean },
+    options?: { exact?: boolean; description?: string },
   ): Promise<void> {
-    const locator = this.locatorWithinTestIdByLabel(rootTestId, label, { exact: options?.exact });
+    const locator = this.locatorWithinTestIdByLabel(rootTestId, label, {
+      exact: options?.exact,
+      description: options?.description,
+    });
     await this.clickLocator(locator, annotationText, wait);
   }
 
-  protected async fillInputByTestId(testId: string, text: string, annotationText: string = ""): Promise<void> {
-    await this.pointer.animateCursorToElementAndClickAndFill(this.selectorForTestId(testId), text, true, 200, annotationText, {
+  protected async fillInputByTestId(
+    testId: string,
+    text: string,
+    annotationText: string = "",
+    description?: string,
+  ): Promise<void> {
+    const locator = this.locatorByTestId(testId, description);
+    await this.pointer.animateCursorToElementAndClickAndFill(locator, text, true, 200, annotationText, {
       afterClick: async ({ testId: clickedTestId, instrumented }: AfterPointerClickInfo) => {
         if (!clickedTestId || !instrumented) return;
         await this.waitForTestIdClickEventAfter(clickedTestId);
@@ -539,8 +557,14 @@ export class BasePage {
    * Interacts with a vue-select control rooted by a data-testid.
    * This is emitted frequently by the generator; keeping it here reduces per-page duplicated code.
    */
-  protected async selectVSelectByTestId(testId: string, value: string, timeOut: number = 500, annotationText: string = ""): Promise<void> {
-    const root = this.locatorByTestId(testId);
+  protected async selectVSelectByTestId(
+    testId: string,
+    value: string,
+    timeOut: number = 500,
+    annotationText: string = "",
+    description?: string,
+  ): Promise<void> {
+    const root = this.locatorByTestId(testId, description);
     const input = root.locator("input");
 
     await this.pointer.animateCursorToElement(input, false, 200, annotationText);