@immense/vue-pom-generator 1.0.36 → 1.0.38

package/README.md

@@ -45,6 +45,10 @@ If `generation.playwright.fixtures` is enabled, it also emits:
 
 - `tests/playwright/__generated__/fixtures.g.ts` (generated; do not edit)
 
+Generated fixtures automatically prefer matching handwritten override classes from
+`tests/playwright/pom/overrides/<ClassName>.ts` (or the sibling `overrides/` directory next to
+your configured `generation.playwright.customPoms.dir`).
+
 ### Vite config example
 
 ```ts
@@ -147,13 +151,35 @@ export default defineConfig(() => {
 
 Notes:
 
-- `vuePomGenerator(...)` already wires `@vitejs/plugin-vue` internally for non-Nuxt apps.
-- Do not pass `vue()` into `createVuePomGeneratorPlugins(...)`; pass Vue options via `vueOptions`.
+- `vuePomGenerator(...)` wires `@vitejs/plugin-vue` internally by default for standard Vue apps.
+- Do not pass `vue()` into `createVuePomGeneratorPlugins(...)`; pass Vue plugin options via `vueOptions`.
+- When the app should own `vue()` explicitly, set `vuePluginOwnership: "external"` and add `vue()` separately in your Vite config.
 
 - **Injection is enabled by plugin inclusion** (there is no longer an `injection.enabled` flag).
 - **Generation is enabled by default** and can be disabled via `generation: false`.
 - **Router-aware POM helpers are enabled** when `generation.router.entry` is provided (the generator will introspect your router).
 
+### External Vue plugin ownership
+
+If your app should own the core Vue Vite plugin explicitly, add `vue()` yourself and let this package patch the resolved plugin:
+
+```ts
+import vue from "@vitejs/plugin-vue";
+import { defineConfig } from "vite";
+import { defineVuePomGeneratorConfig, vuePomGenerator } from "@immense/vue-pom-generator";
+
+const pomConfig = defineVuePomGeneratorConfig({
+  vuePluginOwnership: "external",
+});
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    ...vuePomGenerator(pomConfig),
+  ],
+});
+```
+
 ### `generation.router`
 
 Controls router introspection for `:to` analysis and navigation helper generation.
@@ -180,6 +206,13 @@ Defaults:
 
 - when `true`: writes `fixtures.g.ts` alongside generated POMs (under `generation.outDir`)
 
+Convention:
+
+- if `tests/playwright/pom/overrides/<ClassName>.ts` exists, the generated fixture for that page/component
+  instantiates the override class instead of the raw generated `Pom.<ClassName>`
+- the override directory is inferred as the sibling `overrides/` directory next to
+  `generation.playwright.customPoms.dir`
+
 ### Vite config example
 
 - `nativeWrappers` describes common wrapper components (e.g. design-system buttons/inputs)
@@ -204,7 +237,9 @@ When you want CI/builds to fail on explicit test ids, pair `existingIdBehavior:
 
 ### ESLint cleanup rule: remove existing test-id attributes
 
-Use the `remove-existing-test-id-attributes` rule to strip explicit test-id attributes from `.vue` files before or while enforcing `existingIdBehavior: "error"`.
+Use the `remove-existing-test-id-attributes` rule to strip explicit test-id usage from `.vue` files before or while enforcing `existingIdBehavior: "error"`.
+
+The fixer handles both template attributes like `data-testid="save-button"` and object-literal keys such as `inputAttr: { 'data-testid': 'save-button' }` inside Vue SFC expressions/scripts.
 
 Add this to your ESLint flat-config file, typically `eslint.config.ts` (or `eslint.config.js` / `eslint.config.mjs` at the project root):
 

package/RELEASE_NOTES.md

@@ -1,33 +1,51 @@
-● ## v1.0.36
+● Now I have enough information to generate the release notes. The main feature is auto-wiring
+  fixture overrides in Playwright test fixtures.
 
