@immense/vue-pom-generator 1.0.91 → 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 +60 -2
  2. package/RELEASE_NOTES.md +105 -22
  3. package/class-generation/base-page.ts +141 -59
  4. package/class-generation/diagnostics.ts +559 -0
  5. package/class-generation/index.ts +123 -21
  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 +3 -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 +419 -298
  25. package/dist/index.cjs.map +1 -1
  26. package/dist/index.mjs +419 -298
  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 +3 -1
  43. package/dist/route-navigation-codegen.d.ts.map +1 -1
  44. package/dist/router-bridge.d.ts +14 -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
package/README.md CHANGED
@@ -14,6 +14,7 @@ If you already use Playwright with `getByTestId`, the point is simple: this pack
14
14
  - **Generates TypeScript POM output as either one aggregate or split per class, always with a stable `index.ts` barrel.**
15
15
  - **Describes generated Playwright locators** with deterministic human-readable labels via `Locator.describe()`.
16
16
  - **Can generate Playwright fixtures** so tests can request `userListPage` instead of constructing `new UserListPage(page)` manually.
17
+ - **Captures generator-aware failure diagnostics before fixture teardown** and prints the relevant DOM, accessibility tree, browser errors, generated methods, and isolated rerun command to stdout.
17
18
  - **Can fail fast on unnameable wrapper-button actions** so complex inline handlers do not silently degrade into low-signal generated APIs.
18
19
  - **Can emit a single C# POM file** for Playwright .NET consumers.
19
20
  - **Exposes `virtual:testids` and `virtual:pom-manifest`** so your app can inspect collected ids and generated POM metadata at runtime.
@@ -215,6 +216,7 @@ Exports:
215
216
  - `defineVuePomGeneratorConfig()`
216
217
  - `defineNuxtPomGeneratorConfig()`
217
218
  - `@immense/vue-pom-generator/eslint`
219
+ - `@immense/vue-pom-generator/playwright/reporter`
218
220
  - `@immense/vue-pom-generator/router` (browser-safe runtime bridge)
219
221
 
220
222
  ## Basic Vue/Vite setup
@@ -366,6 +368,7 @@ TypeScript output:
366
368
  Optional Playwright fixture output:
367
369
 
368
370
  - `fixtures.g.ts` next to the POMs by default
371
+ - `pom-manifest.g.ts` — a Node-importable map from Vue source/test ids to generated methods
369
372
  - or a custom directory / file path when configured
370
373
 
371
374
  Optional C# output:
@@ -374,6 +377,60 @@ Optional C# output:
374
377
 
375
378
  If you emit outside a `__generated__` path, the generator also manages `.gitattributes` entries for generated files.
376
379
 
