@immense/vue-pom-generator 1.0.84 → 1.0.86

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.
package/RELEASE_NOTES.md CHANGED
@@ -1,72 +1,68 @@
1
- I'll verify the actual commits in the release range to write accurate notes.
1
+ I'll gather the actual data from the repository to determine which PRs fall within the release
2
+ window and what commits are in the compare range.
2
3
 
3
- Let me fetch the PR details to understand the changes accurately.
4
+ Good - the compare range confirms only one commit (#52). Let me get the PR details for the release
5
+ window.
4
6
 
5
- Now I have full details on both PRs. Let me compose the release notes.
7
+ Let me try a different approach to get PR merge timestamps.
6
8
 
7
- Highlights
9
+ Now I can see the merge timestamps. Let me verify which commits are actually in the compare range
10
+ and check the v1.0.85 tag timing.
8
11
 
9
- - Eliminated getTemplateVariables / inferPomStringPattern — pattern kind and template variables are
10
- now supplied explicitly at createPomStringPattern construction (required 3rd arg) and carried on
11
- PomStringPattern, never re-derived from the formatted string.
12
- - Narrowed Playwright types — PwPage/PwLocator became minimal structural interfaces
13
- (BasePagePage/BasePageLocator) that real Playwright types still satisfy, enabling cast-free test
14
- mocks.
15
- - Tightened no-explicit-any to error in tests — every as any cast replaced with typed construction
16
- via new shared mock helpers.
17
- - Added broad test coverage — 10 new test files in tests/broad/ exercise previously uncovered
18
- modules; 369 tests pass across 34 files.
19
- - Introduced shared typed mock infrastructure (typed-mocks.ts, fake-runtime.ts) and expanded the
20
- __internal export surface for unit testing.
12
+ Now I have clarity. v1.0.85 already included #51 and #49. Only #52 is new in v1.0.86. Let me examine
13
+ the actual diff to write accurate notes.
21
14
 
22
- Changes
15
+ I now have a complete understanding of the changes. This release contains only PR #52. Let me verify
16
+ the tests pass to include accurate testing info.
23
17
 
24
- Refactoring
18
+ I have all the information needed. The environment restricts running Node.js tests, but I've
19
+ thoroughly reviewed the diff. Here are the release notes:
25
20
 
26
- - Removed getTemplateVariables / inferPomStringPattern; pattern kind and template variables are now
27
- passed explicitly at createPomStringPattern construction and stored on PomStringPattern.
28
- - toPomKeyPattern now returns { formatted, templateVariables }; applyResolvedDataTestId threads
29
- template variables through.
30
- - Added collapseWhitespace to utils.ts, replacing an inline regex in compiler-metadata-utils.ts.
31
- - Expanded the transform / utils __internal export surface (including resetCaches) to support unit
32
- testing.
21
+ Highlights
33
22
 
34
- Type Safety
23
+ - Narrowed Playwright types (PwPage, PwLocator) no longer leak into generated POM public APIs —
24
+ consumers now see standard Playwright Page and Locator types throughout.
25
+ - BasePage.page is now a widened protected get getter backed by a private narrowed field, keeping
26
+ test doubles simple while surfacing full Playwright types to subclasses.
27
+ - Locator-returning accessors (locatorByTestId, keyedLocators, describeLocator,
28
+ locatorByTestIdGetByLabel) now return Playwright's full Locator, enabling
29
+ expect(page.SaveButton).toBeVisible() without type errors.
30
+ - Generated POMs construct child/custom POMs with this.page (full Page) instead of the
31
+ constructor's narrowed page parameter.
35
32
 
36
- - Replaced broad PwPage/PwLocator type aliases with minimal structural interfaces
37
- (BasePagePage/BasePageLocator) that real Playwright types satisfy, so mocks need ~15 members with no
38
- casts.
39
- - Added an ESLint override turning ts/method-signature-style off for playwright-types.ts to keep
40
- shorthand method signatures bivariant.
41
- - Promoted no-explicit-any from off to error for the test config; replaced all as any casts with
42
- typed construction via tests/helpers/typed-mocks.ts (hookFn, makeElementNode, makeTransformContext,
43
- makeVNodeCall, …) and tests/broad/helpers/fake-runtime.ts (MockPage/MockLocator).
33
+ Changes
44
34
 
45
- Testing
35
+ Type System & Consumer Compatibility
36
+
37
+ - BasePage stores the page as a private _page: PwPage field and exposes it through a protected get
38
+ page(): Page getter that widens to Playwright's full Page type.
39
+ - Internal Callout and Pointer construction now uses the narrowed this._page; subclass-facing
40
+ access uses the widened this.page.
41
+ - screencast getter return type widened from PwPage["screencast"] to Page["screencast"].
42
+ - describeLocator, locatorByTestId, locatorByTestIdGetByLabel, and keyedLocators return
43
+ Playwright's full Locator instead of the narrowed PwLocator.
44
+ - PwLocator doc comment updated to clarify it is for internal parameters only; return types widen
45
+ at the boundary.
46
+
47
+ Code Generation
46
48
 
47
- - Added standalone test files in tests/broad/ covering: class-generation-base-page-ts,
48
- typescript-codegen-ts, manifest-generator-ts, compiler-metadata-utils-ts, metadata-collector-ts,
49
- plugin-logger-ts, plugin-resolved-generation-options-ts, plugin-runtime-annotator-format-ts,
50
- accessibility-audit-ts.
51
- - Added tests/annotator-runtime-helpers.test.ts for annotator pure helpers.
52
- - Updated existing tests (base-page, build-serve-parity, class-generation-coverage,
53
- class-generation, existing-id-error, generated-tsc, metadata-collector, router-introspection,
54
- transform, utils-coverage, utils, virtual-testids) to use typed mocks.
49
+ - Generated POM constructors pass this.page to child widget and custom POM instances instead of the
50
+ raw page constructor parameter.
51
+ - Split stub POM constructors aligned to accept Playwright's full Page.
52
+ - Added inline comments documenting the narrowed-internal / widened-boundary type strategy.
55
53
 
56
- Breaking Changes
54
+ Tests
57
55
 
58
- - Internal API only: getTemplateVariables and inferPomStringPattern were removed, and
59
- createPomStringPattern now requires a 3rd argument (pattern kind). These are internal
60
- code-generation utilities not part of the consumer-facing public API (defineVuePomGeneratorConfig /
61
- vuePomGenerator), so downstream consumers are unaffected.
56
+ - Updated class-generation-coverage.test.ts and generated-tsc.test.ts expectations to match
57
+ this.page usage in generated output.
62
58
 
63
59
  Pull Requests Included
64
60
 
65
- - ]8;id=md-g075gk;https://github.com/immense/vue-pom-generator/pull/46#46 — refactor: eliminate getTemplateVariables, narrow Playwright types, tighten no-explicit-any]8;;]8;; ]8;;
66
- (@dkattan)
67
- - ]8;id=md-ga6r5j;https://github.com/immense/vue-pom-generator/pull/47#47 — test: add broad coverage for class-generation and plugin internals]8;;]8;; (@dkattan)]8;;
61
+ - ]8;id=md-1h6t1wt;https://github.com/immense/vue-pom-generator/pull/52#52 — fix: make narrowed POM types consumer-compatible]8;;]8;; (by @dkattan)]8;;
68
62
 
