@immense/vue-pom-generator 1.0.95 → 1.0.97

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 (38) hide show
  1. package/README.md +124 -0
  2. package/RELEASE_NOTES.md +68 -18
  3. package/class-generation/base-page.ts +18 -2
  4. package/class-generation/index.ts +564 -48
  5. package/class-generation/vue-test-utils-pom.ts +112 -0
  6. package/dist/class-generation/base-page.d.ts +6 -0
  7. package/dist/class-generation/base-page.d.ts.map +1 -1
  8. package/dist/class-generation/index.d.ts +2 -0
  9. package/dist/class-generation/index.d.ts.map +1 -1
  10. package/dist/class-generation/vue-test-utils-pom.d.ts +28 -0
  11. package/dist/class-generation/vue-test-utils-pom.d.ts.map +1 -0
  12. package/dist/index.cjs +625 -48
  13. package/dist/index.cjs.map +1 -1
  14. package/dist/index.mjs +626 -49
  15. package/dist/index.mjs.map +1 -1
  16. package/dist/playwright/runtime.cjs +12 -2
  17. package/dist/playwright/runtime.cjs.map +1 -1
  18. package/dist/playwright/runtime.mjs +12 -2
  19. package/dist/playwright/runtime.mjs.map +1 -1
  20. package/dist/plugin/create-vue-pom-generator-plugins.d.ts.map +1 -1
  21. package/dist/plugin/internal/build-plugin.d.ts.map +1 -1
  22. package/dist/plugin/internal/dev-plugin.d.ts.map +1 -1
  23. package/dist/plugin/resolved-generation-options.d.ts +1 -0
  24. package/dist/plugin/resolved-generation-options.d.ts.map +1 -1
  25. package/dist/plugin/types.d.ts +9 -0
  26. package/dist/plugin/types.d.ts.map +1 -1
  27. package/dist/tests/fixtures/generated-tsc/base-page.full.d.ts +2 -0
  28. package/dist/tests/fixtures/generated-tsc/base-page.full.d.ts.map +1 -1
  29. package/dist/tests/fixtures/generated-tsc/base-page.minimal.d.ts +2 -0
  30. package/dist/tests/fixtures/generated-tsc/base-page.minimal.d.ts.map +1 -1
  31. package/dist/tests/semantic-component-instances.test.d.ts +2 -0
  32. package/dist/tests/semantic-component-instances.test.d.ts.map +1 -0
  33. package/dist/tests/vue-test-utils-pom.test.d.ts +2 -0
  34. package/dist/tests/vue-test-utils-pom.test.d.ts.map +1 -0
  35. package/dist/transform.d.ts.map +1 -1
  36. package/dist/utils.d.ts +40 -12
  37. package/dist/utils.d.ts.map +1 -1
  38. package/package.json +4 -1
package/README.md CHANGED
@@ -734,6 +734,116 @@ 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
+
797
+ ## Vue Test Utils component objects
798
+
799
+ Enable `generation.vueTestUtils` to emit behavior-oriented component objects for mounted
800
+ Vue unit tests alongside the Playwright output:
801
+
802
+ ```ts
803
+ vuePomGenerator({
804
+ generation: {
805
+ vueTestUtils: {},
806
+ },
807
+ });
808
+ ```
809
+
810
+ The default output directory is `tests/unit/__generated__`. The consuming project must
811
+ install Vue Test Utils 2.x. The test remains responsible for mounting the component and
812
+ providing its plugins, props, stubs, and mocks:
813
+
814
+ ```ts
815
+ import { mount } from "@vue/test-utils";
816
+ import { expect, test } from "vitest";
817
+
818
+ import DeploymentParametersForm from "@/components/DeploymentParametersForm.vue";
819
+ import { DeploymentParametersForm as DeploymentParametersFormPom } from "./__generated__";
820
+
821
+ test("requires an onboarding parameter", async () => {
822
+ const wrapper = mount(DeploymentParametersForm, { /* project-specific mount options */ });
823
+ const form = new DeploymentParametersFormPom(wrapper);
824
+
825
+ await form
826
+ .DynamicFormField(parameterName)
827
+ .OnboardingOption
828
+ .OverridePolicyOptions
829
+ .selectByValue(ParameterOverridePolicy.Require);
830
+
831
+ expect(form.DynamicFormField(parameterName).wrapper.text()).toContain("Required");
832
+ });
833
+ ```
834
+
835
+ The Vue templates mounted by the test must be compiled with the same
836
+ `createVuePomGeneratorPlugins(...)` configuration (normally by sharing the Vite plugins
837
+ with Vitest). That compilation injects the generator-owned `data-pom-instance` scoping
838
+ markers used by semantic component chains.
839
+
840
+ These generated objects reuse the same semantic instance names, keyed scopes, named-slot
841
+ projections, and action names as the Playwright POMs. They expose actions such as
842
+ `clickSave()`, `typeName(text)`, and `selectByValue(value)`, not a generated assertion DSL
843
+ or the raw Vue component ancestry. Each object exposes its scoped Vue Test Utils `wrapper`
844
+ for assertions and uncommon interactions. This keeps assertions in Vitest/VTU while
845
+ preventing selectors in the test from escaping the intended component instance.
846
+
737
847
  ## Playwright fixtures: actual behavior and caveats