380
+ ## Fast, loud Playwright failures
381
+
382
+ Generated fixtures install a failure capture around the browser page. On every unexpected failed attempt, before Playwright destroys the browser context, it captures within one five-second total budget:
383
+
384
+ - the URL and page title
385
+ - rendered generated test ids with visible/hidden and enabled/disabled state
386
+ - the best matching generated POM and its method catalog
387
+ - the most recent generated action and all test-id candidates it expected
388
+ - an accessibility snapshot
389
+ - buffered browser console errors, uncaught page errors, failed requests, and HTTP error responses
390
+ - a screenshot and structured JSON attachment
391
+
392
+ Add the reporter to print this as one bounded, LLM-friendly stdout block. In GitHub Actions, compose Playwright's built-in `github` reporter for canonical line annotations:
393
+
394
+ ```ts
395
+ import { defineConfig } from "@playwright/test";
396
+
397
+ export default defineConfig({
398
+ expect: { timeout: 5_000 },
399
+ reporter: process.env.CI
400
+ ? [
401
+ ["github"],
402
+ ["@immense/vue-pom-generator/playwright/reporter"],
403
+ ]
404
+ : [
405
+ ["list"],
406
+ ["@immense/vue-pom-generator/playwright/reporter"],
407
+ ],
408
+ use: {
409
+ actionTimeout: 5_000,
410
+ navigationTimeout: 5_000,
411
+ trace: "retain-on-first-failure",
412
+ },
413
+ });
414
+ ```
415
+
416
+ The report ends with a file-and-line-targeted command that includes `--max-failures=1`. Method availability is descriptive only: `absent`, `hidden`, or `disabled` can be a valid state for the current page.
417
+
418
+ Animations and presentation delays are disabled by default. Recording/demo projects can opt in through the generated `animation` fixture option; ordinary tests use Playwright's actionability checks without forced clicks. Before clicking, generated actions also await finite CSS animations on the target's ancestor chain (bounded by five seconds). This covers overlays that are visible to Playwright while their component library still suppresses input during an opening transition; infinite decorative animations are ignored.
419
+
420
+ ## Recommended Playwright lint rules
421
+
422
+ The ESLint export composes its generator-specific conventions with `eslint-plugin-playwright`. The flat recommended config treats manual sleeps, `networkidle`, selector waits, forced actions, and non-web-first assertions as errors:
423
+
424
+ ```ts
425
+ import { recommendedPlaywrightConfig } from "@immense/vue-pom-generator/eslint";
426
+
427
+ export default [
428
+ ...recommendedPlaywrightConfig,
429
+ ];
430
+ ```
431
+
432
+ It enables `playwright/no-wait-for-timeout`, `playwright/no-networkidle`, `playwright/no-wait-for-selector`, `playwright/no-force-option`, and `playwright/prefer-web-first-assertions` alongside the generated-POM rules. Presentation waits inside the generator's explicitly enabled animation runtime are not test-authored waits and remain isolated there.
433
+
377
434
  ## Actual Vite dev/build behavior
378
435
 
379
436
  This is important if you are deciding whether the tool will fit into a real codebase.
