@immense/vue-pom-generator 1.0.90 → 1.0.92

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/README.md +88 -10
  2. package/RELEASE_NOTES.md +95 -62
  3. package/class-generation/base-page.ts +141 -59
  4. package/class-generation/diagnostics.ts +559 -0
  5. package/class-generation/index.ts +247 -128
  6. package/class-generation/playwright-types.ts +7 -11
  7. package/class-generation/pointer.ts +65 -18
  8. package/dist/class-generation/base-page.d.ts +19 -4
  9. package/dist/class-generation/base-page.d.ts.map +1 -1
  10. package/dist/class-generation/diagnostics.d.ts +110 -0
  11. package/dist/class-generation/diagnostics.d.ts.map +1 -0
  12. package/dist/class-generation/index.d.ts +4 -0
  13. package/dist/class-generation/index.d.ts.map +1 -1
  14. package/dist/class-generation/playwright-types.d.ts +3 -39
  15. package/dist/class-generation/playwright-types.d.ts.map +1 -1
  16. package/dist/class-generation/pointer.d.ts +10 -1
  17. package/dist/class-generation/pointer.d.ts.map +1 -1
  18. package/dist/eslint/index.cjs +52 -9
  19. package/dist/eslint/index.cjs.map +1 -1
  20. package/dist/eslint/index.d.ts +16 -7
  21. package/dist/eslint/index.d.ts.map +1 -1
  22. package/dist/eslint/index.mjs +52 -9
  23. package/dist/eslint/index.mjs.map +1 -1
  24. package/dist/index.cjs +728 -324
  25. package/dist/index.cjs.map +1 -1
  26. package/dist/index.mjs +728 -324
  27. package/dist/index.mjs.map +1 -1
  28. package/dist/manifest-generator.d.ts +10 -5
  29. package/dist/manifest-generator.d.ts.map +1 -1
  30. package/dist/method-generation.d.ts.map +1 -1
  31. package/dist/playwright/reporter.cjs +174 -0
  32. package/dist/playwright/reporter.cjs.map +1 -0
  33. package/dist/playwright/reporter.d.ts +13 -0
  34. package/dist/playwright/reporter.d.ts.map +1 -0
  35. package/dist/playwright/reporter.mjs +174 -0
  36. package/dist/playwright/reporter.mjs.map +1 -0
  37. package/dist/plugin/internal/build-plugin.d.ts +2 -0
  38. package/dist/plugin/internal/build-plugin.d.ts.map +1 -1
  39. package/dist/plugin/internal/dev-plugin.d.ts +2 -0
  40. package/dist/plugin/internal/dev-plugin.d.ts.map +1 -1
  41. package/dist/plugin/internal-plugins.d.ts.map +1 -1
  42. package/dist/route-navigation-codegen.d.ts +40 -0
  43. package/dist/route-navigation-codegen.d.ts.map +1 -0
  44. package/dist/router-bridge.d.ts +15 -0
  45. package/dist/router-bridge.d.ts.map +1 -1
  46. package/dist/router.cjs +41 -1
  47. package/dist/router.cjs.map +1 -1
  48. package/dist/router.mjs +41 -1
  49. package/dist/router.mjs.map +1 -1
  50. package/dist/tests/broad/helpers/fake-runtime.d.ts +27 -3
  51. package/dist/tests/broad/helpers/fake-runtime.d.ts.map +1 -1
  52. package/dist/tests/fixtures/generated-tsc/base-page.full.d.ts +16 -3
  53. package/dist/tests/fixtures/generated-tsc/base-page.full.d.ts.map +1 -1
  54. package/dist/tests/method-generation.test.d.ts +2 -0
  55. package/dist/tests/method-generation.test.d.ts.map +1 -0
  56. package/dist/tests/playwright-diagnostics.test.d.ts +2 -0
  57. package/dist/tests/playwright-diagnostics.test.d.ts.map +1 -0
  58. package/dist/tests/playwright-reporter.test.d.ts +2 -0
  59. package/dist/tests/playwright-reporter.test.d.ts.map +1 -0
  60. package/dist/transform.d.ts.map +1 -1
  61. package/dist/vite.config.d.ts.map +1 -1
  62. package/package.json +8 -1
@@ -9,6 +9,8 @@ import path from "node:path";
9
9
  import process from "node:process";
10
10
  import { fileURLToPath } from "node:url";
11
11
  import { generateViewObjectModelMembers, generateViewObjectModelMethodContent } from "../method-generation";