69
63
  Testing
70
64
 
71
- Lint clean, typecheck clean, 369 tests pass across 34 files.
65
+ - Existing class-generation coverage and generated-tsc tests were updated to reflect the this.page
66
+ change; no new test suites were added. Test suite could not be independently re-run in this
67
+ environment.
72
68
 
@@ -1,4 +1,6 @@
1
+ import type { Locator, Page } from "playwright";
1
2
  import type { PwLocator, PwPage } from "./playwright-types";
3
+
2
4
  import { TESTID_CLICK_EVENT_NAME } from "../click-instrumentation";
3
5
  import type { TestIdClickEventDetail } from "../click-instrumentation";
4
6
  import { Callout } from "./callout";
@@ -105,20 +107,42 @@ export class BasePage {
105
107
  private readonly pointer: InstanceType<typeof Pointer>;
106
108
 
107
109
  /**
108
- * @param {Page} page - Playwright page object
110
+ * The narrowed Playwright page, stored privately. The narrowing (`PwPage` =
111
+ * `BasePagePage`) is what lets the unit-test `FakePage` double satisfy the
112
+ * constructor without stubbing ~250 `Page` members; it never escapes this
113
+ * class. Subclasses (generated and hand-written POMs) reach the page through
114
+ * the widened {@link BasePage.page} getter, which surfaces Playwright's full
115
+ * `Page` so custom POMs can use `getByRole`/`waitForResponse`/`waitForFunction`
116
+ * etc. for JS/DOM elements the generator can't key.
117
+ */
118
+ private readonly _page: PwPage;
119
+
120
+ /**
121
+ * Playwright's full `Page`, exposed to subclasses. This is the single,
122
+ * sanctioned way generated/custom POMs touch the page — there is no separate
123
+ * `rawPage`. The narrowed storage (`_page`) is widened here; the value is a
124
+ * real `Page` at runtime.
125
+ */
126
+ protected get page(): Page {
127
+ return this._page as unknown as Page;
128
+ }
129
+
130
+ /**
131
+ * @param page - Playwright page object (narrowed `PwPage` so test doubles fit).
109
132
  */
110
- public constructor(protected page: PwPage, options?: BasePageOptions) {
133
+ public constructor(page: PwPage, options?: BasePageOptions) {
134
+ this._page = page;
111
135
  this.testIdAttribute = (options?.testIdAttribute || "data-testid").trim() || "data-testid";
112
136
 
113
137
  const pointerRenderer = options?.renderers?.pointer;
114
- this.callout = new Callout(this.page, {
138
+ this.callout = new Callout(this._page, {
115
139
  extraOverlayIds: pointerRenderer?.overlayIds,
116
140
  renderer: options?.renderers?.callout,
117
141
  });
118
- this.pointer = new Pointer(this.page, this.testIdAttribute, this.callout, pointerRenderer);
142
+ this.pointer = new Pointer(this._page, this.testIdAttribute, this.callout, pointerRenderer);
119
143
  }
120
144
 
121
- public get screencast(): PwPage["screencast"] {
145
+ public get screencast(): Page["screencast"] {
122
146
  return this.page.screencast;
123
147
  }
124
148
 
@@ -232,12 +256,12 @@ export class BasePage {
232
256
  return `[${this.testIdAttribute}="${testId}"]`;
233
257
  }
234
258
 
235
- protected describeLocator(locator: PwLocator, description?: string): PwLocator {
259
+ protected describeLocator(locator: Locator, description?: string): Locator {
236
260
  const normalizedDescription = description?.trim();
237
261
  return normalizedDescription ? locator.describe(normalizedDescription) : locator;
238
262
  }
239
263
 
240
- protected locatorByTestId(testId: string, description?: string): PwLocator {
264
+ protected locatorByTestId(testId: string, description?: string): Locator {
241
265
  return this.describeLocator(this.page.locator(this.selectorForTestId(testId)), description);
242
266
  }
243
267
 
@@ -245,7 +269,7 @@ export class BasePage {
245
269
  rootTestId: string,
246
270
  label: string,
247
271
  options?: { exact?: boolean; description?: string },
248
- ): PwLocator {
272
+ ): Locator {
249
273
  const locator = this.locatorByTestId(rootTestId).getByLabel(label, { exact: options?.exact ?? true });
250
274
  return this.describeLocator(locator, options?.description);
251
275
  }
@@ -282,7 +306,7 @@ export class BasePage {
282
306
  * ergonomic accessors like:
283
307
  * expect(page.SaveButton["MyKey"]).toBeVisible();
284
308
  */
285
- protected keyedLocators<TKey extends string>(getLocator: (key: TKey) => PwLocator): Record<TKey, PwLocator> {
309
+ protected keyedLocators<TKey extends string>(getLocator: (key: TKey) => PwLocator): Record<TKey, Locator> {
286
310
  const handler: ProxyHandler<object> = {
287
311
  get: (_t, prop) => {
288
312
  // Avoid confusing Promise-like detection and ignore symbols.
@@ -293,7 +317,10 @@ export class BasePage {
293
317
  },
294
318
  };
295
319
 
296
- return new Proxy({}, handler) as Record<TKey, PwLocator>;
320
+ // `getLocator` returns the narrowed `PwLocator` (so test doubles satisfy it), but each
321
+ // value is a real Playwright `Locator` at runtime. Widen the record's value type so
322
+ // generated keyed accessors can be passed to `expect(...)`.
323
+ return new Proxy({}, handler) as unknown as Record<TKey, Locator>;
297
324
  }
298
325
 
299
326
  public async getObjectId(options?: { timeoutMs?: number }): Promise<ObjectId> {
@@ -28,7 +28,7 @@ import {
28
28
  type PomStringPattern,
29
29
  } from "../pom-patterns";
30
30
  import { buildPomLocatorDescription, stripPomActionPrefix } from "../pom-discoverability";
31
- import { introspectNuxtPages, parseRouterFileFromCwd } from "../router-introspection";
31
+ import { getParamToken, introspectNuxtPages, parseRouterFileFromCwd } from "../router-introspection";
32
32
  import {
33
33
  addExportAll,
34
34
  addNamedImport,
@@ -108,8 +108,23 @@ function resolveRouterEntry(projectRoot?: string, routerEntry?: string) {
108
108
  return path.isAbsolute(routerEntry) ? routerEntry : path.resolve(root, routerEntry);
109
109
  }
110
110
 
111
+ interface RouteParamMeta {
112
+ name: string;
113
+ optional: boolean;
114
+ }
115
+
116
+ interface RouteEntry {
117
+ /** Vue Router route `name`, when declared. Enables runtime `router.push({ name, params })`. */
118
+ name: string | null;
119
+ template: string;
120
+ params: RouteParamMeta[];
121
+ }
122
+
111
123
  interface RouteMeta {
124
+ /** Shortest route template — used for the static `route` property. */
112
125
  template: string;
126
+ /** Every route that renders this component (name + template + declared params). */
127
+ routes: RouteEntry[];
113
128
  }
114
129
 
115
130
  type CustomPomMethodSignatureMap = Map<string, PomMethodSignature>;
@@ -277,27 +292,40 @@ async function getRouteMetaByComponent(
277
292
  },
278
293
  });
279
294
 
280
- const map = new Map<string, RouteMeta[]>();
295
+ const map = new Map<string, RouteEntry[]>();
281
296
  for (const entry of routeMetaEntries) {
282
297
  const list = map.get(entry.componentName) ?? [];
283
- list.push({ template: entry.pathTemplate });
298
+ list.push({ name: entry.name, template: entry.pathTemplate, params: entry.params });
284
299
  map.set(entry.componentName, list);
285
300
  }
286
301
 
287
- const chooseRouteMeta = (entries: RouteMeta[]): RouteMeta | null => {
302
+ const dedupeRoutes = (entries: RouteEntry[]): RouteEntry[] => {
303
+ const seen = new Set<string>();
304
+ const unique: RouteEntry[] = [];
305
+ for (const entry of entries) {
306
+ if (seen.has(entry.template))
307
+ continue;
308
+ seen.add(entry.template);
309
+ unique.push(entry);
310
+ }
311
+ return unique;
312
+ };
313
+
314
+ const choosePrimaryTemplate = (entries: RouteEntry[]): string | null => {
288
315
  if (!entries.length)
289
316
  return null;
290
317
  return entries
291
318
  .slice()
292
- .sort((a, b) => a.template.length - b.template.length || a.template.localeCompare(b.template))[0];
319
+ .sort((a, b) => a.template.length - b.template.length || a.template.localeCompare(b.template))[0].template;
293
320
  };
294
321
 
295
322
  const sorted = Array.from(map.entries()).sort((a, b) => a[0].localeCompare(b[0]));
296
323
  return Object.fromEntries(
297
324
  sorted
298
- .map(([componentName, entries]) => {
299
- const chosen = chooseRouteMeta(entries);
300
- return chosen ? [componentName, chosen] : null;
325
+ .map(([componentName, rawEntries]) => {
326
+ const routes = dedupeRoutes(rawEntries);
327
+ const primaryTemplate = choosePrimaryTemplate(routes);
328
+ return primaryTemplate ? [componentName, { template: primaryTemplate, routes }] : null;
301
329
  })
302
330
  .filter((entry): entry is [string, RouteMeta] => !!entry),
303
331
  );
@@ -317,28 +345,208 @@ function generateRouteProperty(routeMeta: RouteMeta | null): TypeScriptClassMemb
317
345
  ];
318
346
  }
319
347
 
320
- function generateGoToSelfMethod(componentName: string): TypeScriptClassMember[] {
348
+ function buildParamTypeString(params: RouteParamMeta[]): string {
349
+ return `{ ${params.map(p => `${p.name}${p.optional ? "?" : ""}: string | number`).join("; ")} }`;
350
+ }
351
+
352
+ function chooseParamlessRoute(routes: RouteEntry[]): RouteEntry | null {
353
+ const paramless = routes.filter(r => r.params.length === 0);
354
+ if (!paramless.length)
355
+ return null;
356
+ return paramless
357
+ .slice()
358
+ .sort((a, b) => a.template.length - b.template.length || a.template.localeCompare(b.template))[0];
359
+ }
360
+
361
+ function chooseParametrizedRoute(routes: RouteEntry[]): RouteEntry | null {
362
+ const parametrized = routes.filter(r => r.params.length > 0);
363
+ if (!parametrized.length)
364
+ return null;
365
+ return parametrized
366
+ .slice()
367
+ .sort((a, b) => a.params.length - b.params.length || a.template.length - b.template.length || a.template.localeCompare(b.template))[0];
368
+ }
369
+
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 `window`/`globalThis` key the consumer exposes the live Vue Router instance under
379
+ * (dev-gated), so generated `goTo()` can drive `router.push({ name, params })` instead of
380
+ * reconstructing URLs from opaque path-template tokens. The consumer is responsible for
381
+ * installing `globalThis[ROUTER_GLOBAL_NAME] = router` in test/dev builds.
382
+ */
383
+ const ROUTER_GLOBAL_NAME = "__appRouter";
384
+
385
+ /**
386
+ * Emits the router-driven `goTo()` body for a named route. Two regimes:
387
+ *
388
+ * - **Cold page** (fresh Playwright page on `about:blank` — the SPA hasn't booted, so the
389
+ * router global is `undefined`): boot the app with a cheap `page.goto("/")`, wait for the
390
+ * router to install, then **full-load the resolved target URL** (`router.resolve({ name,
391
+ * params }).href` + `page.goto`). A full load is unavoidable here — you cannot `push`
392
+ * before the router exists — and resolving the target (rather than stopping at "/") means
393
+ * the route's component mounts via a stable page load, exactly as the original
394
+ * `page.goto`-based tests did. This matters because the POM runtime clicks with
395
+ * `force: true` (skipping Playwright's actionability check): a SPA `push` into a freshly
396
+ * mounted view can resolve before radios/inputs are interactive, so a force-click fired
397
+ * the instant the push resolves can miss (the control's handler isn't attached yet). A
398
+ * full load gives a fully-rendered, interactive page.
399
+ * - **Warm page** (the app is already mounted — any later `goTo()` in the same test): the
400
+ * guard is a single cheap `evaluate` that finds the router present, so the navigation is a
401
+ * pure SPA `router.push({ name, params })` — no reload — the intended fast path.
402
+ *
403
+ * `routeNameExpr` is a TS expression yielding the route name (a string literal for single
404
+ * routes, or `params ? "edit" : "new"` for the dual-route overload). `paramsExpr` is the
405
+ * params source (`"undefined"` for a paramless route, `"params"` otherwise); `nullable` is
406
+ * true only when that source may itself be `undefined` (the all-optional-params overload),
407
+ * gating the `?? {}` guard that TS2871 would otherwise flag on a required param.
408
+ */
409
+ const pushBlock = (routeNameExpr: string, paramsExpr: string, nullable: boolean): string[] => {
410
+ 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 } } }`;
411
+ const routeParamsLine = paramsExpr === "undefined"
412
+ ? "const routeParams = {};"
413
+ : nullable
414
+ ? `const routeParams = Object.fromEntries(Object.entries(${paramsExpr} ?? {}).filter(([, v]) => v !== undefined));`
415
+ : `const routeParams = Object.fromEntries(Object.entries(${paramsExpr}).filter(([, v]) => v !== undefined));`;
416
+ return [
417
+ routeParamsLine,
418
+ `const isCold = await this.page.evaluate(() => typeof (globalThis as { ${ROUTER_GLOBAL_NAME}?: unknown }).${ROUTER_GLOBAL_NAME} === "undefined");`,
419
+ `if (isCold) {`,
420
+ ` await this.page.goto("/", { waitUntil: "commit" });`,
421
+ ` await this.page.waitForFunction(() => typeof (globalThis as { ${ROUTER_GLOBAL_NAME}?: unknown }).${ROUTER_GLOBAL_NAME} !== "undefined", { timeout: 15000 });`,
422
+ ` const href = await this.page.evaluate(({ name, params }) => (globalThis as ${routerType}).${ROUTER_GLOBAL_NAME}?.resolve({ name, params })?.href, { name: ${routeNameExpr}, params: routeParams });`,
423
+ ` if (href) { await this.page.goto(href, { waitUntil: "domcontentloaded" }); }`,
424
+ `} else {`,
425
+ ` await this.page.evaluate(async ({ name, params }) => {`,
426
+ ` await (globalThis as ${routerType}).${ROUTER_GLOBAL_NAME}?.push({ name, params });`,
427
+ ` }, { name: ${routeNameExpr}, params: routeParams });`,
428
+ `}`,
429
+ ];
430
+ };
431
+
432
+ function generateGoToMethod(componentName: string, routeMeta: RouteMeta | null): TypeScriptClassMember[] {
433
+ // No route metadata: emit a goTo() that fails loudly when invoked.
434
+ if (!routeMeta) {
435
+ return [
436
+ createClassMethod({
437
+ name: "goTo",
438
+ isAsync: true,
439
+ statements: [
440
+ `throw new Error("[pom] No router path found for component/page-object '${componentName}'.");`,
441
+ ],
442
+ }),
443
+ ];
444
+ }
445
+
446
+ const paramless = chooseParamlessRoute(routeMeta.routes);
447
+ const parametrized = chooseParametrizedRoute(routeMeta.routes);
448
+ const hasParamless = paramless !== null;
449
+ const hasParametrized = parametrized !== null;
450
+
451
+ // Neither a paramless nor a parametrized route (shouldn't happen — routeMeta is non-null — but guard anyway).
452
+ if (!hasParamless && !hasParametrized) {
453
+ return [
454
+ createClassMethod({
455
+ name: "goTo",
456
+ isAsync: true,
457
+ statements: [
458
+ `throw new Error("[pom] No router path found for component/page-object '${componentName}'.");`,
459
+ ],
460
+ }),
461
+ ];
462
+ }
463
+
464
+ // Fallback (unnamed routes, e.g. Nuxt file-based routes whose names the static walk
465
+ // cannot recover): reconstruct the URL from the tokenized template and `page.goto` it.
466
+ const paramStatements = (entry: RouteEntry): string[] => {
467
+ const lines: string[] = [];
468
+ for (const param of entry.params) {
469
+ const token = getParamToken(param.name);
470
+ if (param.optional) {
471
+ // An omitted optional param drops its entire path segment (including the leading "/"),
472
+ // so `/persons/:personId/:tabName?` with tabName omitted resolves to `/persons/123`.
473
+ lines.push(`targetUrl = params.${param.name} === undefined ? targetUrl.replaceAll(${JSON.stringify(`/${token}`)}, "") : targetUrl.replaceAll(${JSON.stringify(token)}, String(params.${param.name}));`);
474
+ }
475
+ else {
476
+ lines.push(`targetUrl = targetUrl.replaceAll(${JSON.stringify(token)}, String(params.${param.name}));`);
477
+ }
478
+ }
479
+ return lines;
480
+ };
481
+
482
+ // Preferred path: the route is named, so hand the param object straight to the runtime
483
+ // router. `undefined` values are stripped first — omitted optional params are simply not
484
+ // passed, and the router builds the URL (handling optional segments, redirects, and param
485
+ // coercion) itself. No opaque tokens, no string substitution. See `pushBlock` for the
486
+ // cold-start (full-load resolved target) vs warm (SPA `router.push`) regimes.
487
+ // Paramless-only: simple no-arg goTo().
488
+ if (hasParamless && !hasParametrized) {
489
+ const route = paramless!;
490
+ return [
491
+ createClassMethod({
492
+ name: "goTo",
493
+ isAsync: true,
494
+ statements: route.name !== null
495
+ ? pushBlock(JSON.stringify(route.name), "undefined", false)
496
+ : [`const targetUrl = ${JSON.stringify(route.template)};`, ...GOTO_RUNTIME_LINES],
497
+ }),
498
+ ];
499
+ }
500
+
501
+ const paramType = buildParamTypeString(parametrized!.params);
502
+
503
+ // Parametrized-only: goTo(params). When every declared param is optional, the params
504
+ // object itself is optional too — `goTo()` is a valid call that navigates to the route
505
+ // with all optional params omitted (e.g. `/preferences/:tabName?` -> `/preferences`).
506
+ if (hasParametrized && !hasParamless) {
507
+ const route = parametrized!;
508
+ const allOptional = route.params.every(p => p.optional);
509
+ return [
510
+ createClassMethod({
511
+ name: "goTo",
512
+ isAsync: true,
513
+ parameters: [{ name: "params", type: paramType, hasQuestionToken: allOptional }],
514
+ statements: route.name !== null
515
+ ? pushBlock(JSON.stringify(route.name), "params", allOptional)
516
+ : [`let targetUrl = ${JSON.stringify(route.template)};`, ...paramStatements(route), ...GOTO_RUNTIME_LINES],
517
+ }),
518
+ ];
519
+ }
520
+
521
+ // Both routes present. Use the runtime router only when both chosen routes are named;
522
+ // otherwise fall back to token reconstruction for consistency across the overloads.
523
+ const paramlessRoute = paramless!;
524
+ const parametrizedRoute = parametrized!;
525
+ const usePush = paramlessRoute.name !== null && parametrizedRoute.name !== null;
526
+
321
527
  return [
322
528
  createClassMethod({
323
529
  name: "goTo",
324
530
  isAsync: true,
325
- statements: [
326
- "await this.goToSelf();",
327
- ],
328
- }),
329
- createClassMethod({
330
- name: "goToSelf",
331
- isAsync: true,
332
- statements: [
333
- `const route = ${componentName}.route;`,
334
- "if (!route) {",
335
- ` throw new Error("[pom] No router path found for component/page-object '${componentName}'.");`,
336
- "}",
337
- "const runtimeEnv = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;",
338
- "const runtimeBaseUrl = runtimeEnv?.PLAYWRIGHT_RUNTIME_BASE_URL ?? runtimeEnv?.PLAYWRIGHT_TEST_BASE_URL ?? runtimeEnv?.VITE_PLAYWRIGHT_BASE_URL;",
339
- "const targetUrl = runtimeBaseUrl ? new URL(route.template, runtimeBaseUrl).toString() : route.template;",
340
- "await this.page.goto(targetUrl);",
531
+ overloads: [
532
+ { parameters: [], returnType: "Promise<void>" },
533
+ { parameters: [{ name: "params", type: paramType }], returnType: "Promise<void>" },
341
534
  ],
535
+ parameters: [{ name: "params", type: paramType, hasQuestionToken: true }],
536
+ statements: usePush
537
+ ? pushBlock(
538
+ `params ? ${JSON.stringify(parametrizedRoute.name)} : ${JSON.stringify(paramlessRoute.name)}`,
539
+ "params",
540
+ true,
541
+ )
542
+ : [
543
+ `const template = params ? ${JSON.stringify(parametrizedRoute.template)} : ${JSON.stringify(paramlessRoute.template)};`,
544
+ "let targetUrl = template;",
545
+ `if (params) {`,
546
+ ...paramStatements(parametrizedRoute).map(line => ` ${line}`),
547
+ "}",
548
+ ...GOTO_RUNTIME_LINES,
549
+ ],
342
550
  }),
343
551
  ];
344
552
  }
@@ -1795,7 +2003,7 @@ function prepareViewObjectModelClass(
1795
2003
  if (isView && options.vueRouterFluentChaining) {
1796
2004
  const routeMeta = options.routeMetaByComponent?.[componentName] ?? null;
1797
2005
  members.push(...generateRouteProperty(routeMeta));
1798
- members.push(...generateGoToSelfMethod(className));
2006
+ members.push(...generateGoToMethod(className, routeMeta));
1799
2007
  }
1800
2008
 
1801
2009
  members.push(...generateMethodsContentForDependencies(componentName, dependencies));
@@ -1832,6 +2040,11 @@ function generateViewObjectModelContent(
1832
2040
  const basePageImport = path.relative(fromAbs, toAbs).replace(/\\/g, "/");
1833
2041
  const basePageImportNoExt = stripExtension(basePageImport).replace(/\\/g, "/");
1834
2042
  const basePageImportSpecifier = basePageImportNoExt.startsWith(".") ? basePageImportNoExt : `./${basePageImportNoExt}`;
2043
+ // Generated POM constructors take Playwright's full `Page` (not the narrowed `PwPage`):
2044
+ // `BasePage` widens `page` to the full `Page` for subclasses, so generated POMs construct
2045
+ // each other with `new Child(this.page)` where `this.page` is `Page`. Importing the
2046
+ // standard `Page` from `@playwright/test` keeps the narrowed types internal to the vendored
2047
+ // runtime — they never surface in generated output.
1835
2048
  const needsPlaywrightPageImport = prepared.isView
1836
2049
  || prepared.attachmentsForThisClass.length > 0
1837
2050
  || prepared.componentRefsForInstances.size > 0
@@ -2240,6 +2453,8 @@ function renderSplitStubPomContent(options: {
2240
2453
  });
2241
2454
 
2242
2455
  return renderSourceFile(`${options.className}.ts`, (sourceFile) => {
2456
+ // Stub ctors take Playwright's full `Page` (aliased `PwPage`), matching non-stub generated
2457
+ // POMs — stubs are constructed with `new Stub(this.page)` where `this.page` is `Page`.
2243
2458
  addNamedImport(sourceFile, {
2244
2459
  moduleSpecifier: "@playwright/test",
2245
2460
  isTypeOnly: true,
@@ -2953,11 +3168,14 @@ function getConstructor(
2953
3168
  writer.writeLine(`super(page, { testIdAttribute: ${JSON.stringify(attr)} });`);
2954
3169
 
2955
3170
  for (const a of attachmentsForThisView) {
2956
- writer.writeLine(`this.${a.propertyName} = new ${a.className}(page, this);`);
3171
+ // Hand-written (custom) POMs are declared against Playwright's full `Page`.
3172
+ // `this.page` already surfaces the full `Page` (BasePage widens it for
3173
+ // subclasses), so pass it straight through — no separate raw-page accessor.
3174
+ writer.writeLine(`this.${a.propertyName} = new ${a.className}(this.page, this);`);
2957
3175
  }
2958
3176
 
2959
3177
  for (const w of widgetInstances) {
2960
- writer.writeLine(`this.${w.propertyName} = new ${w.className}(page, ${JSON.stringify(w.testId)});`);
3178
+ writer.writeLine(`this.${w.propertyName} = new ${w.className}(this.page, ${JSON.stringify(w.testId)});`);
2961
3179
  }
2962
3180
 
2963
3181
  childrenComponent.forEach((child) => {
@@ -1,4 +1,5 @@
1
- import type { Keyboard, Response, Screencast } from "playwright";
1
+ import type { Keyboard, Locator, Response, Screencast } from "playwright";
2
+
2
3
 
3
4
  /**
4
5
  * Narrow subset of the Playwright {@link Locator} surface that the generated
@@ -113,8 +114,15 @@ export type PwPage = BasePagePage;
113
114
 
114
115
  /**
115
116
  * Locator type used by the generated POM runtime. Narrowed from Playwright's
116
- * full `Locator` to {@link BasePageLocator}. A real `Locator` is still
117
- * assignable.
117
+ * full `Locator` to {@link BasePageLocator} so test doubles can satisfy it
118
+ * without stubbing ~70 members. A real `Locator` is still assignable.
119
+ *
120
+ * Note: this narrowed type is used for the runtime's *internal* parameters
121
+ * (what doubles must satisfy). The locator-*returning* accessors
122
+ * (`locatorByTestId`, `keyedLocators`, …) widen back to Playwright's full
123
+ * `Locator` at the boundary so generated accessors can be passed straight to
124
+ * `expect(...)` (`expect(page.SaveButton).toBeVisible()`) — Playwright's
125
+ * `LocatorAssertions` matchers are keyed on `Locator`.
118
126
  */
119
127
  export type PwLocator = BasePageLocator;
120
128
 
@@ -1,3 +1,4 @@
1
+ import type { Locator, Page } from "playwright";
1
2
  import type { PwLocator, PwPage } from "./playwright-types";
2
3
  import type { CalloutRenderer } from "./callout";
3
4
  import { type AfterPointerClick, type PointerRenderer } from "./pointer";
@@ -41,23 +42,39 @@ export declare class ObjectId {
41
42
  * for all component-specific Page Object Models
42
43
  */
43
44
  export declare class BasePage {
44
- protected page: PwPage;
45
45
  protected readonly testIdAttribute: string;
46
46
  private readonly callout;
47
47
  private readonly pointer;
48
48
  /**
49
- * @param {Page} page - Playwright page object
49
+ * The narrowed Playwright page, stored privately. The narrowing (`PwPage` =
50
+ * `BasePagePage`) is what lets the unit-test `FakePage` double satisfy the
51
+ * constructor without stubbing ~250 `Page` members; it never escapes this
52
+ * class. Subclasses (generated and hand-written POMs) reach the page through
53
+ * the widened {@link BasePage.page} getter, which surfaces Playwright's full
54
+ * `Page` so custom POMs can use `getByRole`/`waitForResponse`/`waitForFunction`
55
+ * etc. for JS/DOM elements the generator can't key.
56
+ */
57
+ private readonly _page;
58
+ /**
59
+ * Playwright's full `Page`, exposed to subclasses. This is the single,
60
+ * sanctioned way generated/custom POMs touch the page — there is no separate
61
+ * `rawPage`. The narrowed storage (`_page`) is widened here; the value is a
62
+ * real `Page` at runtime.
63
+ */
64
+ protected get page(): Page;
65
+ /**
66
+ * @param page - Playwright page object (narrowed `PwPage` so test doubles fit).
50
67
  */
51
68
  constructor(page: PwPage, options?: BasePageOptions);
52
- get screencast(): PwPage["screencast"];
69
+ get screencast(): Page["screencast"];
53
70
  private waitForTestIdClickEventAfter;
54
71
  protected selectorForTestId(testId: string): string;
55
- protected describeLocator(locator: PwLocator, description?: string): PwLocator;
56
- protected locatorByTestId(testId: string, description?: string): PwLocator;
72
+ protected describeLocator(locator: Locator, description?: string): Locator;
73
+ protected locatorByTestId(testId: string, description?: string): Locator;
57
74
  protected locatorWithinTestIdByLabel(rootTestId: string, label: string, options?: {
58
75
  exact?: boolean;
59
76
  description?: string;
60
- }): PwLocator;
77
+ }): Locator;
61
78
  /**
62
79
  * Animates the pointer to an element.
63
80
  */
@@ -72,7 +89,7 @@ export declare class BasePage {
72
89
  * ergonomic accessors like:
73
90
  * expect(page.SaveButton["MyKey"]).toBeVisible();
74
91
  */
75
- protected keyedLocators<TKey extends string>(getLocator: (key: TKey) => PwLocator): Record<TKey, PwLocator>;
92
+ protected keyedLocators<TKey extends string>(getLocator: (key: TKey) => PwLocator): Record<TKey, Locator>;
76
93
  getObjectId(options?: {
77
94
  timeoutMs?: number;
78
95
  }): Promise<ObjectId>;