738
848
 
739
849
  When `generation.playwright.fixtures` is enabled, the generator emits a strongly typed Playwright fixture module.
@@ -1246,6 +1356,20 @@ If omitted, router introspection is off.
1246
1356
  - `Record<string, fn>` for explicit shim implementations
1247
1357
  - **Not supported:** wildcard `*` exports
1248
1358
 
1359
+ ### `generation.vueTestUtils`
1360
+
1361
+ - **What it does:** Emits behavior-oriented component objects for Vue Test Utils.
1362
+ - **Why it exists:** unit tests can use the same semantic instance names and generated actions as browser tests without copying test-id selectors.
1363
+ - **Benefit:** selectors stay compiler-derived while the test continues to own mounting and assertions.
1364
+ - **Without it:** no Vue Test Utils files are generated.
1365
+ - **Default output:** `tests/unit/__generated__`.
1366
+ - **Requirement:** the consuming project must provide Vue Test Utils 2.x.
1367
+
1368
+ #### `generation.vueTestUtils.outDir`
1369
+
1370
+ - **What it does:** Overrides the Vue Test Utils generated-file directory.
1371
+ - **Without it:** defaults to `tests/unit/__generated__`.
1372
+
1249
1373
  ### `generation.playwright`
1250
1374
 
1251
1375
  This object holds Playwright-specific additions on top of the generated TypeScript classes.
package/RELEASE_NOTES.md CHANGED
@@ -1,30 +1,80 @@
1
+ I'll verify which PRs actually fall within the release window by querying their merge timestamps
2
+ from GitHub.
3
+
4
+ Let me use the GitHub MCP tools to find PRs merged in the time window.
5
+
6
+ Now I have merge timestamps. Let me convert the window to UTC and check the git log to confirm which
7
+ commits are actually in range.
8
+
9
+ PR #59 was part of v1.0.96. Only PR #60 is in v1.0.97. Let me examine the actual changes to write
10
+ accurate notes.
11
+
12
+ I now have a complete understanding of the changes. Only PR #60 is in this release (PR #59 was part
13
+ of v1.0.96, confirmed by git log). Let me generate the release notes.
14
+
15
+ Release Notes — v1.0.97
16
+
1
17
  Highlights
2
18
 
3
- - Editable combobox wrappers (<input role="combobox">) now generate fill actions instead of native
4
- selectOption(), which only works on <select> elements.
5
- - Wrapper role inference now considers the underlying element tag when mapping the combobox ARIA
6
- role, distinguishing editable inputs from native select-like comboboxes.
7
- - Documentation and test coverage updated to reflect the corrected behavior.
19
+ - New: Vue Test Utils component object generation — emit behavior-oriented POM objects for mounted
20
+ Vue unit tests alongside existing Playwright output
21
+ - Generated VTU objects reuse the same semantic instance names, keyed scopes, named-slot
22
+ projections, and action names as Playwright POMs
23
+ - Tests own mounting and assertions; selectors stay compiler-derived via data-pom-instance scoping
24
+ markers
25
+ - New opt-in generation.vueTestUtils config with configurable output directory (defaults to
26
+ tests/unit/__generated__)
27
+ - Full test coverage added: unit tests for the runtime class, type-checking of generated files, and
28
+ packed-plugin smoke checks
8
29
 
