@immense/vue-pom-generator 1.0.56 → 1.0.58

package/README.md

@@ -54,7 +54,7 @@ export class UserEditorPage extends BasePage {
   get SaveButton() { /* Playwright locator */ }
 
   async typeEmailAddress(text: string, annotationText = "") { /* ... */ }
-  async clickSave(wait: boolean = true) { /* ... */ }
+  async clickSave(wait: boolean = true, annotationText = "") { /* ... */ }
 }
 ```
 

package/RELEASE_NOTES.md

@@ -1,15 +1,31 @@
-● ## Highlights
+● I'll fetch the actual commits and PRs between v1.0.57 and HEAD to generate accurate release
+  notes.
 
-  - Added support for awaited handler wrappers in POM generation
-  - Enhanced async/await pattern detection in Vue event handlers
-  - Improved test coverage with 39 new test lines across transform and utils
+● Based on the commit range v1.0.57..HEAD, only PR #19 is included in this release. Here are the
+  release notes:
+
+  ---
+
+  ## Highlights
+
+  - 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
 
   ## Changes
 
-  - **Handler Detection:** `utils.ts` now correctly identifies and processes event handlers
-  wrapped in `await` expressions
-  - **Test Coverage:** Added comprehensive tests for awaited handler scenarios in
-  `transform.test.ts` and `utils-coverage.test.ts`
+  **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
+
+  **Test coverage improvements:**
+  - Add regression tests for project-local Nuxt kit loading
+  - Enhance Nuxt discovery test coverage with real-world integration scenarios
 
   ## Breaking Changes
 
@@ -17,11 +33,15 @@
 
   ## Pull Requests Included
 
-  - #17 fix: support awaited handler wrappers
-  (https://github.com/immense/vue-pom-generator/pull/17) by @dkattan
+  - [#19](https://github.com/immense/vue-pom-generator/pull/19) fix: harden local app integration
 
   ## Testing
 
-  Added 39 lines of new tests covering awaited handler wrapper scenarios and edge cases. All tests
-   passing.
+  Validated with:
+  - `npm run lint`
+  - `npm run typecheck`
+  - `npm run build`
+  - `npm test`
+
+  All tests passing with 258 net lines added across 13 files.
 

package/dist/index.cjs

@@ -104,6 +104,21 @@ function createLogger(options) {
   };
 }
 const requireFromModule = node_module.createRequire(typeof document === "undefined" ? require("url").pathToFileURL(__filename).href : _documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === "SCRIPT" && _documentCurrentScript.src || new URL("index.cjs", document.baseURI).href);
+function resolveNuxtKitEntry(cwd) {
+  const attemptResolvers = [
+    node_module.createRequire(path.resolve(cwd, "package.json")),
+    requireFromModule
+  ];
+  let lastError;
+  for (const resolver of attemptResolvers) {
+    try {
+      return resolver.resolve("@nuxt/kit");
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+    }
+  }
+  throw lastError ?? new Error("Unknown module resolution error");
+}
 function toUniqueResolvedPaths(paths) {
   return Array.from(new Set(paths.map((value) => path.resolve(value))));
 }
@@ -214,7 +229,7 @@ async function loadNuxtProjectDiscovery(cwd = process.cwd()) {
   let loadNuxtConfig;
   let getLayerDirectories;
   try {
-    const nuxtKitEntry = requireFromModule.resolve("@nuxt/kit");
+    const nuxtKitEntry = resolveNuxtKitEntry(cwd);
     ({ loadNuxtConfig, getLayerDirectories } = await import(node_url.pathToFileURL(nuxtKitEntry).href));
   } catch (error) {
     throw new TypeError(
@@ -403,7 +418,14 @@ function generateClickMethod(methodName, formattedDataTestId, alternateFormatted
     const candidatesExpr = [formattedDataTestId, ...alternates].map(testIdExpression).join(", ");
     const clickMethod = createAsyncMethod(
       name,
-      hasParam(params, "key") ? [...baseParameters, createInlineParameter("wait", { type: "boolean", initializer: "true" })] : [createInlineParameter("wait", { type: "boolean", initializer: "true" })],
+      hasParam(params, "key") ? [
+        ...baseParameters,
+        createInlineParameter("wait", { type: "boolean", initializer: "true" }),
+        createInlineParameter("annotationText", { type: "string", initializer: '""' })
+      ] : [
+        createInlineParameter("wait", { type: "boolean", initializer: "true" }),
+        createInlineParameter("annotationText", { type: "string", initializer: '""' })
+      ],
       (writer) => {
         writer.writeLine(`const candidates = [${candidatesExpr}] as const;`);
         writer.writeLine("let lastError: unknown;");
@@ -411,7 +433,7 @@ function generateClickMethod(methodName, formattedDataTestId, alternateFormatted
           writer.writeLine("const locator = this.locatorByTestId(testId);");
           writer.write("try ").block(() => {
             writer.write("if (await locator.count()) ").block(() => {
-              writer.writeLine('await this.clickLocator(locator, "", wait);');
+              writer.writeLine("await this.clickLocator(locator, annotationText, wait);");
               writer.writeLine("return;");
             });
           });
@@ -422,10 +444,10 @@ function generateClickMethod(methodName, formattedDataTestId, alternateFormatted
         writer.writeLine(`throw (lastError instanceof Error) ? lastError : new Error("[pom] Failed to click any candidate locator for ${name}.");`);
       }
     );
-    const noWaitArgs = argsForForward ? `${argsForForward}, false` : "false";
+    const noWaitArgs = argsForForward ? `${argsForForward}, false, annotationText` : "false, annotationText";
     const noWaitMethod = createAsyncMethod(
       noWaitName,
-      hasParam(params, "key") ? baseParameters : [],
+      hasParam(params, "key") ? [...baseParameters, createInlineParameter("annotationText", { type: "string", initializer: '""' })] : [createInlineParameter("annotationText", { type: "string", initializer: '""' })],
       (writer) => {
         writer.writeLine(`await this.${name}(${noWaitArgs});`);
       }
@@ -434,21 +456,44 @@ function generateClickMethod(methodName, formattedDataTestId, alternateFormatted
   }
   if (hasParam(params, "key")) {
     return [
-      createAsyncMethod(name, [...baseParameters, createInlineParameter("wait", { type: "boolean", initializer: "true" })], (writer) => {
-        writer.writeLine(`await this.clickByTestId(\`${formattedDataTestId}\`, "", wait);`);
-      }),
-      createAsyncMethod(noWaitName, baseParameters, (writer) => {
-        writer.writeLine(`await this.${name}(${argsForForward}, false);`);
-      })
+      createAsyncMethod(
+        name,
+        [
+          ...baseParameters,
+          createInlineParameter("wait", { type: "boolean", initializer: "true" }),
+          createInlineParameter("annotationText", { type: "string", initializer: '""' })
+        ],
+        (writer) => {
+          writer.writeLine(`await this.clickByTestId(\`${formattedDataTestId}\`, annotationText, wait);`);
+        }
+      ),
+      createAsyncMethod(
+        noWaitName,
+        [...baseParameters, createInlineParameter("annotationText", { type: "string", initializer: '""' })],
+        (writer) => {
+          writer.writeLine(`await this.${name}(${argsForForward}, false, annotationText);`);
+        }
+      )
     ];
   }
   return [
-    createAsyncMethod(name, [createInlineParameter("wait", { type: "boolean", initializer: "true" })], (writer) => {
-      writer.writeLine(`await this.clickByTestId("${formattedDataTestId}", "", wait);`);
-    }),
-    createAsyncMethod(noWaitName, [], (writer) => {
-      writer.writeLine(`await this.${name}(false);`);
-    })
+    createAsyncMethod(
+      name,
+      [
+        createInlineParameter("wait", { type: "boolean", initializer: "true" }),
+        createInlineParameter("annotationText", { type: "string", initializer: '""' })
+      ],
+      (writer) => {
+        writer.writeLine(`await this.clickByTestId("${formattedDataTestId}", annotationText, wait);`);
+      }
+    ),
+    createAsyncMethod(
+      noWaitName,
+      [createInlineParameter("annotationText", { type: "string", initializer: '""' })],
+      (writer) => {
+        writer.writeLine(`await this.${name}(false, annotationText);`);
+      }
+    )
   ];
 }
 function generateRadioMethod(methodName, formattedDataTestId) {
@@ -2893,10 +2938,13 @@ Fix: make the element identifiable (e.g. add id/name/inner text or use a more sp
           formattedDataTestId: formattedDataTestIdForPom
         },
         keyLiteral: rawValue,
-        params: { wait: "boolean = true" }
+        params: { wait: "boolean = true", annotationText: 'string = ""' }
       });
       if (added) {
-        registerGeneratedMethodSignature(generatedName, { params: `wait: boolean = true`, argNames: ["wait"] });
+        registerGeneratedMethodSignature(generatedName, {
+          params: `wait: boolean = true, annotationText: string = ""`,
+          argNames: ["wait", "annotationText"]
+        });
       }
     }
     return;
