@immense/vue-pom-generator 1.0.94 → 1.0.96
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/README.md +61 -1
- package/RELEASE_NOTES.md +52 -58
- package/class-generation/base-page.ts +18 -2
- package/class-generation/index.ts +249 -45
- package/dist/class-generation/base-page.d.ts +6 -0
- package/dist/class-generation/base-page.d.ts.map +1 -1
- package/dist/class-generation/index.d.ts.map +1 -1
- package/dist/index.cjs +370 -48
- package/dist/index.cjs.map +1 -1
- package/dist/index.mjs +371 -49
- package/dist/index.mjs.map +1 -1
- package/dist/playwright/runtime.cjs +12 -2
- package/dist/playwright/runtime.cjs.map +1 -1
- package/dist/playwright/runtime.mjs +12 -2
- package/dist/playwright/runtime.mjs.map +1 -1
- package/dist/tests/fixtures/generated-tsc/base-page.full.d.ts +2 -0
- package/dist/tests/fixtures/generated-tsc/base-page.full.d.ts.map +1 -1
- package/dist/tests/fixtures/generated-tsc/base-page.minimal.d.ts +2 -0
- package/dist/tests/fixtures/generated-tsc/base-page.minimal.d.ts.map +1 -1
- package/dist/tests/semantic-component-instances.test.d.ts +2 -0
- package/dist/tests/semantic-component-instances.test.d.ts.map +1 -0
- package/dist/transform.d.ts.map +1 -1
- package/dist/utils.d.ts +40 -12
- package/dist/utils.d.ts.map +1 -1
- package/dist/wrapper-contract.d.ts.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -79,7 +79,7 @@ The generator does not use one naming trick. It layers several signals.
|
|
|
79
79
|
- **Fallback naming exists, but it is intentionally conservative.** That is why `generation.nameCollisionBehavior` exists.
|
|
80
80
|
- **Wrapper-action generation fails fast.** The generator blocks button-like wrapper `:handler` expressions that it cannot turn into a semantic action name.
|
|
81
81
|
|
|
82
|
-
Wrapper inference follows the public attribute contract instead of scanning for an arbitrary interactive descendant. It recognizes automatic single-root fallthrough, `v-bind="$attrs"`, aliases returned by `useAttrs()`, explicit forwarding such as `:data-testid="$attrs['data-testid']"`, and simple helpers that copy all attributes except named keys. The role comes from that target's explicit static ARIA role first, then its native HTML semantics. This means `<button role="tab">` is a tab, while `<div><button>...</button></div>` is not misclassified as a button wrapper because the caller's test id lands on the `<div>`. Nested wrappers are followed recursively. Polymorphic targets with different roles are deliberately left unresolved; configure `nativeWrappers` when one stable generated role is still appropriate.
|
|
82
|
+
Wrapper inference follows the public attribute contract instead of scanning for an arbitrary interactive descendant. It recognizes automatic single-root fallthrough, `v-bind="$attrs"`, aliases returned by `useAttrs()`, explicit forwarding such as `:data-testid="$attrs['data-testid']"`, and simple helpers that copy all attributes except named keys. The role comes from that target's explicit static ARIA role first, then its native HTML semantics. This means `<button role="tab">` is a tab, while an editable `<input role="combobox">` retains input behavior so generated actions fill it instead of calling native `selectOption()`. A `<div><button>...</button></div>` is not misclassified as a button wrapper because the caller's test id lands on the `<div>`. Nested wrappers are followed recursively. Polymorphic targets with different roles are deliberately left unresolved; configure `nativeWrappers` when one stable generated role is still appropriate.
|
|
83
83
|
|
|
84
84
|
## Playwright before/after examples
|
|
85
85
|
|
|
@@ -734,6 +734,66 @@ Actual current rules:
|
|
|
734
734
|
|
|
735
735
|
Without `flatten`, helper composition still works; you just call through the helper property explicitly.
|
|
736
736
|
|
|
737
|
+
## Semantic, scoped component instances
|
|
738
|
+
|
|
739
|
+
Generated TypeScript POMs model component **invocations**, not only component types. Each
|
|
740
|
+
addressable invocation receives a generator-owned `data-pom-instance` marker on the DOM
|
|
741
|
+
root that accepts Vue fallthrough attributes. The child POM is rooted at that marker, so
|
|
742
|
+
identical controls in two component instances cannot accidentally select each other.
|
|
743
|
+
|
|
744
|
+
Instance names come from author-visible semantics, in this order:
|
|
745
|
+
|
|
746
|
+
1. a static accessible name (`aria-label`, `label`, `title`, or `name`)
|
|
747
|
+
2. the identifier bound to `:options`
|
|
748
|
+
3. the `v-model` / `:model-value` identifier
|
|
749
|
+
4. the component tag as the fallback
|
|
750
|
+
|
|
751
|
+
The generator tries those candidates in order. If an earlier invocation already owns a
|
|
752
|
+
semantic candidate, the later invocation uses its next candidate instead. For example, a
|
|
753
|
+
dialog titled `RDP Password` can own `RdpPassword` while its nested copy-input falls back
|
|
754
|
+
to `CopyToClipboardInput`. Repeated structural wrappers with no unique candidate are
|
|
755
|
+
omitted from composition; their ordinary generated controls are unaffected.
|
|
756
|
+
|
|
757
|
+
Static invocations become properties. Repeated invocations with a stable `:key` become
|
|
758
|
+
methods whose argument selects the instance:
|
|
759
|
+
|
|
760
|
+
```vue
|
|
761
|
+
<DynamicFormField
|
|
762
|
+
v-for="parameter in parameters"
|
|
763
|
+
:key="parameter.name"
|
|
764
|
+
:parameter="parameter"
|
|
765
|
+
/>
|
|
766
|
+
|
|
767
|
+
<ImmyRadioGroup
|
|
768
|
+
aria-label="Override policy options"
|
|
769
|
+
:options="overridePolicyOptions"
|
|
770
|
+
/>
|
|
771
|
+
```
|
|
772
|
+
|
|
773
|
+
```ts
|
|
774
|
+
form
|
|
775
|
+
.DynamicFormField(parameterName)
|
|
776
|
+
.OnboardingOption
|
|
777
|
+
.OverridePolicyOptions
|
|
778
|
+
.selectByValue(ParameterOverridePolicy.Require);
|
|
779
|
+
```
|
|
780
|
+
|
|
781
|
+
Named slot content is projected onto the component instance that receives the slot. That
|
|
782
|
+
is why the example can expose `OnboardingOption` beneath `DynamicFormField` even when an
|
|
783
|
+
intermediate form component forwards the slot. The generator only emits this projection
|
|
784
|
+
when the receiving boundary and every attached child have one statically provable scope.
|
|
785
|
+
Keyed slot owners and keyed projected content fail generation instead of producing a
|
|
786
|
+
misleading API. Components that do not forward the marker to a DOM root are omitted from
|
|
787
|
+
component-instance composition rather than falling back to page-wide selectors; their
|
|
788
|
+
own standalone fixture is still generated normally.
|
|
789
|
+
|
|
790
|
+
When `injection.optionKeyAttribute` maps a radio component to `"value"`, its generated
|
|
791
|
+
selection API uses the domain term directly: `selectByValue(value)`. Other configured
|
|
792
|
+
attribute names retain `key` when the HTML attribute name is not a valid public TypeScript
|
|
793
|
+
identifier (for example `data-value`).
|
|
794
|
+
|
|
795
|
+
`data-pom-instance` is generator-owned. Do not author it in Vue templates.
|
|
796
|
+
|
|
737
797
|
## Playwright fixtures: actual behavior and caveats
|
|
738
798
|
|
|
739
799
|
When `generation.playwright.fixtures` is enabled, the generator emits a strongly typed Playwright fixture module.
|
package/RELEASE_NOTES.md
CHANGED
|
@@ -1,83 +1,77 @@
|
|
|
1
|
-
I'll
|
|
2
|
-
|
|
1
|
+
I'll verify the actual commits in the release range and gather details about the changes before
|
|
2
|
+
writing the notes.
|
|
3
3
|
|
|
4
|
-
|
|
5
|
-
GitHub API.
|
|
4
|
+
Let me examine the actual diff to understand the changes precisely.
|
|
6
5
|
|
|
7
|
-
|
|
8
|
-
for accurate notes.
|
|
6
|
+
Let me check the remaining changed files for completeness.
|
|
9
7
|
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
Let me verify the release tag and confirm only PR #59 is in range.
|
|
9
|
+
|
|
10
|
+
Let me verify whether PR #58 is already in v1.0.95 or if it's part of this release.
|
|
11
|
+
|
|
12
|
+
I now have full clarity. v1.0.95 was tagged at PR #58's merge commit, so only PR #59 is new in
|
|
13
|
+
v1.0.96. Here are the release notes:
|
|
12
14
|
|
|
13
15
|
Highlights
|
|
14
16
|
|
|
15
|
-
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
-
|
|
28
|
-
|
|
17
|
+
- Scoped component instances: Generated POMs now model individual Vue component invocations — not
|
|
18
|
+
just component types — each rooted at a generator-owned data-pom-instance marker, eliminating
|
|
19
|
+
cross-instance selector collisions.
|
|
20
|
+
- Semantic instance naming: Instance names are inferred from accessible names (aria-label, label,
|
|
21
|
+
title, name), :options bindings, v-model/:model-value identifiers, and component tags, with earlier
|
|
22
|
+
invocations claiming candidates first.
|
|
23
|
+
- Keyed instance accessors: Static invocations become properties; repeated invocations with a
|
|
24
|
+
stable :key become methods that accept a key argument to select the instance.
|
|
25
|
+
- Named-slot projection: Slot content is projected onto the receiving component instance, enabling
|
|
26
|
+
fluent chains like form.DynamicFormField(parameterName).OnboardingOption.
|
|
27
|
+
- selectByValue(value) API: Radio wrappers configured with optionKeyAttribute: "value" now emit a
|
|
28
|
+
domain-term selectByValue(value) selection method.
|
|
29
|
+
- Fail-fast safety: Components that can't forward the scope marker are omitted from composition
|
|
30
|
+
rather than falling back to page-wide selectors; ambiguous names and incompatible keyed-slot
|
|
31
|
+
projections throw clear errors.
|
|
29
32
|
|
|
30
33
|
Changes
|
|
31
34
|
|
|
32
|
-
|
|
35
|
+
Component instance generation
|
|
33
36
|
|
|
34
|
-
-
|
|
35
|
-
|
|
36
|
-
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
37
|
+
- Added data-pom-instance marker injection and scoped child POM rooting in transform.ts (instance
|
|
38
|
+
detection, name-candidate inference, keyed/static classification, slot-outlet tracking).
|
|
39
|
+
- Added component-instance resolution, uniqueness checking, and named-slot projection in
|
|
40
|
+
class-generation/index.ts, generating properties for static instances and parameterized methods for
|
|
41
|
+
keyed instances.
|
|
42
|
+
- Added componentInstanceLocator and locatorInScope helpers to BasePage; BasePageOptions now
|
|
43
|
+
accepts an optional root locator that scopes every generated selector in a component POM.
|
|
44
|
+
- Updated utils.ts toPomKeyPattern to accept a configurable parameter name (defaulting to key), and
|
|
45
|
+
added selectorParameterName support so optionKeyAttribute surfaces the attribute name (e.g. value)
|
|
46
|
+
in the public API.
|
|
44
47
|
|
|
45
|
-
|
|
48
|
+
Documentation
|
|
46
49
|
|
|
47
|
-
-
|
|
48
|
-
|
|
49
|
-
- README updated to document the new fallthrough-based inference model, the tab role, and the
|
|
50
|
-
revised nativeWrappers semantics.
|
|
50
|
+
- Added a new "Semantic, scoped component instances" section to README.md covering marker behavior,
|
|
51
|
+
naming priority, keyed vs. static accessors, slot projection, and selectByValue.
|
|
51
52
|
|
|
52
53
|
Tests
|
|
53
54
|
|
|
54
|
-
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
55
|
+
- Added tests/semantic-component-instances.test.ts (189 lines) covering
|
|
56
|
+
keyed/slot-projected/semantically-named component chains.
|
|
57
|
+
- Updated base-page.test.ts, class-generation-coverage.test.ts, generated-tsc.test.ts,
|
|
58
|
+
transform.test.ts, and tsc fixtures (base-page.full.ts, base-page.minimal.ts) for the new scoping
|
|
59
|
+
and instance APIs.
|
|
59
60
|
|
|
60
61
|
Breaking Changes
|
|
61
62
|
|
|
62
|
-
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
- nativeWrappers without role now errors when no single role can be proven from the source.
|
|
67
|
-
Previously it silently defaulted to button; now it throws so misclassified wrappers surface
|
|
68
|
-
immediately.
|
|
69
|
-
- wrapperSearchRoots auto-includes source directories. If you previously listed your
|
|
70
|
-
component/page/layout dirs in wrapperSearchRoots, they are now searched automatically and can be
|
|
71
|
-
removed from the list.
|
|
63
|
+
- Generated child POM properties now use semantic invocation names and scoped roots. Consumers must
|
|
64
|
+
regenerate POMs and update affected call sites. Components that cannot forward the generator-owned
|
|
65
|
+
data-pom-instance scope marker are omitted from composition instead of falling back to page-wide
|
|
66
|
+
selectors.
|
|
72
67
|
|
|
73
68
|
Pull Requests Included
|
|
74
69
|
|
|
75
|
-
- ]8;id=md-
|
|
70
|
+
- ]8;id=md-1e4xfa4;https://github.com/immense/vue-pom-generator/pull/59#59 feat!: generate scoped component instances]8;;]8;; — by @dkattan]8;;
|
|
76
71
|
|
|
77
72
|
Testing
|
|
78
73
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
option and revised wrapper-resolution behavior.
|
|
74
|
+
Validated with npm test (419 passed), npm run typecheck, npm run lint (0 errors), npm run build,
|
|
75
|
+
Playwright integration tests (3 passed), npm run smoke:pack, and a real-world frontend build
|
|
76
|
+
producing 643 POMs / 1,443 selectors.
|
|
83
77
|
|
|
@@ -75,6 +75,8 @@ export type Fluent<T extends object> = DeepFluent<T, T> & PromiseLike<T>;
|
|
|
75
75
|
export type ValueFluent<T> = DeepValueFluent<T> & PromiseLike<T>;
|
|
76
76
|
|
|
77
77
|
export interface BasePageOptions {
|
|
78
|
+
/** Locator that scopes every generated selector in this component POM. */
|
|
79
|
+
root?: PwLocator;
|
|
78
80
|
renderers?: {
|
|
79
81
|
callout?: CalloutRenderer;
|
|
80
82
|
pointer?: PointerRenderer;
|
|
@@ -133,6 +135,7 @@ export class BasePage {
|
|
|
133
135
|
* etc. for JS/DOM elements the generator can't key.
|
|
134
136
|
*/
|
|
135
137
|
private readonly _page: PwPage;
|
|
138
|
+
private readonly _root?: PwLocator;
|
|
136
139
|
|
|
137
140
|
/**
|
|
138
141
|
* Playwright's full `Page`, exposed to subclasses. This is the single,
|
|
@@ -149,6 +152,7 @@ export class BasePage {
|
|
|
149
152
|
*/
|
|
150
153
|
public constructor(page: PwPage, options?: BasePageOptions) {
|
|
151
154
|
this._page = page;
|
|
155
|
+
this._root = options?.root;
|
|
152
156
|
this.testIdAttribute = (options?.testIdAttribute || "data-testid").trim() || "data-testid";
|
|
153
157
|
|
|
154
158
|
const pointerRenderer = options?.renderers?.pointer;
|
|
@@ -287,8 +291,20 @@ export class BasePage {
|
|
|
287
291
|
return normalizedDescription ? locator.describe(normalizedDescription) : locator;
|
|
288
292
|
}
|
|
289
293
|
|
|
294
|
+
private locatorInScope(selector: string, within?: PwLocator): Locator {
|
|
295
|
+
const root = within ?? this._root;
|
|
296
|
+
return (root ? root.locator(selector) : this._page.locator(selector)) as Locator;
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
/** Resolve a generated component-instance marker inside this POM's current scope. */
|
|
300
|
+
protected componentInstanceLocator(instanceId: string, within?: PwLocator): Locator {
|
|
301
|
+
return this.locatorInScope(`[data-pom-instance=${JSON.stringify(instanceId)}]`, within)
|
|
302
|
+
.filter({ visible: true })
|
|
303
|
+
.first();
|
|
304
|
+
}
|
|
305
|
+
|
|
290
306
|
protected locatorByTestId(testId: string, description?: string): Locator {
|
|
291
|
-
return this.describeLocator(this.
|
|
307
|
+
return this.describeLocator(this.locatorInScope(this.selectorForTestId(testId)), description);
|
|
292
308
|
}
|
|
293
309
|
|
|
294
310
|
protected async resolveVisibleTestIdLocator(
|
|
@@ -612,7 +628,7 @@ export class BasePage {
|
|
|
612
628
|
// pseudo-elements intercept the pointer. Playwright's visible filter can exclude that
|
|
613
629
|
// empty label even though its pseudo-element is the actual interaction surface, so first
|
|
614
630
|
// select the associated label by DOM presence and then choose pointer or keyboard activation.
|
|
615
|
-
const associatedLabel = this.
|
|
631
|
+
const associatedLabel = this.locatorInScope(`label[for=${JSON.stringify(controlId)}]`).first();
|
|
616
632
|
if (await associatedLabel.count() > 0) {
|
|
617
633
|
if (await associatedLabel.isVisible()) {
|
|
618
634
|
clickTarget = associatedLabel;
|