12
+ import { generatePomManifestModule } from "../manifest-generator";
13
+ import type { ElementMetadata } from "../metadata-collector";
12
14
  import {
13
15
  createPomMethodSignature,
14
16
  createPomParameterSpec,
@@ -28,8 +30,7 @@ import {
28
30
  type PomStringPattern,
29
31
  } from "../pom-patterns";
30
32
  import { buildPomLocatorDescription, stripPomActionPrefix } from "../pom-discoverability";
31
- import { getParamToken, introspectNuxtPages, parseRouterFileFromCwd } from "../router-introspection";
32
- import { POM_ROUTER_GLOBAL_NAME } from "../router-bridge";
33
+ import { introspectNuxtPages, parseRouterFileFromCwd } from "../router-introspection";
33
34
  import {
34
35
  addExportAll,
35
36
  addNamedImport,
@@ -62,6 +63,10 @@ import {
62
63
  // Intentionally imported so tooling understands this exported helper is part of the
63
64
  // generated POM public surface (it is consumed by generated Playwright fixtures).
64
65
  import { setPlaywrightAnimationOptions } from "./pointer";
66
+ import {
67
+ createRouterNavigationWriter,
68
+ createUrlNavigationWriter,
69
+ } from "../route-navigation-codegen";
65
70
 
66
71
  void setPlaywrightAnimationOptions;
67
72
 
@@ -118,6 +123,7 @@ interface RouteEntry {
118
123
  name: string | null;
119
124
  template: string;
120
125
  params: RouteParamMeta[];
126
+ query: string[];
121
127
  }
122
128
 
123
129
  interface RouteMeta {
@@ -295,7 +301,7 @@ async function getRouteMetaByComponent(
295
301
  const map = new Map<string, RouteEntry[]>();
296
302
  for (const entry of routeMetaEntries) {
297
303
  const list = map.get(entry.componentName) ?? [];
298
- list.push({ name: entry.name, template: entry.pathTemplate, params: entry.params });
304
+ list.push({ name: entry.name, template: entry.pathTemplate, params: entry.params, query: entry.query });
299
305
  map.set(entry.componentName, list);
300
306
  }
301
307
 
@@ -345,8 +351,50 @@ function generateRouteProperty(routeMeta: RouteMeta | null): TypeScriptClassMemb
345
351
  ];
346
352
  }
347
353
 
348
- function buildParamTypeString(params: RouteParamMeta[]): string {
349
- return `{ ${params.map(p => `${p.name}${p.optional ? "?" : ""}: string | number`).join("; ")} }`;
354
+ function formatNavigationFieldName(name: string): string {
355
+ return /^[$a-z_][$\w]*$/i.test(name) ? name : JSON.stringify(name);
356
+ }
357
+
358
+ function buildNavigationTypeString(route: RouteEntry, requiredOptionalParamName?: string): string {
359
+ const pathFields = route.params.map((param) => {
360
+ const forcePresent = param.optional && param.name === requiredOptionalParamName;
361
+ return `${formatNavigationFieldName(param.name)}${param.optional && !forcePresent ? "?" : ""}: string | number${forcePresent ? " | undefined" : ""}`;
362
+ });
363
+ const pathNames = new Set(route.params.map(param => param.name));
364
+ const queryFields = route.query
365
+ .filter(query => !pathNames.has(query))
366
+ .map(query => `${formatNavigationFieldName(query)}?: string | number`);
367
+ return `{ ${[...pathFields, ...queryFields].join("; ")} }`;
368
+ }
369
+
370
+ function buildParametrizedRouteSelectionTypeString(route: RouteEntry): string {
371
+ if (route.params.some(param => !param.optional)) {
372
+ return buildNavigationTypeString(route);
373
+ }
374
+
375
+ // In a dual-route overload, the runtime selects the parametrized route by path-key
376
+ // presence. Require at least one optional path key to be present so the public type
377
+ // cannot accept an object that runtime would send to the paramless route. Its value may
378
+ // still be undefined, which intentionally selects the optional-param route with that
379
+ // segment omitted.
380
+ return route.params
381
+ .map(param => buildNavigationTypeString(route, param.name))
382
+ .join(" | ");
383
+ }
384
+
385
+ function buildImplementationNavigationTypeString(routes: RouteEntry[]): string {
386
+ const fields = new Map<string, boolean>();
387
+ for (const route of routes) {
388
+ for (const param of route.params) {
389
+ fields.set(param.name, true);
390
+ }
391
+ for (const query of route.query) {
392
+ if (!fields.has(query)) {
393
+ fields.set(query, true);
394
+ }
395
+ }
396
+ }
397
+ return `{ ${Array.from(fields.keys()).map(name => `${formatNavigationFieldName(name)}?: string | number`).join("; ")} }`;
350
398
  }
351
399
 
352
400
  function chooseParamlessRoute(routes: RouteEntry[]): RouteEntry | null {
@@ -367,66 +415,12 @@ function chooseParametrizedRoute(routes: RouteEntry[]): RouteEntry | null {
367
415
  .sort((a, b) => a.params.length - b.params.length || a.template.length - b.template.length || a.template.localeCompare(b.template))[0];
368
416
  }
369
417
 
370
- const GOTO_RUNTIME_LINES = [
371
- "const runtimeEnv = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;",
372
- "const runtimeBaseUrl = runtimeEnv?.PLAYWRIGHT_RUNTIME_BASE_URL ?? runtimeEnv?.PLAYWRIGHT_TEST_BASE_URL ?? runtimeEnv?.VITE_PLAYWRIGHT_BASE_URL;",
373
- "const resolvedUrl = runtimeBaseUrl ? new URL(targetUrl, runtimeBaseUrl).toString() : targetUrl;",
374
- "await this.page.goto(resolvedUrl);",
375
- ];
376
-
377
- /**
378
- * The generator-owned `window`/`globalThis` key used by `exposeRouterForPomNavigation`,
379
- * so generated `goTo()` can drive `router.push({ name, params })` instead of reconstructing
380
- * URLs from opaque path-template tokens.
381
- */
382
- const ROUTER_GLOBAL_NAME = POM_ROUTER_GLOBAL_NAME;
383
-
384
- /**
385
- * Emits the router-driven `goTo()` body for a named route. Two regimes:
386
- *
387
- * - **Cold page** (fresh Playwright page on `about:blank` — the SPA hasn't booted, so the
388
- * router global is `undefined`): boot the app with a cheap `page.goto("/")`, wait for the
389
- * router to install, then **full-load the resolved target URL** (`router.resolve({ name,
390
- * params }).href` + `page.goto`). A full load is unavoidable here — you cannot `push`
391
- * before the router exists — and resolving the target (rather than stopping at "/") means
392
- * the route's component mounts via a stable page load, exactly as the original
393
- * `page.goto`-based tests did. This matters because the POM runtime clicks with
394
- * `force: true` (skipping Playwright's actionability check): a SPA `push` into a freshly
395
- * mounted view can resolve before radios/inputs are interactive, so a force-click fired
396
- * the instant the push resolves can miss (the control's handler isn't attached yet). A
397
- * full load gives a fully-rendered, interactive page.
398
- * - **Warm page** (the app is already mounted — any later `goTo()` in the same test): the
399
- * guard is a single cheap `evaluate` that finds the router present, so the navigation is a
400
- * pure SPA `router.push({ name, params })` — no reload — the intended fast path.
401
- *
402
- * `routeNameExpr` is a TS expression yielding the route name (a string literal for single
403
- * routes, or `params ? "edit" : "new"` for the dual-route overload). `paramsExpr` is the
404
- * params source (`"undefined"` for a paramless route, `"params"` otherwise); `nullable` is
405
- * true only when that source may itself be `undefined` (the all-optional-params overload),
406
- * gating the `?? {}` guard that TS2871 would otherwise flag on a required param.
407
- */
408
- const pushBlock = (routeNameExpr: string, paramsExpr: string, nullable: boolean): string[] => {
409
- const routerType = `{ ${ROUTER_GLOBAL_NAME}?: { push: (to: { name: string; params: Record<string, unknown> }) => Promise<unknown>; resolve: (to: { name: string; params: Record<string, unknown> }) => { href: string } } }`;
410
- const routeParamsLine = paramsExpr === "undefined"
411
- ? "const routeParams = {};"
412
- : nullable
413
- ? `const routeParams = Object.fromEntries(Object.entries(${paramsExpr} ?? {}).filter(([, v]) => v !== undefined));`
414
- : `const routeParams = Object.fromEntries(Object.entries(${paramsExpr}).filter(([, v]) => v !== undefined));`;
415
- return [
416
- routeParamsLine,
417
- `const isCold = await this.page.evaluate(() => typeof (globalThis as { ${ROUTER_GLOBAL_NAME}?: unknown }).${ROUTER_GLOBAL_NAME} === "undefined");`,
418
- `if (isCold) {`,
419
- ` await this.page.goto("/", { waitUntil: "commit" });`,
420
- ` await this.page.waitForFunction(() => typeof (globalThis as { ${ROUTER_GLOBAL_NAME}?: unknown }).${ROUTER_GLOBAL_NAME} !== "undefined", { timeout: 15000 });`,
421
- ` const href = await this.page.evaluate(({ name, params }) => (globalThis as ${routerType}).${ROUTER_GLOBAL_NAME}?.resolve({ name, params })?.href, { name: ${routeNameExpr}, params: routeParams });`,
422
- ` if (href) { await this.page.goto(href, { waitUntil: "domcontentloaded" }); }`,
423
- `} else {`,
424
- ` await this.page.evaluate(async ({ name, params }) => {`,
425
- ` await (globalThis as ${routerType}).${ROUTER_GLOBAL_NAME}?.push({ name, params });`,
426
- ` }, { name: ${routeNameExpr}, params: routeParams });`,
427
- `}`,
428
- ];
429
- };
418
+ function requireRouteName(route: RouteEntry): string {
419
+ if (route.name === null) {
420
+ throw new VuePomGeneratorError(`Named navigation requires a route name for template "${route.template}".`);
421
+ }
422
+ return route.name;
423
+ }
430
424
 
431
425
  function generateGoToMethod(componentName: string, routeMeta: RouteMeta | null): TypeScriptClassMember[] {
432
426
  // No route metadata: emit a goTo() that fails loudly when invoked.
@@ -460,44 +454,41 @@ function generateGoToMethod(componentName: string, routeMeta: RouteMeta | null):
460
454
  ];
461
455
  }
462
456
 
463
- // Fallback (unnamed routes, e.g. Nuxt file-based routes whose names the static walk
464
- // cannot recover): reconstruct the URL from the tokenized template and `page.goto` it.
465
- const paramStatements = (entry: RouteEntry): string[] => {
466
- const lines: string[] = [];
467
- for (const param of entry.params) {
468
- const token = getParamToken(param.name);
469
- if (param.optional) {
470
- // An omitted optional param drops its entire path segment (including the leading "/"),
471
- // so `/persons/:personId/:tabName?` with tabName omitted resolves to `/persons/123`.
472
- lines.push(`targetUrl = params.${param.name} === undefined ? targetUrl.replaceAll(${JSON.stringify(`/${token}`)}, "") : targetUrl.replaceAll(${JSON.stringify(token)}, String(params.${param.name}));`);
473
- }
474
- else {
475
- lines.push(`targetUrl = targetUrl.replaceAll(${JSON.stringify(token)}, String(params.${param.name}));`);
476
- }
477
- }
478
- return lines;
479
- };
480
-
481
457
  // Preferred path: the route is named, so hand the param object straight to the runtime
482
458
  // router. `undefined` values are stripped first — omitted optional params are simply not
483
459
  // passed, and the router builds the URL (handling optional segments, redirects, and param
484
- // coercion) itself. No opaque tokens, no string substitution. See `pushBlock` for the
460
+ // coercion) itself. No opaque tokens, no string substitution. The centralized router writer owns the
485
461
  // cold-start (full-load resolved target) vs warm (SPA `router.push`) regimes.
486
- // Paramless-only: simple no-arg goTo().
462
+ // Paramless-only: query keys, when present, are optional navigation arguments.
487
463
  if (hasParamless && !hasParametrized) {
488
464
  const route = paramless!;
465
+ const hasQuery = route.query.length > 0;
466
+ const paramType = buildNavigationTypeString(route);
489
467
  return [
490
468
  createClassMethod({
491
469
  name: "goTo",
492
470
  isAsync: true,
471
+ parameters: hasQuery ? [{ name: "params", type: paramType, hasQuestionToken: true }] : [],
493
472
  statements: route.name !== null
494
- ? pushBlock(JSON.stringify(route.name), "undefined", false)
495
- : [`const targetUrl = ${JSON.stringify(route.template)};`, ...GOTO_RUNTIME_LINES],
473
+ ? createRouterNavigationWriter({
474
+ componentName,
475
+ routeName: { kind: "single", target: route.name },
476
+ input: hasQuery ? { identifier: "params", optional: true } : undefined,
477
+ pathParamNames: [],
478
+ queryNames: route.query,
479
+ })
480
+ : createUrlNavigationWriter({
481
+ componentName,
482
+ routeTemplate: { kind: "single", target: route.template },
483
+ input: hasQuery ? { identifier: "params", optional: true } : undefined,
484
+ pathParams: [],
485
+ queryNames: route.query,
486
+ }),
496
487
  }),
497
488
  ];
498
489
  }
499
490
 
500
- const paramType = buildParamTypeString(parametrized!.params);
491
+ const paramType = buildNavigationTypeString(parametrized!);
501
492
 
502
493
  // Parametrized-only: goTo(params). When every declared param is optional, the params
503
494
  // object itself is optional too — `goTo()` is a valid call that navigates to the route
@@ -511,8 +502,20 @@ function generateGoToMethod(componentName: string, routeMeta: RouteMeta | null):
511
502
  isAsync: true,
512
503
  parameters: [{ name: "params", type: paramType, hasQuestionToken: allOptional }],
513
504
  statements: route.name !== null
514
- ? pushBlock(JSON.stringify(route.name), "params", allOptional)
515
- : [`let targetUrl = ${JSON.stringify(route.template)};`, ...paramStatements(route), ...GOTO_RUNTIME_LINES],
505
+ ? createRouterNavigationWriter({
506
+ componentName,
507
+ routeName: { kind: "single", target: route.name },
508
+ input: { identifier: "params", optional: allOptional },
509
+ pathParamNames: route.params.map(param => param.name),
510
+ queryNames: route.query,
511
+ })
512
+ : createUrlNavigationWriter({
513
+ componentName,
514
+ routeTemplate: { kind: "single", target: route.template },
515
+ input: { identifier: "params", optional: allOptional },
516
+ pathParams: route.params,
517
+ queryNames: route.query,
518
+ }),
516
519
  }),
517
520
  ];
518
521
  }