@@ -438,8 +495,9 @@ goTo(params: { userId: string | number; tab?: string | number }): Promise<void>
438
495
  ```
439
496
 
440
497
  `goTo({ userId: 42, tab: "activity" })` partitions the flat input into Vue Router's
441
- `params` and `query` records. On a cold page it resolves and fully loads the named route;
442
- on a warm page it uses `router.push`.
498
+ `params` and `query` records. On a cold page it boots the application, waits for Vue
499
+ Router's initial navigation to settle, and then uses `router.push`; warm pages use the
500
+ same awaited push without booting again.
443
501
 
444
502
  Important caveats:
445
503
 
package/RELEASE_NOTES.md CHANGED
@@ -1,36 +1,119 @@
1
- Looking at the provided data, the v1.0.90..HEAD range contains only one commit/PR (#53), confirmed
2
- by the diffstat showing 6 files. I'll generate release notes focused on that change.
1
+ I'll verify the actual merged PRs in the release window by querying the repository directly, and
2
+ check the git log between the tags.
3
3
 
4
- v1.0.91
4
+ Let me check the v1.0.91 tag to understand the boundary, and verify the PR merge details.
5
+
6
+ Let me retry those queries.
7
+
8
+ Now I understand the picture. The v1.0.91 tag is at commit #53, so v1.0.92 contains only PR #54. Let
9
+ me examine the key changed files to write accurate release notes.
10
+
11
+ Let me check the diagnostics module and README changes to round out the picture.
12
+
13
+ I now have a complete picture. v1.0.91 was tagged at PR #53's commit, so v1.0.92 contains only PR
14
+ #54. Let me write the release notes.
5
15
 
6
16
  Highlights
7
17
 
8
- - New route-navigation-codegen module generates type-safe Vue Router navigation helpers with
9
- query-parameter awareness
10
- - class-generation refactored to integrate route navigation generation into POM class output
11
- - Router bridge wired to pass route metadata into the navigation codegen
12
- - README updated with documentation for query-aware navigation generation
13
- - New generated-tsc test suite verifies generated navigation code passes TypeScript compilation
18
+ - Fast, actionable Playwright failure diagnostics — generated fixtures now capture the full failure
19
+ state (URL, rendered test IDs, accessibility snapshot, console errors, failed requests, HTTP
20
+ response bodies, active action, and POM method catalog) before the browser context is destroyed,
21
+ within a five-second budget.
22
+ - Bundled Playwright reporter — a new @immense/vue-pom-generator/playwright/reporter subpath prints
23
+ diagnostics as one bounded, LLM-friendly stdout block and emits a structured JSON attachment.
24
+ - Generated POM manifest — a new pom-manifest.g.ts artifact maps Vue source/test IDs to their
25
+ generated methods, consumable at runtime by the diagnostics layer.
26
+ - Composable recommended ESLint config — recommendedPlaywrightConfig composes generator-specific
27
+ rules with eslint-plugin-playwright, banning manual waits, networkidle, selector waits, forced
28
+ actions, and non-web-first assertions.
29
+ - Five-second action failure budget — generated actions now fail fast instead of waiting out
30
+ Playwright's default timeout, and redundant runtime waits have been removed.
31
+ - Finite-animation awareness — generated clicks await finite CSS animations on the target's
32
+ ancestor chain (bounded to five seconds); infinite decorative animations are ignored.
14
33
 
15
34
  Changes
16
35
 
17
- - Route navigation codegen: Added route-navigation-codegen.ts — generates goTo(params)-style
18
- navigation accessors that account for declared route query parameters
19
- - Class generation: Refactored class-generation/index.ts to produce navigation methods alongside
20
- existing POM class members
21
- - Router bridge: Updated router-bridge.ts to expose route metadata needed by the navigation codegen
22
- - Documentation: Updated README.md with details on the new query-aware navigation generation
23
- feature
24
- - Tests: Added tests/generated-tsc.test.ts to assert generated navigation output type-checks;
25
- updated tests/class-generation-coverage.test.ts for new navigation behavior
36
+ Diagnostics & Reporting
37
+
38
+ - Added class-generation/diagnostics.ts — installs a failure-capture wrapper around the browser
39
+ page that gathers URL/title, rendered test IDs with visible/enabled state, the best-matching POM and
40
+ its method catalog, the most recent generated action and expected test-id candidates, an
41
+ accessibility snapshot, buffered console/page errors, failed requests, bounded HTTP failure bodies,
42
+ a screenshot, and a JSON attachment.
43
+ - Added playwright/reporter.ts — a Playwright reporter that reads the diagnostics attachment and
44
+ prints a single bounded stdout block; ends with a file-and-line-targeted rerun command including
45
+ --max-failures=1.
46
+ - Exported a new package subpath @immense/vue-pom-generator/playwright/reporter.
47
+ - Method availability is reported descriptively (absent, hidden, disabled) rather than as errors,
48
+ so conditional UI states remain obvious without false failures.
49
+
50
+ POM Manifest
51
+
52
+ - Added pom-manifest.g.ts — a Node-importable map from Vue source/test IDs to generated methods,
53
+ consumed by the diagnostics layer to report method availability.
54
+ - Introduced manifest types (PomManifest, PomManifestComponent, PomManifestMethod,
55
+ PomManifestEntry) in the diagnostics module.
56
+ - Updated manifest-generator.ts to emit the new manifest artifact alongside existing POM output.
57
+
58
+ ESLint
59
+
60
+ - Added recommendedPlaywrightConfig — a composable flat config that merges
61
+ eslint-plugin-playwright's recommended rules with the generator's own rules.
62
+ - Enabled playwright/no-wait-for-timeout, playwright/no-networkidle,
63
+ playwright/no-wait-for-selector, playwright/no-force-option, and
64
+ playwright/prefer-web-first-assertions as errors.
65
+ - Banned low-level POM action helpers (clickByTestId, clickLocator) via the no-raw-locator-action
66
+ rule.
67
+ - Added scrollIntoViewIfNeeded to the recognized locator-action set.
68
+ - Restructured the plugin export to include a configs record alongside rules.
69
+ - Added eslint-plugin-playwright (^2.11.0) as a runtime dependency.
70
+
71
+ Action & Animation Behavior
72
+
73
+ - Generated actions now fail within a five-second total budget; redundant runtime waits removed.
74
+ - Generated clicks await finite CSS animations on the target's ancestor chain before proceeding,
75
+ bounded to five seconds; infinite decorative animations are ignored.
76
+ - Animations and presentation delays are disabled by default; recording/demo projects opt in via
77
+ the generated animation fixture option.
78
+
79
+ Codegen & Navigation
80
+
81
+ - Centralized router navigation emission in route-navigation-codegen.ts; cold pages now boot the
82
+ application, wait for Vue Router's initial navigation to settle, then use router.push, while warm
83
+ pages use the same awaited push without re-booting.
84
+ - Tightened fragment, wrapper, radio, checkbox, pointer, and transitive-POM codegen behavior
85
+ uncovered by consumer testing.
86
+ - Updated class-generation/base-page.ts, class-generation/index.ts, class-generation/pointer.ts,
87
+ class-generation/playwright-types.ts, method-generation.ts, transform.ts, and router-bridge.ts to
88
+ support the above.
89
+
90
+ Plugin & Build
91
+
92
+ - Updated plugin/internal-plugins.ts, plugin/internal/build-plugin.ts, and
93
+ plugin/internal/dev-plugin.ts for manifest and reporter integration.
94
+ - Updated vite.config.ts and scripts/packed-smoke-check.mjs accordingly.
95
+
96
+ Documentation
97
+
98
+ - Expanded README.md with sections on fast Playwright failures, the bundled reporter, the POM
99
+ manifest, recommended lint rules, and animation handling.
100
+
101
+ Breaking Changes
102
+
103
+ - New peer dependency — @playwright/test (>=1.61.0 <2) is now a required peer dependency.
104
+ - Five-second action budget — generated actions fail within five seconds instead of relying on
105
+ Playwright's default timeout; tests depending on longer timeouts will fail sooner.
106
+ - Animations disabled by default — presentation delays are off unless explicitly opted in via the
107
+ generated animation fixture option.
26
108
 
27
109
  Pull Requests Included
28
110
 
29
- - #53 Support query-aware generated navigation
30
- (]8;id=md-1gwtg7u;https://github.com/immense/vue-pom-generator/pull/53https://github.com/immense/vue-pom-generator/pull/53]8;;]8;;)]8;;
111
+ - ]8;id=md-1fivfqz;https://github.com/immense/vue-pom-generator/pull/54#54 — Add fast, actionable Playwright diagnostics]8;;]8;; (@dkattan)]8;;
31
112
 
32
113
  Testing
33
114
 
34
- - Added generated-tsc.test.ts for TypeScript compilation validation of generated navigation code;
35
- updated class-generation-coverage.test.ts to cover new navigation generation behavior.
115
+ Validated per the PR: npm test (401 passed), npm run typecheck, npm run lint, npm run smoke:pack,
116
+ and a full Immy Aspire-backed Playwright suite with --max-failures=1 (passed in 4m37s). New test
117
+ suites added for diagnostics (tests/playwright-diagnostics.test.ts) and the reporter
118
+ (tests/playwright-reporter.test.ts), plus tests/method-generation.test.ts.
36
119
 
@@ -7,6 +7,23 @@ import { Callout } from "./callout";
7
7
  import type { CalloutRenderer } from "./callout";
8
8
  import { Pointer, type AfterPointerClick, type AfterPointerClickInfo, type PointerRenderer } from "./pointer";
9
9
 
10
+ const POM_ACTIVE_ACTION_REGISTRY = Symbol.for("@immense/vue-pom-generator.active-action-registry");
11
+
12
+ interface PomActiveActionRecord {
13
+ componentName?: string;
14
+ methodName: string;
15
+ expectedTestIds: readonly string[];
16
+ }
17
+
18
+ function setPomAction(page: object, action: PomActiveActionRecord): void {
19
+ const globalRecord = globalThis as typeof globalThis & {
20
+ [POM_ACTIVE_ACTION_REGISTRY]?: WeakMap<object, PomActiveActionRecord>;
21
+ };
22
+ const registry = globalRecord[POM_ACTIVE_ACTION_REGISTRY] ?? new WeakMap<object, PomActiveActionRecord>();
23
+ globalRecord[POM_ACTIVE_ACTION_REGISTRY] = registry;
24
+ registry.set(page, { ...action, expectedTestIds: [...action.expectedTestIds] });
25
+ }
26
+
10
27
  // Click instrumentation is optional for generated POMs.
11
28
  //
12
29
  // When enabled, POM click/fill helpers will wait for the app to emit
@@ -124,7 +141,7 @@ export class BasePage {
124
141
  * real `Page` at runtime.
125
142
  */
126
143
  protected get page(): Page {
127
- return this._page as unknown as Page;
144
+ return this._page as Page;
128
145
  }
129
146
 
130
147
  /**
@@ -252,6 +269,15 @@ export class BasePage {
252
269
  }
253
270
  }
254
271
 
272
+ private getAfterPointerClick(wait: boolean = true): AfterPointerClick | undefined {
273
+ if (!REQUIRE_CLICK_EVENT || !wait) return undefined;
274
+
275
+ return async ({ testId, instrumented }: AfterPointerClickInfo) => {
276
+ if (!testId || !instrumented) return;
277
+ await this.waitForTestIdClickEventAfter(testId);
278
+ };
279
+ }
280
+
255
281
  protected selectorForTestId(testId: string): string {
256
282
  return `[${this.testIdAttribute}="${testId}"]`;
257
283
  }
@@ -265,12 +291,55 @@ export class BasePage {
265
291
  return this.describeLocator(this.page.locator(this.selectorForTestId(testId)), description);
266
292
  }
267
293
 
294
+ protected async resolveVisibleTestIdLocator(
295
+ testIds: readonly string[],
296
+ description: string,
297
+ methodName: string,
298
+ componentName?: string,
299
+ ): Promise<Locator> {
300
+ this.recordPomAction(componentName, methodName, testIds);
301
+ const locators = testIds.map(testId => this.locatorByTestId(testId, description));
302
+ if (!locators.length) {
303
+ throw new Error(`[pom] ${methodName} has no candidate test ids.`);
304
+ }
305
+
306
+ try {
307
+ await Promise.any(locators.map(locator => locator.waitFor({ state: "visible", timeout: 5_000 })));
308
+ }
309
+ catch (error) {
310
+ throw new Error(
311
+ `[pom] ${methodName} could not find a visible element for any generated test id: ${testIds.join(", ")}`,
312
+ { cause: error },
313
+ );
314
+ }
315
+
316
+ for (const locator of locators) {
317
+ if (await locator.isVisible()) return locator;
318
+ }
319
+ return locators[0]!;
320
+ }
321
+
322
+ protected recordPomAction(
323
+ componentName: string | undefined,
324
+ methodName: string,
325
+ expectedTestIds: readonly string[],
326
+ ): void {
327
+ setPomAction(this.page, { componentName, methodName, expectedTestIds });
328
+ }
329
+
268
330
  protected locatorWithinTestIdByLabel(
269
331
  rootTestId: string,
270
332
  label: string,
271
333
  options?: { exact?: boolean; description?: string },
272
334
  ): Locator {
273
- const locator = this.locatorByTestId(rootTestId).getByLabel(label, { exact: options?.exact ?? true });
335
+ // Custom radio controls commonly render an invisible input beneath its visible
336
+ // associated <label>. getByLabel() correctly resolves the input, but clicking it
337
+ // then fails actionability because the label intercepts pointer events. Generated
338
+ // radio actions are user interactions, so click the visible labelled surface.
339
+ const locator = this.locatorByTestId(rootTestId)
340
+ .filter({ visible: true })
341
+ .first()
342
+ .getByText(label, { exact: options?.exact ?? true });
274
343
  return this.describeLocator(locator, options?.description);
275
344
  }
276
345
 
@@ -320,11 +389,11 @@ export class BasePage {
320
389
  // `getLocator` returns the narrowed `PwLocator` (so test doubles satisfy it), but each
321
390
  // value is a real Playwright `Locator` at runtime. Widen the record's value type so
322
391
  // generated keyed accessors can be passed to `expect(...)`.
323
- return new Proxy({}, handler) as unknown as Record<TKey, Locator>;
392
+ return new Proxy({}, handler) as Record<TKey, Locator>;
324
393
  }
325
394
 
326
395
  public async getObjectId(options?: { timeoutMs?: number }): Promise<ObjectId> {
327
- const timeoutMs = options?.timeoutMs ?? 10_000;
396
+ const timeoutMs = options?.timeoutMs ?? 5_000;
328
397
  const deadline = Date.now() + timeoutMs;
329
398
 
330
399
  while (true) {
@@ -529,25 +598,52 @@ export class BasePage {
529
598
  annotationText: string = "",
530
599
  wait: boolean = true,
531
600
  description?: string,
601
+ action?: { componentName?: string; methodName: string; preferAssociatedLabel?: boolean },
532
602
  ): Promise<void> {
533
- const locator = this.locatorByTestId(testId, description);
534
- await this.pointer.animateCursorToElement(locator, true, 200, annotationText, {
535
- afterClick: async ({ testId: clickedTestId, instrumented }: AfterPointerClickInfo) => {
536
- if (!wait) return;
537
- if (!clickedTestId || !instrumented) return;
538
- await this.waitForTestIdClickEventAfter(clickedTestId);
539
- },
540
- });
603
+ this.recordPomAction(action?.componentName, action?.methodName ?? description ?? "clickByTestId", [testId]);
604
+ const locator = this.locatorByTestId(testId, description).filter({ visible: true }).first();
605
+ let clickTarget = locator;
606
+ let activateWithKeyboard = false;
607
+ if (action?.preferAssociatedLabel) {
608
+ const visibleControl = locator;
609
+ const controlId = await visibleControl.getAttribute("id");
610
+ if (controlId) {
611
+ // Bootstrap custom controls often use an empty label whose painted ::before/::after
612
+ // pseudo-elements intercept the pointer. Playwright's visible filter can exclude that
613
+ // empty label even though its pseudo-element is the actual interaction surface, so first
614
+ // select the associated label by DOM presence and then choose pointer or keyboard activation.
615
+ const associatedLabel = this.page.locator(`label[for=${JSON.stringify(controlId)}]`).first();
616
+ if (await associatedLabel.count() > 0) {
617
+ if (await associatedLabel.isVisible()) {
618
+ clickTarget = associatedLabel;
619
+ }
620
+ else {
621
+ // An empty label can have a zero-size element box while its ::before checkbox/radio
622
+ // remains painted over the input. Pointer clicks cannot target either surface without
623
+ // force; Space is the native, actionability-checked keyboard activation for both.
624
+ activateWithKeyboard = true;
625
+ }
626
+ }
627
+ }
628
+ else {
629
+ clickTarget = visibleControl;
630
+ }
631
+ }
632
+ const afterClick = this.getAfterPointerClick(wait);
633
+ if (activateWithKeyboard) {
634
+ await this.pointer.animateCursorToElement(locator, false, 200, annotationText);
635
+ await locator.press("Space");
636
+ if (afterClick) {
637
+ await afterClick({ testId, instrumented: true });
638
+ }
639
+ return;
640
+ }
641
+ await this.pointer.animateCursorToElement(clickTarget, true, 200, annotationText, afterClick ? { afterClick } : undefined);
541
642
  }
542
643
 
543
644
  public async clickLocator(locator: PwLocator, annotationText: string = "", wait: boolean = true): Promise<void> {
544
- await this.pointer.animateCursorToElement(locator, true, 200, annotationText, {
545
- afterClick: async ({ testId: clickedTestId, instrumented }: AfterPointerClickInfo) => {
546
- if (!wait) return;
547
- if (!clickedTestId || !instrumented) return;
548
- await this.waitForTestIdClickEventAfter(clickedTestId);
549
- },
550
- });
645
+ const afterClick = this.getAfterPointerClick(wait);
646
+ await this.pointer.animateCursorToElement(locator, true, 200, annotationText, afterClick ? { afterClick } : undefined);
551
647
  }
552
648
 
553
649
  protected async clickWithinTestIdByLabel(
@@ -555,8 +651,9 @@ export class BasePage {
555
651
  label: string,
556
652
  annotationText: string = "",
557
653
  wait: boolean = true,
558
- options?: { exact?: boolean; description?: string },
654
+ options?: { exact?: boolean; description?: string; componentName?: string; methodName?: string },
559
655
  ): Promise<void> {
656
+ this.recordPomAction(options?.componentName, options?.methodName ?? options?.description ?? "clickWithinTestIdByLabel", [rootTestId]);
560
657
  const locator = this.locatorWithinTestIdByLabel(rootTestId, label, {
561
658
  exact: options?.exact,
562
659
  description: options?.description,
@@ -569,14 +666,12 @@ export class BasePage {
569
666
  text: string,
570
667
  annotationText: string = "",
571
668
  description?: string,
669
+ action?: { componentName?: string; methodName: string },
572
670
  ): Promise<void> {
573
- const locator = this.locatorByTestId(testId, description);
574
- await this.pointer.animateCursorToElementAndClickAndFill(locator, text, true, 200, annotationText, {
575
- afterClick: async ({ testId: clickedTestId, instrumented }: AfterPointerClickInfo) => {
576
- if (!clickedTestId || !instrumented) return;
577
- await this.waitForTestIdClickEventAfter(clickedTestId);
578
- },
579
- });
671
+ this.recordPomAction(action?.componentName, action?.methodName ?? description ?? "fillInputByTestId", [testId]);
672
+ const locator = this.locatorByTestId(testId, description).filter({ visible: true }).first();
673
+ const afterClick = this.getAfterPointerClick();
674
+ await this.pointer.animateCursorToElementAndClickAndFill(locator, text, true, 200, annotationText, afterClick ? { afterClick } : undefined);
580
675
  }
581
676
 
582
677
  /**
@@ -586,45 +681,32 @@ export class BasePage {
586
681
  protected async selectVSelectByTestId(
587
682
  testId: string,
588
683
  value: string,
589
- timeOut: number = 500,
590
684
  annotationText: string = "",
591
685
  description?: string,
686
+ action?: { componentName?: string; methodName: string },
592
687
  ): Promise<void> {
593
- const root = this.locatorByTestId(testId, description);
688
+ this.recordPomAction(action?.componentName, action?.methodName ?? description ?? "selectVSelectByTestId", [testId]);
689
+ const root = this.locatorByTestId(testId, description).filter({ visible: true }).first();
594
690
  const input = root.locator("input");
595
691
 
596
692
  await this.pointer.animateCursorToElement(input, false, 200, annotationText);
597
- await input.click({ force: true });
693
+ await input.click();
598
694
  await this.pointer.animateCursorToElementAndClickAndFill(input, value, false, 200, annotationText);
599
- await this.page.waitForTimeout(timeOut);
600
695
 
601
696
  const option = root.locator("ul.vs__dropdown-menu li[role='option']").first();
602
- if (await option.count()) {
603
- await this.pointer.animateCursorToElement(option, true, 200, annotationText, {
604
- afterClick: async ({ testId: clickedTestId, instrumented }: AfterPointerClickInfo) => {
605
- if (!clickedTestId || !instrumented) return;
606
- await this.waitForTestIdClickEventAfter(clickedTestId);
607
- },
608
- });
609
- }
697
+ await option.waitFor({ state: "visible", timeout: 5_000 });
698
+ const afterClick = this.getAfterPointerClick();
699
+ await this.pointer.animateCursorToElement(option, true, 200, annotationText, afterClick ? { afterClick } : undefined);
610
700
  }
611
701
 
612
702
  public async fillInputByLocator(locator: PwLocator, text: string, annotationText: string = ""): Promise<void> {
613
- await this.pointer.animateCursorToElementAndClickAndFill(locator, text, true, 200, annotationText, {
614
- afterClick: async ({ testId: clickedTestId, instrumented }: AfterPointerClickInfo) => {
615
- if (!clickedTestId || !instrumented) return;
616
- await this.waitForTestIdClickEventAfter(clickedTestId);
617
- },
618
- });
703
+ const afterClick = this.getAfterPointerClick();
704
+ await this.pointer.animateCursorToElementAndClickAndFill(locator, text, true, 200, annotationText, afterClick ? { afterClick } : undefined);
619
705
  }
620
706
 
621
707
  protected async clickByAriaLabel(ariaLabel: string, annotationText: string = ""): Promise<void> {
622
- await this.pointer.animateCursorToElement(`[aria-label="${ariaLabel}"]`, true, 200, annotationText, {
623
- afterClick: async ({ testId: clickedTestId, instrumented }: AfterPointerClickInfo) => {
624
- if (!clickedTestId || !instrumented) return;
625
- await this.waitForTestIdClickEventAfter(clickedTestId);
626
- },
627
- });
708
+ const afterClick = this.getAfterPointerClick();
709
+ await this.pointer.animateCursorToElement(`[aria-label="${ariaLabel}"]`, true, 200, annotationText, afterClick ? { afterClick } : undefined);
628
710
  }
629
711
 
630
712
  /**
@@ -642,7 +724,7 @@ export class BasePage {
642
724
  * @returns True if the element is visible, false otherwise
643
725
  */
644
726
  protected async isVisibleByTestId(testId: string): Promise<boolean> {
645
- return await this.page.isVisible(this.selectorForTestId(testId));
727
+ return this.locatorByTestId(testId).isVisible();
646
728
  }
647
729
 
648
730
  /**
@@ -651,18 +733,18 @@ export class BasePage {
651
733
  * @returns The text content of the element
652
734
  */
653
735
  protected async getTextByTestId(testId: string): Promise<string | null> {
654
- return await this.page.textContent(this.selectorForTestId(testId));
736
+ return this.locatorByTestId(testId).textContent();
655
737
  }
656
738
 
657
739
  /**
658
740
  * Waits for an element with the specified data-testid to be visible
659
741
  * @param testId The data-testid of the element to wait for
660
742
  * @param options Optional timeout and other options
661
- * @param options.timeout The maximum time to wait for the element to be visible (default is 3000ms)
743
+ * @param options.timeout The maximum time to wait for the element to be visible (default is 5000ms)
662
744
  * @returns A promise that resolves when the element is visible
663
745
  */
664
746
  protected async waitForTestId(testId: string, options?: { timeout?: number }): Promise<void> {
665
- await this.page.waitForSelector(this.selectorForTestId(testId), options);
747
+ await this.locatorByTestId(testId).waitFor({ state: "visible", timeout: options?.timeout ?? 5_000 });
666
748
  }
667
749
 
668
750
  /**
@@ -670,9 +752,9 @@ export class BasePage {
670
752
  * @param testId The data-testid of the element to hover over
671
753
  */
672
754
  protected async hoverByTestId(testId: string): Promise<void> {
673
- const selector = this.selectorForTestId(testId);
674
- await this.pointer.animateCursorToElement(selector, false, 200, "");
675
- await this.page.hover(selector);
755
+ const locator = this.locatorByTestId(testId);
756
+ await this.pointer.animateCursorToElement(locator, false, 200, "");
757
+ await locator.hover();
676
758
  }
677
759
 
678
760
  /**
@@ -681,6 +763,6 @@ export class BasePage {
681
763
  * @param value The value to select
682
764
  */
683
765
  protected async selectByTestId(testId: string, value: string): Promise<void> {
684
- await this.page.selectOption(this.selectorForTestId(testId), value);
766
+ await this.locatorByTestId(testId).selectOption(value);
685
767
  }
686
768
  }