@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 +48 -52
- package/class-generation/base-page.ts +37 -10
- package/class-generation/index.ts +246 -28
- package/class-generation/playwright-types.ts +11 -3
- package/dist/class-generation/base-page.d.ts +24 -7
- package/dist/class-generation/base-page.d.ts.map +1 -1
- package/dist/class-generation/index.d.ts +13 -0
- package/dist/class-generation/index.d.ts.map +1 -1
- package/dist/class-generation/playwright-types.d.ts +9 -2
- package/dist/class-generation/playwright-types.d.ts.map +1 -1
- package/dist/eslint/index.cjs +16 -3
- package/dist/eslint/index.cjs.map +1 -1
- package/dist/eslint/index.mjs +16 -3
- package/dist/eslint/index.mjs.map +1 -1
- package/dist/eslint/no-raw-playwright-apis.d.ts.map +1 -1
- package/dist/index.cjs +145 -25
- package/dist/index.cjs.map +1 -1
- package/dist/index.mjs +145 -25
- package/dist/index.mjs.map +1 -1
- package/dist/router-introspection.d.ts +5 -0
- package/dist/router-introspection.d.ts.map +1 -1
- package/package.json +1 -1
package/RELEASE_NOTES.md
CHANGED
|
@@ -1,72 +1,68 @@
|
|
|
1
|
-
I'll
|
|
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
|
|
4
|
+
Good - the compare range confirms only one commit (#52). Let me get the PR details for the release
|
|
5
|
+
window.
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
Let me try a different approach to get PR merge timestamps.
|
|
6
8
|
|
|
7
|
-
|
|
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
|
-
|
|
10
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
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
|
-
|
|
54
|
+
Tests
|
|
57
55
|
|
|
58
|
-
-
|
|
59
|
-
|
|
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-
|
|
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
|
-
|
|
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
|
-
*
|
|
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(
|
|
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.
|
|
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.
|
|
142
|
+
this.pointer = new Pointer(this._page, this.testIdAttribute, this.callout, pointerRenderer);
|
|
119
143
|
}
|
|
120
144
|
|
|
121
|
-
public get 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:
|
|
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):
|
|
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
|
-
):
|
|
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,
|
|
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
|
-
|
|
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,
|
|
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
|
|
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,
|
|
299
|
-
const
|
|
300
|
-
|
|
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
|
|
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
|
-
|
|
326
|
-
"
|
|
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(...
|
|
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
|
-
|
|
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}
|
|
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
|
-
*
|
|
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():
|
|
69
|
+
get screencast(): Page["screencast"];
|
|
53
70
|
private waitForTestIdClickEventAfter;
|
|
54
71
|
protected selectorForTestId(testId: string): string;
|
|
55
|
-
protected describeLocator(locator:
|
|
56
|
-
protected locatorByTestId(testId: string, description?: string):
|
|
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
|
-
}):
|
|
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,
|
|
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>;
|