@@ -522,30 +525,52 @@ function generateGoToMethod(componentName: string, routeMeta: RouteMeta | null):
522
525
  const paramlessRoute = paramless!;
523
526
  const parametrizedRoute = parametrized!;
524
527
  const usePush = paramlessRoute.name !== null && parametrizedRoute.name !== null;
525
-
528
+ const paramlessType = buildNavigationTypeString(paramlessRoute);
529
+ const parametrizedOverloadType = buildParametrizedRouteSelectionTypeString(parametrizedRoute);
530
+ const queryNames = Array.from(new Set([...paramlessRoute.query, ...parametrizedRoute.query]));
531
+ const hasQuery = queryNames.length > 0;
532
+ const implementationType = hasQuery
533
+ ? buildImplementationNavigationTypeString([paramlessRoute, parametrizedRoute])
534
+ : paramType;
526
535
  return [
527
536
  createClassMethod({
528
537
  name: "goTo",
529
538
  isAsync: true,
530
539
  overloads: [
531
- { parameters: [], returnType: "Promise<void>" },
532
- { parameters: [{ name: "params", type: paramType }], returnType: "Promise<void>" },
540
+ {
541
+ parameters: paramlessRoute.query.length
542
+ ? [{ name: "params", type: paramlessType, hasQuestionToken: true }]
543
+ : [],
544
+ returnType: "Promise<void>",
545
+ },
546
+ { parameters: [{ name: "params", type: parametrizedOverloadType }], returnType: "Promise<void>" },
533
547
  ],
534
- parameters: [{ name: "params", type: paramType, hasQuestionToken: true }],
548
+ parameters: [{ name: "params", type: implementationType, hasQuestionToken: true }],
535
549
  statements: usePush
536
- ? pushBlock(
537
- `params ? ${JSON.stringify(parametrizedRoute.name)} : ${JSON.stringify(paramlessRoute.name)}`,
538
- "params",
539
- true,
540
- )
541
- : [
542
- `const template = params ? ${JSON.stringify(parametrizedRoute.template)} : ${JSON.stringify(paramlessRoute.template)};`,
543
- "let targetUrl = template;",
544
- `if (params) {`,
545
- ...paramStatements(parametrizedRoute).map(line => ` ${line}`),
546
- "}",
547
- ...GOTO_RUNTIME_LINES,
548
- ],
550
+ ? createRouterNavigationWriter({
551
+ componentName,
552
+ routeName: {
553
+ kind: "dual",
554
+ parametrizedTarget: requireRouteName(parametrizedRoute),
555
+ paramlessTarget: requireRouteName(paramlessRoute),
556
+ selectBy: hasQuery ? "path-param-presence" : "input-presence",
557
+ },
558
+ input: { identifier: "params", optional: true },
559
+ pathParamNames: parametrizedRoute.params.map(param => param.name),
560
+ queryNames: hasQuery ? queryNames : [],
561
+ })
562
+ : createUrlNavigationWriter({
563
+ componentName,
564
+ routeTemplate: {
565
+ kind: "dual",
566
+ parametrizedTarget: parametrizedRoute.template,
567
+ paramlessTarget: paramlessRoute.template,
568
+ selectBy: hasQuery ? "path-param-presence" : "input-presence",
569
+ },
570
+ input: { identifier: "params", optional: true },
571
+ pathParams: parametrizedRoute.params,
572
+ queryNames: hasQuery ? queryNames : [],
573
+ }),
549
574
  }),
550
575
  ];
