@immense/vue-pom-generator 1.0.3 → 1.0.8

package/README.md

@@ -47,69 +47,87 @@ import vue from "@vitejs/plugin-vue";
 import { createVuePomGeneratorPlugins } from "@immense/vue-pom-generator";
 
 export default defineConfig(() => {
-	const vueOptions = {
-		script: { defineModel: true, propsDestructure: true },
-	};
-
-	return {
-		plugins: [
-			...createVuePomGeneratorPlugins({
-				vueOptions,
-				logging: { verbosity: "info" },
-
-				injection: {
-					// Attribute to inject/read as the test id (default: data-testid)
-					attribute: "data-testid",
-
-					// Used to classify Vue files as "views" vs components (default: src/views)
-					viewsDir: "src/views",
-
-					// Optional: wrapper semantics for design-system components
-					nativeWrappers: {
-						ImmyButton: { role: "button" },
-						ImmyInput: { role: "input" },
-					},
-
-					// Optional: opt specific components out of injection
-					excludeComponents: ["ImmyButton"],
-
-					// Optional: preserve/overwrite/error when an author already set the attribute
-					existingIdBehavior: "preserve",
-				},
-
-				generation: {
-					// Default: tests/playwright/generated
-					outDir: "tests/playwright/generated",
-
-					// Controls how to handle duplicate generated member names within a single POM class.
-					// - "error": fail compilation
-					// - "warn": warn and suffix
-					// - "suffix": suffix silently (default)
-					nameCollisionBehavior: "suffix",
-
-					// Enable router introspection. When provided, router-aware POM helpers are generated.
-					router: { entry: "src/router.ts" },
-
-					playwright: {
-						fixtures: true,
-						customPoms: {
-							// Default: tests/playwright/pom/custom
-							dir: "tests/playwright/pom/custom",
-							importAliases: { ImmyCheckBox: "CheckboxWidget" },
-							attachments: [
-								{
-									className: "ConfirmationModal",
-									propertyName: "confirmationModal",
-									attachWhenUsesComponents: ["Page"],
-								},
-							],
-						},
-					},
-				},
-			}),
-			vue(vueOptions),
-		],
-	};
+  const vueOptions = {
+    script: { defineModel: true, propsDestructure: true },
+  };
+
+  return {
+    plugins: [
+      ...createVuePomGeneratorPlugins({
+        vueOptions,
+        logging: { verbosity: "info" },
+
+        injection: {
+          // Attribute to inject/read as the test id (default: data-testid)
+          attribute: "data-testid",
+
+          // Used to classify Vue files as "views" vs components (default: src/views)
+          viewsDir: "src/views",
+
+          // Directories to scan for .vue files when building the POM library (default: ["src"])
+          // For Nuxt, you might want ["app", "components", "pages", "layouts"]
+          scanDirs: ["src"],
+
+          // Optional: wrapper semantics for design-system components
+          nativeWrappers: {
+            MyButton: { role: "button" },
+            MyInput: { role: "input" },
+          },
+
+          // Optional: opt specific components out of injection
+          excludeComponents: ["MyButton"],
+
+          // Optional: preserve/overwrite/error when an author already set the attribute
+          existingIdBehavior: "preserve",
+        },
+
+        generation: {
+          // Default: ["ts"]
+          emit: ["ts", "csharp"],
+
+          // C# specific configuration
+          csharp: {
+            // The namespace for generated C# classes (default: Playwright.Generated)
+            namespace: "MyProject.Tests.Generated",
+          },
+
+          // Default: tests/playwright/generated
+          outDir: "tests/playwright/generated",
+
+          // Controls how to handle duplicate generated member names within a single POM class.
+          // - "error": fail compilation
+          // - "warn": warn and suffix
+          // - "suffix": suffix silently (default)
+          nameCollisionBehavior: "suffix",
+
+          // Enable router introspection. When provided, router-aware POM helpers are generated.
+          router: {
+            // For standard Vue apps:
+            entry: "src/router.ts",
+            // For Nuxt apps (file-based routing):
+            // type: "nuxt"
+          },
+
+          playwright: {
+            fixtures: true,
+            customPoms: {
+              // Default: tests/playwright/pom/custom
+              dir: "tests/playwright/pom/custom",
+              importAliases: { MyCheckBox: "CheckboxWidget" },
+              attachments: [
+                {
+                  className: "ConfirmationModal",
+                  propertyName: "confirmationModal",
+                  attachWhenUsesComponents: ["Page"],
+                },
+              ],
+            },
+          },
+        },
+      }),
+      vue(vueOptions),
+    ],
+  };
 });
 ```
 
@@ -119,16 +137,12 @@ Notes:
 - **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).
 
-### `generation.router.entry: string`
+### `generation.router`
 
-Controls where router introspection loads your Vue Router definition from (used for `:to` analysis and navigation helper generation).
+Controls router introspection for `:to` analysis and navigation helper generation.
 
-Resolution:
-
-- relative paths are resolved relative to Vite's resolved `config.root`
-- absolute paths are used as-is
-
-This file must export a **default router factory function** (e.g. `export default makeRouter`).
+- `entry: string`: For standard Vue apps, where router introspection loads your Vue Router definition from. This file must export a **default router factory function** (e.g. `export default makeRouter`).
+- `type: "vue-router" | "nuxt"`: The introspection provider. Defaults to `"vue-router"`. Use `"nuxt"` for file-based routing discovery (e.g. `app/pages` or `pages`).
 
 ### `generation.playwright.fixtures: boolean | string | { outDir?: string }`
 

package/RELEASE_NOTES.md

@@ -0,0 +1,38 @@
+● ## Highlights
+  - Added Nuxt pages introspection to router introspection.
+  - Major overhaul of Vue plugin with expanded support/dev/build plugins and types.
+  - Introduced Playwright types and updated class generation pipeline.
+  - Significant updates to transform and utility modules to support new features.
+  - CI improvements: release on main without gate and a pre-push up-to-date guard.
+
+  ## Changes
+  - Router Introspection
+    - Enhanced router-introspection.ts to add Nuxt pages introspection functionality.
+  - Plugin System
+    - Overhauled plugin/vue-plugin.ts (+286/- changes) with expanded capabilities.
+    - Updated support plugins: dev-plugin, build-plugin, support-plugins, path-utils, logger, and
+  types.
+    - Improved create-vue-pom-generator-plugins.ts for plugin creation.
+  - Class Generation
+    - Added class-generation/playwright-types.ts.
+    - Updated BasePage, Pointer, index.ts, and method-generation.ts for generation flow.
+  - Transform & Utilities
+    - Refactored transform.ts and utils.ts with substantial changes.
+    - Minor eslint.config.ts adjustments.
+  - CI & Tooling
+    - Updated .github/workflows/release.yml and agentic-release-notes.lock.yml.
+    - Added scripts/git-hooks/pre-push.sh pre-push guard.
+    - Cleaned up .gitignore; updated package.json and package-lock.json for git hooks.
+  - Documentation & Logs
+    - Linted README.md.
+    - Added build_v5.log and build_web_v5.log.
+
+  ## Pull Requests Included
+  - #1 Add PR release-notes preview comments (https://github.com/immense/vue-pom-generator/pull/1)
+   by @dkattan
+
+  ## Testing
+  - Updated tests in tests/options.test.ts and tests/utils-coverage.test.ts; adjusted fixture
+  MyComp_CancelButtons_InnerText.vue.
+  - No new test suites added.
+

package/class-generation/BasePage.ts

@@ -1,8 +1,8 @@
-import type { Locator as PwLocator, Page as PwPage } from "@playwright/test";
+import type { PwLocator, PwPage } from "./playwright-types";
 import { TESTID_CLICK_EVENT_NAME, TESTID_CLICK_EVENT_STRICT_FLAG } from "../click-instrumentation";
 import type { TestIdClickEventDetail } from "../click-instrumentation";
 import { Pointer } from "./Pointer";
-import type { AfterPointerClickInfo } from "./Pointer";
+import type { AfterPointerClick, AfterPointerClickInfo } from "./Pointer";
 
 // Click instrumentation is a core contract for generated POMs.
 const REQUIRE_CLICK_EVENT = true;
@@ -218,6 +218,21 @@ export class BasePage {
     return this.page.locator(this.selectorForTestId(testId));
   }
 
+  /**
+   * Animates the cursor to an element.
+   */
+  protected async animateCursorToElement(
+    target: string | PwLocator,
+    executeClick: boolean = true,
+    delayMs: number = 100,
+    annotationText: string = "",
+    options?: {
+      afterClick?: AfterPointerClick;
+    },
+  ): Promise<void> {
+    await this.pointer.animateCursorToElement(target, executeClick, delayMs, annotationText, options);
+  }
+
   /**
    * Creates an indexable proxy for keyed elements so generated POMs can expose
    * ergonomic accessors like:

package/class-generation/Pointer.ts

@@ -1,4 +1,4 @@
-import type { Locator as PwLocator, Page as PwPage } from "@playwright/test";
+import type { PwLocator, PwPage } from "./playwright-types";
 
 export interface PlaywrightAnimationOptions {
 	/**

package/class-generation/index.ts

@@ -3,9 +3,7 @@ import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { generateViewObjectModelMethodContent } from "../method-generation";
-import { parseRouterFileFromCwd } from "../router-introspection";
-// NOTE: This module intentionally does not depend on Babel parsing.
-
+import { introspectNuxtPages, parseRouterFileFromCwd } from "../router-introspection";
 import { IComponentDependencies, IDataTestId, PomExtraClickMethodSpec, PomPrimarySpec, upperFirst } from "../utils";
 
 // Intentionally imported so tooling understands this exported helper is part of the
@@ -62,9 +60,16 @@ interface RouteMeta {
   template: string;
 }
 
-async function getRouteMetaByComponent(projectRoot?: string, routerEntry?: string): Promise<Record<string, RouteMeta>> {
-  const resolvedRouterEntry = resolveRouterEntry(projectRoot, routerEntry);
-  const { routeMetaEntries } = await parseRouterFileFromCwd(resolvedRouterEntry);
+async function getRouteMetaByComponent(
+  projectRoot?: string,
+  routerEntry?: string,
+  routerType?: "vue-router" | "nuxt",
+): Promise<Record<string, RouteMeta>> {
+  const root = projectRoot ?? process.cwd();
+
+  const { routeMetaEntries } = routerType === "nuxt"
+    ? await introspectNuxtPages(root)
+    : await parseRouterFileFromCwd(resolveRouterEntry(root, routerEntry));
 
   const map = new Map<string, RouteMeta[]>();
   for (const entry of routeMetaEntries) {
@@ -327,12 +332,20 @@ export interface GenerateFilesOptions {
   /** Which POM languages to emit. Defaults to ["ts"]. */
   emitLanguages?: Array<"ts" | "csharp">;
 
+  /** C# generation options. */
+  csharp?: {
+    namespace?: string;
+  };
+
   /** When true, generate router-aware helpers like goToSelf() on view POMs. */
   vueRouterFluentChaining?: boolean;
 
   /** Router entry path used for vue-router introspection when fluent chaining is enabled. */
   routerEntry?: string;
 
+  /** The type of router introspection to perform. */
+  routerType?: "vue-router" | "nuxt";
+
   routeMetaByComponent?: Record<string, RouteMeta>;
 }
 
@@ -382,8 +395,10 @@ export async function generateFiles(
     customPomImportAliases,
     testIdAttribute,
     emitLanguages: emitLanguagesOverride,
+    csharp,
     vueRouterFluentChaining,
     routerEntry,
+    routerType,
   } = options;
 
   const emitLanguages: Array<"ts" | "csharp"> = emitLanguagesOverride?.length
@@ -393,7 +408,7 @@ export async function generateFiles(
   const outDir = outDirOverride ?? "./pom";
 
   const routeMetaByComponent = vueRouterFluentChaining
-    ? await getRouteMetaByComponent(projectRoot, routerEntry)
+    ? await getRouteMetaByComponent(projectRoot, routerEntry, routerType)
     : undefined;
 
   if (emitLanguages.includes("ts")) {
@@ -421,6 +436,8 @@ export async function generateFiles(
   if (emitLanguages.includes("csharp")) {
     const csFiles = generateAggregatedCSharpFiles(componentHierarchyMap, outDir, {
       projectRoot,
+      testIdAttribute,
+      csharp,
     });
     for (const file of csFiles) {
       createFile(file.filePath, file.content);
@@ -454,11 +471,11 @@ function toCSharpParam(paramTypeExpr: string): { type: string; defaultExpr?: str
   const typePart = left.includes("|") ? "string" : left;
 
   let type = "string";
-  if (/(^|\s)boolean(\s|$)/.test(typePart))
+  if (/(?:^|\s)boolean(?:\s|$)/.test(typePart))
     type = "bool";
-  else if (/(^|\s)string(\s|$)/.test(typePart))
+  else if (/(?:^|\s)string(?:\s|$)/.test(typePart))
     type = "string";
-  else if (/(^|\s)number(\s|$)/.test(typePart))
+  else if (/(?:^|\s)number(?:\s|$)/.test(typePart))
     type = "int";
   else if (/\d+/.test(typePart) && typePart === "")
     type = "int";
@@ -508,10 +525,17 @@ function formatCSharpParams(params: Record<string, string> | undefined): { signa
 function generateAggregatedCSharpFiles(
   componentHierarchyMap: Map<string, IComponentDependencies>,
   outDir: string,
-  options: { projectRoot?: string } = {},
+  options: {
+    projectRoot?: string;
+    testIdAttribute?: string;
+    csharp?: {
+      namespace?: string;
+    };
+  } = {},
 ): Array<{ filePath: string; content: string }> {
-  const projectRoot = options.projectRoot ?? process.cwd();
-  const outAbs = path.isAbsolute(outDir) ? outDir : path.resolve(projectRoot, outDir);
+  const outAbs = ensureDir(outDir);
+  const namespace = options.csharp?.namespace ?? "Playwright.Generated";
+  const testIdAttribute = (options.testIdAttribute || "data-testid").trim() || "data-testid";
 
   const entries = Array.from(componentHierarchyMap.entries()).sort((a, b) => a[0].localeCompare(b[0]));
 
@@ -527,13 +551,13 @@ function generateAggregatedCSharpFiles(
     "using System.Threading.Tasks;",
     "using Microsoft.Playwright;",
     "",
-    "namespace ImmyBot.Playwright.Generated;",
+    `namespace ${namespace};`,
     "",
-    "public abstract class BasePage",
+    "public abstract partial class BasePage",
     "{",
     "    protected BasePage(IPage page) => Page = page;",
     "    protected IPage Page { get; }",
-    "    protected ILocator LocatorByTestId(string testId) => Page.GetByTestId(testId);",
+    `    protected ILocator LocatorByTestId(string testId) => Page.Locator($"[${testIdAttribute}=\\"{testId}\\"]");`,
     "",
     "    // Minimal vue-select helper mirroring the TS BasePage.selectVSelectByTestId behavior.",
     "    // Note: annotationText is currently a no-op in C# output (we don't render a cursor overlay).",
@@ -559,8 +583,9 @@ function generateAggregatedCSharpFiles(
   const chunks: string[] = [header];
 
   for (const [componentName, deps] of entries) {
+    const className = toPascalCaseLocal(componentName);
     chunks.push(
-      `public sealed class ${componentName} : BasePage\n{\n    public ${componentName}(IPage page) : base(page) { }\n`,
+      `public partial class ${className} : BasePage\n{\n    public ${className}(IPage page) : base(page) { }\n`,
     );
 
     // Primary specs
@@ -748,7 +773,7 @@ function maybeGenerateFixtureRegistry(
     projectRoot?: string;
   },
 ) {
-  const { generateFixtures, pomOutDir, projectRoot } = options;
+  const { generateFixtures, pomOutDir } = options;
   if (!generateFixtures)
     return;
 
@@ -767,7 +792,7 @@ function maybeGenerateFixtureRegistry(
   const fixtureOutDirRel = looksLikeFilePath ? path.dirname(fixtureOutRel) : fixtureOutRel;
   const fixtureFileName = looksLikeFilePath ? path.basename(fixtureOutRel) : "fixtures.g.ts";
 
-  const root = projectRoot ?? process.cwd();
+  const root = options.projectRoot ?? process.cwd();
   const fixtureOutDirAbs = path.isAbsolute(fixtureOutDirRel)
     ? fixtureOutDirRel
     : path.resolve(root, fixtureOutDirRel);
@@ -1132,8 +1157,7 @@ async function generateAggregatedFiles(
     outputDir: string,
     items: Array<[string, IComponentDependencies]>,
   ) => {
-    // Alias Playwright types to avoid collisions with generated classes (e.g. a Vue component named `Page`).
-    const imports: string[] = ["import type { Locator as PwLocator, Page as PwPage } from \"@playwright/test\";"];
+    const imports: string[] = [];
 
     if (!basePageClassPath) {
       throw new Error("basePageClassPath is required for aggregated generation");
@@ -1158,6 +1182,20 @@ async function generateAggregatedFiles(
       "}",
     ].join("\n");
 
+    const inlinePlaywrightTypesModule = () => {
+      const typesPath = fileURLToPath(new URL("./playwright-types.ts", import.meta.url));
+
+      let typesSource = "";
+      try {
+        typesSource = fs.readFileSync(typesPath, "utf8");
+      }
+      catch {
+        throw new Error(`Failed to read playwright-types.ts at ${typesPath}`);
+      }
+
+      return typesSource.trim();
+    };
+
     const inlinePointerModule = () => {
       // Inline Pointer.ts from this package so generated POMs are self-contained and do not
       // rely on runtime TS module resolution within workspace packages.
@@ -1190,6 +1228,12 @@ async function generateAggregatedFiles(
         "",
       );
 
+      // The aggregated file inlines these structural types once at the top.
+      pointerSource = pointerSource.replace(
+        /import\s+type\s*\{\s*PwLocator\s*,\s*PwPage\s*\}\s*from\s*["']\.\/playwright-types["'];?\s*/,
+        "",
+      );
+
       return pointerSource.trim();
     };
 
@@ -1222,15 +1266,22 @@ async function generateAggregatedFiles(
         "",
       );
 
+      // The aggregated file inlines these structural types once at the top.
+      basePageSource = basePageSource.replace(
+        /import\s+type\s*\{\s*PwLocator\s*,\s*PwPage\s*\}\s*from\s*["']\.\/playwright-types["'];?\s*/,
+        "",
+      );
+
       // BasePage references Pointer, but in aggregated output we inline Pointer above.
       basePageSource = basePageSource.replace(
-        /import\s*\{\s*Pointer\s*\}\s*from\s*["']\.\/Pointer["'];?\s*/g,
+        /import\s+(?:type\s*)?\{[\s\S]*?\}\s*from\s*["']\.\/Pointer["'];?\s*/g,
         "",
       );
 
       return basePageSource.trim();
     };
 
+    const playwrightTypesInline = inlinePlaywrightTypesModule();
     const pointerInline = inlinePointerModule();
     const basePageInline = inlineBasePageModule();
 
@@ -1244,7 +1295,7 @@ async function generateAggregatedFiles(
       const importAliases: Record<string, string> = {
         Toggle: "ToggleWidget",
         Checkbox: "CheckboxWidget",
-        ...(options.customPomImportAliases ?? {}),
+        ...(options.customPomImportAliases),
       };
 
       const customDirRelOrAbs = options.customPomDir ?? "tests/playwright/pom/custom";
@@ -1489,6 +1540,8 @@ async function generateAggregatedFiles(
       header,
       ...imports,
       "",
+      playwrightTypesInline,
+      "",
       pointerInline,
       "",
       basePageInline,
@@ -1502,7 +1555,7 @@ async function generateAggregatedFiles(
 
   const base = ensureDir(outDir);
   const outputFile = path.join(base, "page-object-models.g.ts");
-  const header = `${eslintSuppressionHeader}/**\n * Aggregated generated POMs\n${AUTO_GENERATED_COMMENT}`;
+  const header = `/// <reference lib="es2015" />\n${eslintSuppressionHeader}/**\n * Aggregated generated POMs\n${AUTO_GENERATED_COMMENT}`;
   const content = makeAggregatedContent(header, path.dirname(outputFile), [...views, ...components]);
 
   const indexFile = path.join(base, "index.ts");

package/class-generation/playwright-types.ts

@@ -0,0 +1,23 @@
+export interface PwLocator {
+  locator: (selector: string) => PwLocator;
+  first: () => PwLocator;
+  count: () => Promise<number>;
+  click: (options?: { force?: boolean }) => Promise<void>;
+  fill: (value: string, options?: { force?: boolean; timeout?: number }) => Promise<void>;
+  getAttribute: (name: string) => Promise<string | null>;
+  scrollIntoViewIfNeeded: (options?: { timeout?: number }) => Promise<void>;
+}
+
+export type PwSelectOption = string | { value?: string; label?: string; index?: number };
+
+export interface PwPage {
+  locator: (selector: string) => PwLocator;
+  url: () => string;
+  waitForTimeout: (timeout: number) => Promise<void>;
+  evaluate: <R, Arg>(pageFunction: (arg: Arg) => R | Promise<R>, arg: Arg) => Promise<R>;
+  isVisible: (selector: string, options?: { timeout?: number }) => Promise<boolean>;
+  textContent: (selector: string, options?: { timeout?: number }) => Promise<string | null>;
+  waitForSelector: (selector: string, options?: { timeout?: number }) => Promise<object | null>;
+  hover: (selector: string, options?: { timeout?: number }) => Promise<void>;
+  selectOption: (selector: string, values: PwSelectOption | PwSelectOption[], options?: { timeout?: number }) => Promise<string[]>;
+}