-  ### Highlights
+  ```markdown
+  # Release v1.0.38
 
-  - Fixed handler collision suffixes to prevent naming conflicts in strict error mode
-  - Improved handler suffix derivation by skipping unstable leading arguments
-  - Enhanced detection of constant-like member expressions for more stable naming
-  - Added comprehensive test coverage for collision avoidance scenarios
+  ## Highlights
 
-  ### Changes
+  - Playwright fixtures now automatically detect and use handwritten POM override classes
+  - Override classes in `overrides/<ClassName>.ts` are auto-wired when generating fixtures
+  - Enhanced test coverage for class generation and TypeScript compilation
+  - Updated documentation with fixture override conventions
 
-  **Bug Fixes**
-  - Fixed handler collision suffixes when generating test IDs and POM methods (#27dc566)
-  - Skip unstable leading arguments when deriving handler suffixes from function arguments
-  - Check up to 4 arguments (previously 2) to find stable literal/constant values
-  - Validate constant-like root identifiers (e.g., `RebootPreference.Suppress`) before using
-  member expression names
+  ## Changes
 
-  **Testing**
-  - Added test for strict-mode collision avoidance with later stable args
-  - Added utility test coverage for `getRootIdentifierFromMemberChain` function
-  - New test validates `clickRunDeploymentActionAssign` method generation without conflicts
+  ### Playwright Fixture Generation
 
-  ### Pull Requests Included
+  - Fixtures now automatically prefer matching handwritten override classes from the `overrides/`
+  directory
+  - Override directory location is inferred as sibling to `generation.playwright.customPoms.dir`
+  - Generated fixtures import and instantiate override classes when available (e.g.,
+  `tests/playwright/pom/overrides/<ClassName>.ts`)
+  - Added runtime detection of override files via filesystem checks during generation
 
-  - [#1](https://github.com/immense/vue-pom-generator/pull/1) - Add PR release-notes preview
-  comments (merged 2026-02-02, not in v1.0.36 window)
+  ### Documentation
+
+  - Added fixture override convention documentation to README
+  - Updated plugin type definitions with fixture override behavior
+  - Documented override directory structure and lookup rules
 
   ### Testing
 
-  Added 44 lines of test coverage across `transform.test.ts` and `utils-coverage.test.ts` to
-  validate collision handling improvements.
+  - Expanded `tests/class-generation-coverage.test.ts` with fixture override scenarios
+  - Enhanced `tests/generated-tsc.test.ts` with 75+ additional lines of TypeScript compilation
+  tests
+
+  ## Breaking Changes
+
+  None.
+
+  ## Pull Requests Included
+
+  - #1 Add PR release-notes preview comments https://github.com/immense/vue-pom-generator/pull/1
+  (by @dkattan)
+
+  ## Testing
+
+  Test coverage expanded significantly with new test cases for fixture override auto-wiring and
+  TypeScript compilation validation.
+  ```
 

package/class-generation/index.ts

@@ -233,7 +233,6 @@ function generateExtraClickMethodContent(spec: PomExtraClickMethodSpec): string
   if (labelNeedsTemplate) {
     lines.push(`        const label = ${labelExpr};`);
   }
-
   const rootArg = rootNeedsTemplate ? "rootTestId" : rootExpr;
   const labelArg = labelNeedsTemplate ? "label" : labelExpr;
   lines.push(`        await this.clickWithinTestIdByLabel(${rootArg}, ${labelArg}, ${annotationArg}, ${waitArg});`);