551
576
  }
@@ -594,7 +619,7 @@ function generateExtraClickMethodMembers(spec: PomExtraClickMethodSpec, componen
594
619
  for (const statement of testIdBinding.setupStatements) {
595
620
  writer.writeLine(statement);
596
621
  }
597
- writer.writeLine(`await this.clickByTestId(${testIdBinding.expression}, ${annotationArg}, ${waitArg}, ${locatorDescription});`);
622
+ writer.writeLine(`await this.clickByTestId(${testIdBinding.expression}, ${annotationArg}, ${waitArg}, ${locatorDescription}, { componentName: ${JSON.stringify(componentName)}, methodName: ${JSON.stringify(spec.name)} });`);
598
623
  },
599
624
  }),
600
625
  ];
@@ -617,7 +642,7 @@ function generateExtraClickMethodMembers(spec: PomExtraClickMethodSpec, componen
617
642
  for (const statement of labelBinding.setupStatements) {
618
643
  writer.writeLine(statement);
619
644
  }
620
- writer.writeLine(`await this.clickWithinTestIdByLabel(${rootBinding.expression}, ${labelBinding.expression}, ${annotationArg}, ${waitArg}, { description: ${locatorDescription} });`);
645
+ writer.writeLine(`await this.clickWithinTestIdByLabel(${rootBinding.expression}, ${labelBinding.expression}, ${annotationArg}, ${waitArg}, { description: ${locatorDescription}, componentName: ${JSON.stringify(componentName)}, methodName: ${JSON.stringify(spec.name)} });`);
621
646
  },