9
30
  Changes
10
31
 
11
- - wrapper-contract.ts: mapExplicitAriaRole now accepts the element tag and returns "input" for
12
- <input>/<uinput> elements with role="combobox", falling back to "select" otherwise.
13
- getElementControlRole passes the tag through to this function.
14
- - README.md: Expanded the wrapper-inference section to explain that an editable <input
15
- role="combobox"> retains input behavior so generated actions fill it rather than calling
16
- selectOption().
17
- - tests/wrapper-contract.test.ts: Added a test verifying that an editable combobox target resolves
18
- to input interaction behavior.
19
- - tests/transform.test.ts: Added an end-to-end test confirming a typeSearch method is generated
20
- (and selectSearch is not) for an editable combobox wrapper.
32
+ Vue Test Utils POM Generation
33
+
34
+ - Added class-generation/vue-test-utils-pom.ts — VueTestUtilsPom base class exposing getByTestId,
35
+ getByAnyTestId, getComponentInstance, clickByTestId, selectVSelectByTestId, and a public wrapper for
36
+ consumer assertions
37
+ - Added generateVueTestUtilsFiles and supporting helpers (getVueTestUtilsPrimaryMembers,
38
+ getVueTestUtilsExtraMembers, getVueTestUtilsParameters) to class-generation/index.ts
39
+ - Generated actions include clickSave(), typeName(text), selectByValue(value), and v-select
40
+ interactions — no generated assertion DSL or raw component ancestry exposed
41
+ - Refactored getUniquePrimaryPomSpecs out of generateMethodsContentForDependencies for
42
+ deduplication reuse
43
+
44
+ Configuration & Plugin Wiring
45
+
46
+ - Added generation.vueTestUtils option (with outDir) to VuePomGeneratorPluginOptions in
47
+ plugin/types.ts
48
+ - Added vueTestUtilsOutDir to ResolvedGenerationSupportOptions in
49
+ plugin/resolved-generation-options.ts
50
+ - Wired the option through create-vue-pom-generator-plugins.ts, build-plugin.ts, and dev-plugin.ts
51
+ - Validation: fails fast if vueTestUtils.outDir is empty or matches generation.outDir
52
+
53
+ Dependencies
54
+
55
+ - Added @vue/test-utils (^2.4.11), @vue/server-renderer, and vue (3.5.27) as devDependencies
56
+
57
+ Documentation
58
+
59
+ - Added full README section covering setup, usage example, and the generation.vueTestUtils.outDir
60
+ reference
61
+
62
+ Breaking Changes
63
+
64
+ None. Vue Test Utils generation is opt-in; existing Playwright-only behavior is unchanged.
21
65
 
22
66
  Pull Requests Included
23
67
 
24
- - #58 fix(wrappers): fill editable comboboxes (]8;id=md-1eex0z3;https://github.com/immense/vue-pom-generator/pull/58#58]8;;]8;;)]8;;
68
+ - ]8;id=md-c46er0;https://github.com/immense/vue-pom-generator/pull/60#60 — Generate Vue Test Utils component objects]8;;]8;; (@dkattan)]8;;
25
69
 
26
70
  Testing
27
71
 
28
- Added targeted tests for wrapper-contract inference and end-to-end transform output. Full suite (417
29
- tests), typecheck, lint, build, and smoke-pack all passing per the PR.
72
+ - New tests/vue-test-utils-pom.test.ts (157 lines) exercises the VueTestUtilsPom runtime against
73
+ mounted components (radio groups, keyed scoped instances, v-selects, inputs, buttons)
74
+ - Extended tests/semantic-component-instances.test.ts to generate Vue Test Utils files and
75
+ type-check them with tsc --noEmit
76
+ - Extended tests/options.test.ts to verify default acceptance and fail-fast on empty outDir
77
+ - Extended tests/resolved-generation-options.test.ts for vueTestUtilsOutDir resolution
78
+ - Extended scripts/packed-smoke-check.mjs to build through the packed Vite plugin, emit VTU output,
79
+ and type-check generated files including the copied runtime
30
80
 
@@ -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.page.locator(this.selectorForTestId(testId)), description);
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.page.locator(`label[for=${JSON.stringify(controlId)}]`).first();
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;