@@ -322,6 +321,10 @@ export interface GenerateFilesOptions {
    * Default output (when `true`):
    * - `<projectRoot>/<outDir>/fixtures.g.ts`
    *
+   * Convention:
+   * - fixtures automatically prefer matching handwritten override classes from
+   *   `<dirname(customPomDir)>/overrides/<ClassName>.ts` when present
+   *
    * Accepted values:
    * - `true`: enable with defaults
    * - `"path"`: enable and write the fixture file under this directory (resolved relative to projectRoot),
@@ -506,6 +509,7 @@ export async function generateFiles(
       generateFixtures,
       pomOutDir: outDir,
       projectRoot,
+      customPomDir,
     });
     if (fixtureRegistryFile) {
       writeGeneratedFile(fixtureRegistryFile);
@@ -1005,6 +1009,7 @@ function maybeGenerateFixtureRegistry(
     generateFixtures: GenerateFilesOptions["generateFixtures"];
     pomOutDir: string;
     projectRoot?: string;
+    customPomDir?: string;
   },
 ): GeneratedFileOutput | null {
   const { generateFixtures, pomOutDir } = options;
@@ -1031,6 +1036,12 @@ function maybeGenerateFixtureRegistry(
     ? fixtureOutDirRel
     : path.resolve(root, fixtureOutDirRel);
 
+  const customPomDirRel = options.customPomDir ?? "tests/playwright/pom/custom";
+  const customPomDirAbs = path.isAbsolute(customPomDirRel)
+    ? customPomDirRel
+    : path.resolve(root, customPomDirRel);
+  const overridePomDirAbs = path.resolve(path.dirname(customPomDirAbs), "overrides");
+
   // Resolve the directory that contains the POM barrel export (e.g. <root>/pom).
   const pomDirAbs = path.isAbsolute(pomOutDir) ? pomOutDir : path.resolve(root, pomOutDir);
 
@@ -1067,6 +1078,29 @@ function maybeGenerateFixtureRegistry(
     })
     .sort((a, b) => a.localeCompare(b));
 
+  const fixtureClassNames = [...viewClassNames, ...componentClassNames];
+  const overrideCtorEntries = fixtureClassNames
+    .map((name) => {
+      const overrideFilePath = path.join(overridePomDirAbs, `${name}.ts`);
+      if (!fs.existsSync(overrideFilePath))
+        return null;
+
+      return {
+        className: name,
+        localIdentifier: `${name}Override`,
+        importSpecifier: stripExtension(toPosixRelativePath(fixtureOutDirAbs, overrideFilePath)),
+      };
+    })
+    .filter((entry): entry is { className: string; localIdentifier: string; importSpecifier: string } => !!entry);
+  const overrideCtorByClassName = new Map(overrideCtorEntries.map(entry => [entry.className, entry.localIdentifier]));
+  const overrideImports = overrideCtorEntries.length
+    ? `${overrideCtorEntries
+        .map(entry => `import { ${entry.className} as ${entry.localIdentifier} } from "${entry.importSpecifier}";`)
+        .join("\n")}\n\n`
+    : "";
+
+  const fixtureCtorExpression = (name: string) => overrideCtorByClassName.get(name) ?? `Pom.${name}`;
+
   const header = `${eslintSuppressionHeader}/**\n`
     + ` * DO NOT MODIFY BY HAND\n`
     + ` *\n`
@@ -1080,11 +1114,11 @@ function maybeGenerateFixtureRegistry(
   // View POMs implement goTo() directly, so fixtures can be strongly typed without
   // casting/augmenting at runtime.
   const fixturesTypeEntries = viewClassNames
-    .map(name => `  ${lowerFirst(name)}: Pom.${name},`)
+    .map(name => `  ${lowerFirst(name)}: ${fixtureCtorExpression(name)},`)
     .join("\n");
 
   const componentFixturesTypeEntries = componentClassNames
-    .map(name => `  ${lowerFirst(name)}: Pom.${name},`)
+    .map(name => `  ${lowerFirst(name)}: ${fixtureCtorExpression(name)},`)
     .join("\n");
 
   const pomFactoryType = `export type PomConstructor<T> = new (page: PwPage) => T;\n\n`
@@ -1101,7 +1135,8 @@ function maybeGenerateFixtureRegistry(
   }/** Generated Playwright fixtures (typed page objects). */\n\n`
   + `import { expect, test as base } from "@playwright/test";\n`
   + `import type { Page as PwPage } from "@playwright/test";\n`
-  + `import * as Pom from "${pomImport}";\n\n`
+  + `import * as Pom from "${pomImport}";\n`
+  + `${overrideImports}`
   + `export interface PlaywrightOptions {\n`
   + `  animation: Pom.PlaywrightAnimationOptions;\n`
   + `}\n\n`
@@ -1896,8 +1931,9 @@ function getWidgetInstancesForView(
       continue;
     }
 
-    if (!availableClassIdentifiers.has(className))
+    if (!availableClassIdentifiers.has(className)) {
       continue;
+    }
 
     // Prefer stripping the view prefix (e.g. PreferencesPage-) for cleaner member names.
     const viewPrefix = `${componentName}-`;

package/dist/class-generation/index.d.ts

@@ -17,6 +17,10 @@ export interface GenerateFilesOptions {
      * Default output (when `true`):
      * - `<projectRoot>/<outDir>/fixtures.g.ts`
      *
+     * Convention:
+     * - fixtures automatically prefer matching handwritten override classes from
+     *   `<dirname(customPomDir)>/overrides/<ClassName>.ts` when present
+     *
      * Accepted values:
      * - `true`: enable with defaults
      * - `"path"`: enable and write the fixture file under this directory (resolved relative to projectRoot),

package/dist/class-generation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../class-generation/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,oCAAoC,EAAE,MAAM,sBAAsB,CAAC;AAE5E,OAAO,EAAE,sBAAsB,EAAoE,MAAM,UAAU,CAAC;AAQpH,OAAO,EAAE,oCAAoC,EAAE,CAAC;AA8ChD,UAAU,SAAS;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAwPD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAE1D;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,oCAAoC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAEzD;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,KAAK,CAAC;QAC3B,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,wBAAwB,EAAE,MAAM,EAAE,CAAC;QAEnC;;;WAGG;QACH,QAAQ,CAAC,EAAE,OAAO,GAAG,YAAY,GAAG,MAAM,CAAC;KAC5C,CAAC,CAAC;IAEH,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,uDAAuD;IACvD,aAAa,CAAC,EAAE,KAAK,CAAC,IAAI,GAAG,QAAQ,CAAC,CAAC;IAEvC,6BAA6B;IAC7B,MAAM,CAAC,EAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IAEF,6EAA6E;IAC7E,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAElC,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,mDAAmD;IACnD,UAAU,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;IAEnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAClD;AAwCD,wBAAsB,aAAa,CACjC,qBAAqB,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC1D,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,iBAAiB,EAAE,MAAM,EACzB,OAAO,GAAE,oBAAyB,iBAkFnC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../class-generation/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,oCAAoC,EAAE,MAAM,sBAAsB,CAAC;AAE5E,OAAO,EAAE,sBAAsB,EAAoE,MAAM,UAAU,CAAC;AAQpH,OAAO,EAAE,oCAAoC,EAAE,CAAC;AA8ChD,UAAU,SAAS;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAuPD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAE1D;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,oCAAoC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAEzD;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,KAAK,CAAC;QAC3B,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,wBAAwB,EAAE,MAAM,EAAE,CAAC;QAEnC;;;WAGG;QACH,QAAQ,CAAC,EAAE,OAAO,GAAG,YAAY,GAAG,MAAM,CAAC;KAC5C,CAAC,CAAC;IAEH,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,uDAAuD;IACvD,aAAa,CAAC,EAAE,KAAK,CAAC,IAAI,GAAG,QAAQ,CAAC,CAAC;IAEvC,6BAA6B;IAC7B,MAAM,CAAC,EAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IAEF,6EAA6E;IAC7E,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAElC,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,mDAAmD;IACnD,UAAU,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;IAEnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAClD;AAwCD,wBAAsB,aAAa,CACjC,qBAAqB,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC1D,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,iBAAiB,EAAE,MAAM,EACzB,OAAO,GAAE,oBAAyB,iBAmFnC"}