622
647
  }),
623
648
  ];
@@ -791,6 +816,9 @@ export interface GenerateFilesOptions {
791
816
  layoutDirs?: string[];
792
817
 
793
818
  routeMetaByComponent?: Record<string, RouteMeta>;
819
+
820
+ /** Metadata used by the generated Node-importable POM discoverability manifest. */
821
+ elementMetadata?: Map<string, Map<string, ElementMetadata>>;
794
822
  }
795
823
 
796
824
  interface BaseGenerateContentOptions {
@@ -855,6 +883,7 @@ export async function generateFiles(
855
883
  componentDirs,
856
884
  layoutDirs,
857
885
  routeMetaByComponent: routeMetaByComponentOverride,
886
+ elementMetadata = new Map<string, Map<string, ElementMetadata>>(),
858
887
  } = options;
859
888
 
860
889
  const emitLanguages: Array<"ts" | "csharp"> = emitLanguagesOverride?.length
@@ -908,13 +937,15 @@ export async function generateFiles(
908
937
  writeGeneratedFile(file);
909
938
  }
910
939
 
911
- const fixtureRegistryFile = maybeGenerateFixtureRegistry(emittableComponentHierarchyMap, {
940
+ const fixtureRegistryFiles = maybeGenerateFixtureRegistry(emittableComponentHierarchyMap, {
912
941
  generateFixtures,
913
942
  pomOutDir: outDir,
914
943
  projectRoot,
915
944
  customPomDir,
945
+ elementMetadata,
946
+ testIdAttribute,
916
947
  });
917
- if (fixtureRegistryFile) {
948
+ for (const fixtureRegistryFile of fixtureRegistryFiles) {
918
949
  writeGeneratedFile(fixtureRegistryFile);
919
950
  }
920
951
  }
@@ -1523,11 +1554,13 @@ function maybeGenerateFixtureRegistry(
1523
1554
  pomOutDir: string;
1524
1555
  projectRoot?: string;
1525
1556
  customPomDir?: string;
1557
+ elementMetadata: Map<string, Map<string, ElementMetadata>>;
1558
+ testIdAttribute?: string;
1526
1559
  },
1527
- ): GeneratedFileOutput | null {
1560
+ ): GeneratedFileOutput[] {
1528
1561
  const { generateFixtures, pomOutDir } = options;
1529
1562
  if (!generateFixtures)
1530
- return null;
1563
+ return [];
1531
1564
 
1532
1565
  // generateFixtures accepts:
1533
1566
  // - true: enable fixtures with defaults
@@ -1559,6 +1592,10 @@ function maybeGenerateFixtureRegistry(
1559
1592
  const pomDirAbs = path.isAbsolute(pomOutDir) ? pomOutDir : path.resolve(root, pomOutDir);
1560
1593
 
1561
1594
  const pomImport = toPosixRelativePath(fixtureOutDirAbs, pomDirAbs);
1595
+ const diagnosticsImport = stripExtension(toPosixRelativePath(
1596
+ fixtureOutDirAbs,
1597
+ path.join(pomDirAbs, "_pom-runtime", "class-generation", "diagnostics.ts"),
1598
+ ));
1562
1599
 
1563
1600
  const viewClassNames = Array.from(componentHierarchyMap.entries())
1564
1601
  .filter(([, deps]) => !!deps.isView)
@@ -1574,6 +1611,7 @@ function maybeGenerateFixtureRegistry(
1574
1611
  "request",
1575
1612
  // Our own fixtureOptions
1576
1613
  "animation",
1614
+ "pomDiagnostics",
1577
1615
  ]);
1578
1616
 
1579
1617
  const viewFixtureNames = new Set(viewClassNames.map(name => lowerFirst(name)));
@@ -1636,13 +1674,27 @@ function maybeGenerateFixtureRegistry(
1636
1674
  namedImports: [
1637
1675
  { name: "Page", alias: "PwPage" },
1638
1676
  "PlaywrightTestArgs",
1677
+ "TestInfo",
1639
1678
  "TestType",
1640
1679
  ],
1641
1680
  });
1681
+ addNamedImport(sourceFile, {
1682
+ moduleSpecifier: diagnosticsImport,
1683
+ namedImports: ["installPomFailureDiagnostics"],
1684
+ });
1685
+ addNamedImport(sourceFile, {
1686
+ moduleSpecifier: diagnosticsImport,
1687
+ isTypeOnly: true,
1688
+ namedImports: ["PomFailureDiagnosticsOptions"],
1689
+ });
1642
1690
  sourceFile.addImportDeclaration({
1643
1691
  namespaceImport: "Pom",
1644
1692
  moduleSpecifier: pomImport,
1645
1693
  });
1694
+ addNamedImport(sourceFile, {
1695
+ moduleSpecifier: "./pom-manifest.g",
1696
+ namedImports: ["pomManifest"],
1697
+ });
1646
1698
  for (const entry of overrideCtorEntries) {
1647
1699
  addNamedImport(sourceFile, {
1648
1700
  moduleSpecifier: entry.importSpecifier,
@@ -1656,6 +1708,9 @@ function maybeGenerateFixtureRegistry(
1656
1708
  properties: [{
1657
1709
  name: "animation",
1658
1710
  type: "Pom.PlaywrightAnimationOptions",
1711
+ }, {
1712
+ name: "pomDiagnostics",
1713
+ type: "PomFailureDiagnosticsOptions",
1659
1714
  }],
1660
1715
  });
1661
1716
  sourceFile.addTypeAlias({
@@ -1682,6 +1737,10 @@ function maybeGenerateFixtureRegistry(
1682
1737
  name: "PomFactoryFixture",
1683
1738
  type: "{ pomFactory: PomFactory }",
1684
1739
  });
1740
+ sourceFile.addTypeAlias({
1741
+ name: "PomDiagnosticsSetupFixture",
1742
+ type: "{ pomDiagnosticsSetup: void }",
1743
+ });
1685
1744
 
1686
1745
  sourceFile.addVariableStatement({
1687
1746
  declarationKind: VariableDeclarationKind.Const,
@@ -1731,7 +1790,7 @@ function maybeGenerateFixtureRegistry(
1731
1790
  description: "Every fixture contributed by the generator: the `animation` option, the internal\n"
1732
1791
  + "`pomSetup`/`pomFactory` fixtures, and one fixture per generated page/component POM.",
1733
1792
  }],
1734
- type: "PlaywrightOptions & PomSetupFixture & PomFactoryFixture & GeneratedPageFixtures & GeneratedComponentFixtures",
1793
+ type: "PlaywrightOptions & PomSetupFixture & PomFactoryFixture & PomDiagnosticsSetupFixture & GeneratedPageFixtures & GeneratedComponentFixtures",
1735
1794
  });
1736
1795
 
1737
1796
  sourceFile.addFunction({
@@ -1785,10 +1844,12 @@ function maybeGenerateFixtureRegistry(
1785
1844
  writer.block(() => {
1786
1845
  writer.writeLine("animation: [{");
1787
1846
  writer.indent(() => {
1847
+ writer.writeLine("enabled: false,");
1788
1848
  writer.writeLine('pointer: { durationMilliseconds: 250, transitionStyle: "ease-in-out", clickDelayMilliseconds: 0 },');
1789
1849
  writer.writeLine("keyboard: { typeDelayMilliseconds: 100 },");
1790
1850
  });
1791
1851
  writer.writeLine("}, { option: true }],");
1852
+ writer.writeLine(`pomDiagnostics: [{ captureBudgetMs: 5_000, testIdAttribute: ${JSON.stringify(options.testIdAttribute ?? "data-testid")} }, { option: true }],`);
1792
1853
  // The fixture callbacks are annotated explicitly rather than relying on
1793
1854
  // contextual typing: `base` is generic here, so TypeScript cannot resolve
1794
1855
  // Playwright's `Fixtures<...>` parameter types and the callbacks would
@@ -1799,6 +1860,20 @@ function maybeGenerateFixtureRegistry(
1799
1860
  writer.writeLine("await use();");
1800
1861
  });
1801
1862
  writer.writeLine("}, { auto: true }],");
1863
+ writer.writeLine("pomDiagnosticsSetup: [async ({ page, pomDiagnostics }: { page: PwPage; pomDiagnostics: PomFailureDiagnosticsOptions }, use: (r: void) => Promise<void>, testInfo: TestInfo) => {");
1864
+ writer.indent(() => {
1865
+ writer.writeLine("const capture = installPomFailureDiagnostics(page, pomManifest, testInfo, pomDiagnostics);");
1866
+ writer.writeLine("try {");
1867
+ writer.indent(() => writer.writeLine("await use();"));
1868
+ writer.writeLine("} finally {");
1869
+ writer.indent(() => {
1870
+ writer.writeLine("if (testInfo.status !== undefined && testInfo.status !== testInfo.expectedStatus) {");
1871
+ writer.indent(() => writer.writeLine("await capture.capture().catch(() => undefined);"));
1872
+ writer.writeLine("}");
1873
+ });
1874
+ writer.writeLine("}");
1875
+ });
1876
+ writer.writeLine("}, { auto: true }],");
1802
1877
  writer.writeLine("pomFactory: async ({ page }: { page: PwPage }, use: (r: PomFactory) => Promise<void>) => {");
1803
1878
  writer.indent(() => {
1804
1879
  writer.writeLine("await use({");
@@ -1830,10 +1905,32 @@ function maybeGenerateFixtureRegistry(
1830
1905
  }),
1831
1906
  });
1832
1907
 
1833
- return {
1834
- filePath: path.resolve(fixtureOutDirAbs, fixtureFileName),
1835
- content: fixturesContent,
1836
- };
1908
+ const manifestFileName = "pom-manifest.g.ts";
1909
+ const manifestContent = generatePomManifestModule(
1910
+ componentHierarchyMap,
1911
+ options.elementMetadata,
1912
+ manifestFileName,
1913
+ );
1914
+ const [diagnosticsRuntimeFile] = buildRuntimeGeneratedFilesFromSpecs([{
1915
+ absolutePath: resolvePluginAsset("../class-generation/diagnostics.ts"),
1916
+ description: "diagnostics.ts",
1917
+ outputPath: path.join(pomDirAbs, "_pom-runtime", "class-generation", "diagnostics.ts"),
1918
+ }]);
1919
+ if (!diagnosticsRuntimeFile) {
1920
+ throw new Error("[vue-pom-generator] Failed to generate the Playwright diagnostics runtime.");
1921
+ }
1922
+
1923
+ return [
1924
+ {
1925
+ filePath: path.resolve(fixtureOutDirAbs, fixtureFileName),
1926
+ content: fixturesContent,
1927
+ },
1928
+ {
1929
+ filePath: path.resolve(fixtureOutDirAbs, manifestFileName),
1930
+ content: manifestContent,
1931
+ },
1932
+ diagnosticsRuntimeFile,
1933
+ ];
1837
1934
 
1838
1935
  // No pomFixture is generated; goToSelf is emitted directly on each view POM.
1839
1936
  }
@@ -1878,6 +1975,33 @@ function prepareViewObjectModelClass(
1878
1975
  return match;
1879
1976
  };
1880
1977
 
1978
+ const hasGeneratedPomSurface = (value: string, seen = new Set<string>()): boolean => {
1979
+ const resolvedRef = resolveTrackedComponentRef(value);
1980
+ if (!resolvedRef || seen.has(resolvedRef)) {
1981
+ return false;
1982
+ }
1983
+
1984
+ const resolvedDependencies = componentHierarchyMap.get(resolvedRef);
1985
+ if (!resolvedDependencies) {
1986
+ return false;
1987
+ }
1988
+
1989
+ if (
1990
+ resolvedDependencies.dataTestIdSet.size > 0
1991
+ || (resolvedDependencies.pomExtraMethods?.length ?? 0) > 0
1992
+ || (resolvedDependencies.generatedMethods?.size ?? 0) > 0
1993
+ ) {
1994
+ return true;
1995
+ }
1996
+
1997
+ const nextSeen = new Set(seen);
1998
+ nextSeen.add(resolvedRef);
1999
+ const nestedRefs = resolvedDependencies.usedComponentSet?.size
2000
+ ? resolvedDependencies.usedComponentSet
2001
+ : resolvedDependencies.childrenComponentSet;
2002
+ return Array.from(nestedRefs).some(child => hasGeneratedPomSurface(child, nextSeen));
2003
+ };
2004
+
1881
2005
  const rawComponentRefsForInstances = usedComponentSet?.size
1882
2006
  ? usedComponentSet
1883
2007
  : childrenComponentSet;
@@ -1896,8 +2020,7 @@ function prepareViewObjectModelClass(
1896
2020
  if (isSelfReference(resolvedRef)) {
1897
2021
  continue;
1898
2022
  }
1899
- const resolvedDependencies = componentHierarchyMap.get(resolvedRef);
1900
- if (!resolvedDependencies?.dataTestIdSet.size) {
2023
+ if (!hasGeneratedPomSurface(resolvedRef, new Set([componentName]))) {
1901
2024
  continue;
1902
2025
  }
1903
2026
  componentRefsForInstances.add(resolvedRef);
@@ -1956,7 +2079,6 @@ function prepareViewObjectModelClass(
1956
2079
 
1957
2080
  const className = toPascalCaseLocal(componentName);
1958
2081
  const childInstancePropertyNames = Array.from(componentRefsForInstances)
1959
- .filter(child => componentHierarchyMap.has(child) && componentHierarchyMap.get(child)?.dataTestIdSet.size)
1960
2082
  .map(child => child.split(".vue")[0]);
1961
2083
  const blockedViewPassthroughMethodNames = new Set(
1962
2084
  attachmentsForThisClass
@@ -2090,10 +2212,7 @@ function generateViewObjectModelContent(
2090
2212
 
2091
2213
  for (const child of prepared.componentRefsForInstances) {
2092
2214
  const childName = child.endsWith(".vue") ? child.slice(0, -4) : child;
2093
- const childDeps = componentHierarchyMap.get(child) ?? componentHierarchyMap.get(childName);
2094
- if (childDeps?.dataTestIdSet.size) {
2095
- addGeneratedImport(childName);
2096
- }
2215
+ addGeneratedImport(childName);
2097
2216
  }
2098
2217
 
2099
2218
  const targetClassNames = Array.from(
@@ -2548,7 +2667,7 @@ function getRuntimeGeneratedAssetSpecs(baseDir: string, basePageClassPath: strin
2548
2667
  const runtimeClassGenSourceDir = resolvePluginAsset("../class-generation");
2549
2668
  const runtimeClassGenFiles = fs.readdirSync(runtimeClassGenSourceDir)
2550
2669
  .filter(file => file.endsWith(".ts"))
2551
- .filter(file => file !== "base-page.ts" && file !== "index.ts")
2670
+ .filter(file => file !== "base-page.ts" && file !== "diagnostics.ts" && file !== "index.ts")
2552
2671
  .sort((left, right) => left.localeCompare(right));
2553
2672
 
2554
2673
  return [
@@ -3137,7 +3256,7 @@ function getComponentInstances(
3137
3256
  }
3138
3257
 
3139
3258
  childrenComponent.forEach((child) => {
3140
- if (componentHierarchyMap.has(child) && componentHierarchyMap.get(child)?.dataTestIdSet.size) {
3259
+ if (componentHierarchyMap.has(child)) {
3141
3260
  const childName = child.split(".vue")[0];
3142
3261
  declarations.push(createClassProperty({
3143
3262
  name: childName,
@@ -3174,7 +3293,7 @@ function getConstructor(
3174
3293
  }
3175
3294
 
3176
3295
  childrenComponent.forEach((child) => {
3177
- if (componentHierarchyMap.has(child) && componentHierarchyMap.get(child)?.dataTestIdSet.size) {
3296
+ if (componentHierarchyMap.has(child)) {
3178
3297
  const childName = child.split(".vue")[0];
3179
3298
  writer.writeLine(`this.${childName} = new ${childName}(page);`);
3180
3299
  }
@@ -70,7 +70,12 @@ export interface BasePageLocator {
70
70
  options?: { force?: boolean; noWaitAfter?: boolean; timeout?: number },
71
71
  ): Promise<string[]>;
72
72
  type(text: string, options?: { delay?: number; noWaitAfter?: boolean; timeout?: number }): Promise<void>;
73
- evaluate<R>(pageFunction: (element: { tagName: string; isContentEditable?: boolean }) => R | Promise<R>): Promise<R>;
73
+ evaluate<R>(pageFunction: (element: {
74
+ tagName: string;
75
+ isContentEditable?: boolean;
76
+ parentElement?: Element | null;
77
+ getAnimations?: () => Animation[];
78
+ }) => R | Promise<R>): Promise<R>;
74
79
  }
75
80
 
76
81
  /**
@@ -88,17 +93,8 @@ export interface BasePageLocator {
88
93
  */
89
94
  export interface BasePagePage {
90
95
  url(): string;
91
- goto(url: string, options?: { referer?: string; timeout?: number; waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit" }): Promise<Response | null>;
96
+ goto(url: string, options?: { referer?: string; timeout?: number; waitUntil?: "load" | "domcontentloaded" | "commit" }): Promise<Response | null>;
92
97
  locator(selector: string, options?: { has?: BasePageLocator; hasNot?: BasePageLocator; hasNotText?: string | RegExp; hasText?: string | RegExp }): BasePageLocator;
93
- isVisible(selector: string, options?: { strict?: boolean; timeout?: number }): Promise<boolean>;
94
- textContent(selector: string, options?: { strict?: boolean; timeout?: number }): Promise<string | null>;
95
- waitForSelector(selector: string, options?: { state?: "attached" | "detached" | "visible" | "hidden"; timeout?: number; strict?: boolean }): Promise<unknown>;
96
- hover(selector: string, options?: { force?: boolean; noWaitAfter?: boolean; position?: { x: number; y: number }; strict?: boolean; timeout?: number; trial?: boolean }): Promise<void>;
97
- selectOption(
98
- selector: string,
99
- values: null | string | ReadonlyArray<string> | { value?: string; label?: string; index?: number } | ReadonlyArray<{ value?: string; label?: string; index?: number }>,
100
- options?: { force?: boolean; noWaitAfter?: boolean; strict?: boolean; timeout?: number },
101
- ): Promise<string[]>;
102
98
  waitForTimeout(timeout: number): Promise<void>;
103
99
  evaluate<R, Arg = never>(pageFunction: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>;
104
100
  readonly keyboard: Keyboard;