@@ -3157,6 +3205,56 @@ function createRouterIntrospectionVueStubPlugin(options) {
     }
   };
 }
+function snapshotGlobalValue(name) {
+  const g = globalThis;
+  return {
+    descriptor: Object.getOwnPropertyDescriptor(globalThis, name),
+    value: g[name]
+  };
+}
+function setTemporaryGlobal(name, value, snapshots) {
+  if (!snapshots.has(name))
+    snapshots.set(name, snapshotGlobalValue(name));
+  const snapshot = snapshots.get(name);
+  if (!snapshot)
+    return false;
+  if (!snapshot.descriptor || snapshot.descriptor.configurable) {
+    Object.defineProperty(globalThis, name, {
+      configurable: true,
+      enumerable: snapshot.descriptor?.enumerable ?? true,
+      writable: true,
+      value
+    });
+    return true;
+  }
+  if ("writable" in snapshot.descriptor && snapshot.descriptor.writable) {
+    Reflect.set(globalThis, name, value);
+    return true;
+  }
+  if (snapshot.descriptor.set) {
+    snapshot.descriptor.set.call(globalThis, value);
+    return true;
+  }
+  return false;
+}
+function restoreTemporaryGlobals(snapshots) {
+  for (const [name, snapshot] of Array.from(snapshots.entries()).reverse()) {
+    const { descriptor, value } = snapshot;
+    if (!descriptor) {
+      Reflect.deleteProperty(globalThis, name);
+      continue;
+    }
+    if (descriptor.configurable) {
+      Object.defineProperty(globalThis, name, descriptor);
+      continue;
+    }
+    if ("writable" in descriptor && descriptor.writable) {
+      Reflect.set(globalThis, name, value);
+      continue;
+    }
+    descriptor.set?.call(globalThis, value);
+  }
+}
 const PARAM_TOKEN_PREFIX = "__VUE_TESTID_PARAM__";
 function getParamToken(name) {
   return `${PARAM_TOKEN_PREFIX}${name}__`;
@@ -3505,12 +3603,18 @@ function createMinimalLocation() {
     ancestorOrigins: { length: 0, contains: () => false, item: () => null, [Symbol.iterator]: [][Symbol.iterator] }
   };
 }
-async function ensureDomShim() {
+function ensureDomShim() {
   const g = globalThis;
   if (typeof document !== "undefined" && typeof window !== "undefined")
-    return;
+    return () => {
+    };
   const minimalDoc = createMinimalDocument();
   const minimalLocation = createMinimalLocation();
+  const snapshots = /* @__PURE__ */ new Map();
+  const setGlobal = (name, value) => {
+    if (!setTemporaryGlobal(name, value, snapshots))
+      debugLog(`could not temporarily install global ${name}`);
+  };
   const win = {
     document: minimalDoc,
     location: minimalLocation,
@@ -3555,17 +3659,17 @@ async function ensureDomShim() {
     queueMicrotask,
     performance: globalThis.performance
   };
-  g.window = win;
-  g.document = minimalDoc;
-  g.location = minimalLocation;
+  setGlobal("window", win);
+  setGlobal("document", minimalDoc);
+  setGlobal("location", minimalLocation);
   if (!g.self)
-    g.self = win;
+    setGlobal("self", win);
   if (!g.navigator)
-    g.navigator = win.navigator;
+    setGlobal("navigator", win.navigator);
   if (!g.history)
-    g.history = win.history;
+    setGlobal("history", win.history);
   if (!g.MutationObserver) {
-    g.MutationObserver = class {
+    setGlobal("MutationObserver", class {
       disconnect() {
       }
       observe() {
@@ -3573,20 +3677,20 @@ async function ensureDomShim() {
       takeRecords() {
         return [];
       }
-    };
+    });
   }
   if (!g.ResizeObserver) {
-    g.ResizeObserver = class {
+    setGlobal("ResizeObserver", class {
       disconnect() {
       }
       observe() {
       }
       unobserve() {
       }
-    };
+    });
   }
   if (!g.IntersectionObserver) {
-    g.IntersectionObserver = class {
+    setGlobal("IntersectionObserver", class {
       disconnect() {
       }
       observe() {
@@ -3596,10 +3700,10 @@ async function ensureDomShim() {
       takeRecords() {
         return [];
       }
-    };
+    });
   }
   if (!g.requestIdleCallback) {
-    g.requestIdleCallback = (cb) => setTimeout(() => cb({ didTimeout: false, timeRemaining: () => 0 }), 1);
+    setGlobal("requestIdleCallback", (cb) => setTimeout(() => cb({ didTimeout: false, timeRemaining: () => 0 }), 1));
   }
   if (!g.localStorage || !g.sessionStorage) {
     const storageFactory = () => {
@@ -3622,12 +3726,15 @@ async function ensureDomShim() {
       };
     };
     if (!g.localStorage)
-      g.localStorage = storageFactory();
+      setGlobal("localStorage", storageFactory());
     if (!g.sessionStorage)
-      g.sessionStorage = storageFactory();
+      setGlobal("sessionStorage", storageFactory());
   }
   if (!g.requestAnimationFrame)
-    g.requestAnimationFrame = (cb) => setTimeout(() => cb(Date.now()), 16);
+    setGlobal("requestAnimationFrame", (cb) => setTimeout(() => cb(Date.now()), 16));
+  return () => {
+    restoreTemporaryGlobals(snapshots);
+  };
 }
 function unwrapNuxtPageSegment(segment, prefix, suffix) {
   if (!segment.startsWith(prefix) || !segment.endsWith(suffix))
@@ -3745,85 +3852,89 @@ async function parseRouterFileFromCwd(routerEntryPath, options = {}) {
     }
     const cwd = path.dirname(routerEntry);
     const moduleShims = normalizeRouterIntrospectionModuleShims(options.moduleShims);
-    await ensureDomShim();
-    debugLog(`parseRouterFileFromCwd cwd=${cwd}`);
-    const vite = await import("vite");
-    const server = await vite.createServer({
-      root: cwd,
-      configFile: false,
-      logLevel: "error",
-      // This server is created only to SSR-load the router module. Disable HMR/WebSocket
-      // to avoid port conflicts in dev/test environments.
-      server: { middlewareMode: true, hmr: false, ws: false },
-      appType: "custom",
-      // IMPORTANT:
-      // This internal, short-lived Vite server exists only to `ssrLoadModule()` the router entry.
-      // We close it immediately after reading routes.
-      //
-      // Vite's dependency optimizer (vite:dep-scan / optimizeDeps) runs asynchronously and can
-      // still have pending resolve requests when we call `server.close()`, which surfaces as:
-      //   "The server is being restarted or closed. Request is outdated [plugin vite:dep-scan]"
-      //
-      // Disable optimizeDeps entirely for this internal server to avoid that race.
-      optimizeDeps: {
-        disabled: true
-      },
-      resolve: {
-        alias: {
-          "@": cwd
-        }
-      },
-      // Important: Do NOT include @vitejs/plugin-vue here.
-      // We stub all `.vue` imports ourselves, and including the Vue plugin would attempt to parse
-      // those stubbed modules as real SFCs (and fail).
-      plugins: [createRouterIntrospectionVueStubPlugin({ routerEntryAbs: routerEntry, moduleShims })]
-    });
+    const restoreDomShim = ensureDomShim();
     try {
-      const moduleId = node_url.pathToFileURL(routerEntry).href;
-      debugLog(`ssrLoadModule(${moduleId}) start`);
-      const mod = await server.ssrLoadModule(moduleId);
-      debugLog(`ssrLoadModule(${moduleId}) done; hasDefault=${typeof mod?.default === "function"}`);
-      const makeRouter = mod?.default;
-      if (typeof makeRouter !== "function") {
-        throw new TypeError(`[vue-pom-generator] ${routerEntry} must export a default router factory function (export default makeRouter).`);
-      }
-      let router;
+      debugLog(`parseRouterFileFromCwd cwd=${cwd}`);
+      const vite = await import("vite");
+      const server = await vite.createServer({
+        root: cwd,
+        configFile: false,
+        logLevel: "error",
+        // This server is created only to SSR-load the router module. Disable HMR/WebSocket
+        // to avoid port conflicts in dev/test environments.
+        server: { middlewareMode: true, hmr: false, ws: false },
+        appType: "custom",
+        // IMPORTANT:
+        // This internal, short-lived Vite server exists only to `ssrLoadModule()` the router entry.
+        // We close it immediately after reading routes.
+        //
+        // Vite's dependency optimizer (vite:dep-scan / optimizeDeps) runs asynchronously and can
+        // still have pending resolve requests when we call `server.close()`, which surfaces as:
+        //   "The server is being restarted or closed. Request is outdated [plugin vite:dep-scan]"
+        //
+        // Disable optimizeDeps entirely for this internal server to avoid that race.
+        optimizeDeps: {
+          disabled: true
+        },
+        resolve: {
+          alias: {
+            "@": cwd
+          }
+        },
+        // Important: Do NOT include @vitejs/plugin-vue here.
+        // We stub all `.vue` imports ourselves, and including the Vue plugin would attempt to parse
+        // those stubbed modules as real SFCs (and fail).
+        plugins: [createRouterIntrospectionVueStubPlugin({ routerEntryAbs: routerEntry, moduleShims })]
+      });
       try {
-        router = makeRouter();
-      } catch (err) {
-        throw new Error(`[vue-pom-generator] makeRouter() invocation failed: ${String(err)}`);
-      }
-      const routeNameMap = /* @__PURE__ */ new Map();
-      const routePathMap = /* @__PURE__ */ new Map();
-      const routeMetaEntries = [];
-      for (const r of router.getRoutes()) {
-        const componentInfo = await getComponentInfoFromRouteRecord(r, { rootDir: cwd });
-        const componentName = resolveIntrospectedComponentName(componentInfo, options.componentNaming);
-        if (!componentName)
-          continue;
-        if (typeof r.path === "string" && r.path.length) {
-          routePathMap.set(r.path, componentName);
+        const moduleId = node_url.pathToFileURL(routerEntry).href;
+        debugLog(`ssrLoadModule(${moduleId}) start`);
+        const mod = await server.ssrLoadModule(moduleId);
+        debugLog(`ssrLoadModule(${moduleId}) done; hasDefault=${typeof mod?.default === "function"}`);
+        const makeRouter = mod?.default;
+        if (typeof makeRouter !== "function") {
+          throw new TypeError(`[vue-pom-generator] ${routerEntry} must export a default router factory function (export default makeRouter).`);
         }
-        if (typeof r.name === "string" && r.name.length) {
-          const key = toPascalCase(r.name);
-          routeNameMap.set(key, componentName);
+        let router;
+        try {
+          router = makeRouter();
+        } catch (err) {
+          throw new Error(`[vue-pom-generator] makeRouter() invocation failed: ${String(err)}`);
         }
-        const { paramKeys, queryKeys } = getRoutePropsKeys(r);
-        const paramsMeta = getRouteParamMeta(router, r, paramKeys);
-        const pathTemplate = buildRouteTemplate(router, r, paramsMeta.map((p) => p.name));
-        if (typeof pathTemplate === "string" && pathTemplate.length) {
-          routeMetaEntries.push({
-            componentName,
-            pathTemplate,
-            params: paramsMeta,
-            query: queryKeys
-          });
+        const routeNameMap = /* @__PURE__ */ new Map();
+        const routePathMap = /* @__PURE__ */ new Map();
+        const routeMetaEntries = [];
+        for (const r of router.getRoutes()) {
+          const componentInfo = await getComponentInfoFromRouteRecord(r, { rootDir: cwd });
+          const componentName = resolveIntrospectedComponentName(componentInfo, options.componentNaming);
+          if (!componentName)
+            continue;
+          if (typeof r.path === "string" && r.path.length) {
+            routePathMap.set(r.path, componentName);
+          }
+          if (typeof r.name === "string" && r.name.length) {
+            const key = toPascalCase(r.name);
+            routeNameMap.set(key, componentName);
+          }
+          const { paramKeys, queryKeys } = getRoutePropsKeys(r);
+          const paramsMeta = getRouteParamMeta(router, r, paramKeys);
+          const pathTemplate = buildRouteTemplate(router, r, paramsMeta.map((p) => p.name));
+          if (typeof pathTemplate === "string" && pathTemplate.length) {
+            routeMetaEntries.push({
+              componentName,
+              pathTemplate,
+              params: paramsMeta,
+              query: queryKeys
+            });
+          }
         }
+        return { routeNameMap, routePathMap, routeMetaEntries };
+      } finally {
+        debugLog("closing internal vite server");
+        await server.close();
       }
-      return { routeNameMap, routePathMap, routeMetaEntries };
     } finally {
-      debugLog("closing internal vite server");
-      await server.close();
+      restoreDomShim();
     }
   });
 }
@@ -7997,6 +8108,13 @@ function tryCreateElementMetadata(args) {
   };
   return metadata;
 }
+function resolveCompilerSfcParse(compilerSfc2) {
+  const parse = compilerSfc2.parse ?? compilerSfc2.default?.parse;
+  if (typeof parse !== "function") {
+    throw new TypeError("[vue-pom-generator] Failed to resolve @vue/compiler-sfc.parse.");
+  }
+  return parse;
+}
 function extractMetadataAfterTransform(ast, componentName, elementMetadata, semanticNameMap, testIdAttribute) {
   const componentMetadata = /* @__PURE__ */ new Map();
   function traverseNode(node) {
@@ -8193,7 +8311,8 @@ function createVuePluginWithTestIds(options) {
       }
       const componentName = getComponentNameFromPath(cleanPath);
       loggerRef.current.debug(`Collecting metadata for ${cleanPath} (component: ${componentName})`);
-      const { parse } = await import("@vue/compiler-sfc");
+      const compilerSfc2 = await import("@vue/compiler-sfc");
+      const parse = resolveCompilerSfcParse(compilerSfc2);
       const compilerDom2 = await import("@vue/compiler-dom");
       const compile = compilerDom2.compile;
       const { descriptor } = parse(code, { filename: cleanPath });