@shivaedev/test-story 0.28.0 → 0.30.0

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 (101) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +90 -37
  3. package/dist/server/adapters/outcomeMatchers.d.ts +12 -0
  4. package/dist/server/adapters/outcomeMatchers.d.ts.map +1 -0
  5. package/dist/server/adapters/outcomeMatchers.js +22 -0
  6. package/dist/server/adapters/outcomeMatchers.js.map +1 -0
  7. package/dist/server/{internal → adapters}/screenElements.d.ts +6 -2
  8. package/dist/server/adapters/screenElements.d.ts.map +1 -0
  9. package/dist/server/{internal → adapters}/screenElements.js +23 -15
  10. package/dist/server/adapters/screenElements.js.map +1 -0
  11. package/dist/server/adapters/screenMutations.d.ts +3 -0
  12. package/dist/server/adapters/screenMutations.d.ts.map +1 -0
  13. package/dist/server/adapters/screenMutations.js +11 -0
  14. package/dist/server/adapters/screenMutations.js.map +1 -0
  15. package/dist/server/adapters/screenNavigation.d.ts +3 -0
  16. package/dist/server/adapters/screenNavigation.d.ts.map +1 -0
  17. package/dist/server/adapters/screenNavigation.js +34 -0
  18. package/dist/server/adapters/screenNavigation.js.map +1 -0
  19. package/dist/server/adapters/screenQueries.d.ts +8 -0
  20. package/dist/server/adapters/screenQueries.d.ts.map +1 -0
  21. package/dist/server/adapters/screenQueries.js +62 -0
  22. package/dist/server/adapters/screenQueries.js.map +1 -0
  23. package/dist/server/internal/compose.d.ts.map +1 -1
  24. package/dist/server/internal/compose.js +2 -2
  25. package/dist/server/internal/compose.js.map +1 -1
  26. package/dist/server/internal/engineSnapshot.d.ts.map +1 -1
  27. package/dist/server/internal/engineSnapshot.js +3 -0
  28. package/dist/server/internal/engineSnapshot.js.map +1 -1
  29. package/dist/server/internal/hookInference.d.ts +3 -2
  30. package/dist/server/internal/hookInference.d.ts.map +1 -1
  31. package/dist/server/internal/narration.d.ts +11 -1
  32. package/dist/server/internal/narration.d.ts.map +1 -1
  33. package/dist/server/internal/narration.js +8 -3
  34. package/dist/server/internal/narration.js.map +1 -1
  35. package/dist/server/internal/nextClientHint.d.ts +4 -0
  36. package/dist/server/internal/nextClientHint.d.ts.map +1 -0
  37. package/dist/server/internal/{screenActivity.js → nextClientHint.js} +1 -5
  38. package/dist/server/internal/nextClientHint.js.map +1 -0
  39. package/dist/server/internal/screenAccessibility.d.ts +0 -1
  40. package/dist/server/internal/screenAccessibility.d.ts.map +1 -1
  41. package/dist/server/internal/screenAccessibility.js +1 -22
  42. package/dist/server/internal/screenAccessibility.js.map +1 -1
  43. package/dist/server/internal/screenReadouts.d.ts +1 -1
  44. package/dist/server/internal/screenReadouts.d.ts.map +1 -1
  45. package/dist/server/internal/screenReadouts.js +3 -3
  46. package/dist/server/internal/screenReadouts.js.map +1 -1
  47. package/dist/server/internal/screenText.d.ts +2 -0
  48. package/dist/server/internal/screenText.d.ts.map +1 -0
  49. package/dist/server/internal/screenText.js +40 -0
  50. package/dist/server/internal/screenText.js.map +1 -0
  51. package/dist/server/internal/screenWaits.d.ts +28 -0
  52. package/dist/server/internal/screenWaits.d.ts.map +1 -0
  53. package/dist/server/internal/screenWaits.js +47 -0
  54. package/dist/server/internal/screenWaits.js.map +1 -0
  55. package/dist/server/internal/start.js +1 -1
  56. package/dist/server/internal/start.js.map +1 -1
  57. package/dist/server/internal/waitForScreen.d.ts +9 -0
  58. package/dist/server/internal/waitForScreen.d.ts.map +1 -0
  59. package/dist/server/internal/waitForScreen.js +36 -0
  60. package/dist/server/internal/waitForScreen.js.map +1 -0
  61. package/dist/server/outcomes.d.ts +8 -1
  62. package/dist/server/outcomes.d.ts.map +1 -1
  63. package/dist/server/outcomes.js +6 -6
  64. package/dist/server/outcomes.js.map +1 -1
  65. package/dist/server/screenDriver.d.ts +19 -9
  66. package/dist/server/screenDriver.d.ts.map +1 -1
  67. package/dist/server/screenDriver.js +18 -58
  68. package/dist/server/screenDriver.js.map +1 -1
  69. package/dist/server/storyKit.d.ts +2 -2
  70. package/dist/server/storyKit.d.ts.map +1 -1
  71. package/dist/server/storyKit.js.map +1 -1
  72. package/dist/server/until.d.ts +16 -0
  73. package/dist/server/until.d.ts.map +1 -0
  74. package/dist/server/until.js +36 -0
  75. package/dist/server/until.js.map +1 -0
  76. package/package.json +3 -3
  77. package/src/server/adapters/outcomeMatchers.ts +33 -0
  78. package/src/server/{internal → adapters}/screenElements.ts +23 -15
  79. package/src/server/adapters/screenMutations.ts +14 -0
  80. package/src/server/adapters/screenNavigation.ts +37 -0
  81. package/src/server/adapters/screenQueries.ts +75 -0
  82. package/src/server/internal/compose.ts +6 -2
  83. package/src/server/internal/engineSnapshot.ts +4 -1
  84. package/src/server/internal/hookInference.ts +4 -2
  85. package/src/server/internal/narration.ts +15 -3
  86. package/src/server/internal/{screenActivity.ts → nextClientHint.ts} +1 -5
  87. package/src/server/internal/screenAccessibility.ts +1 -25
  88. package/src/server/internal/screenReadouts.ts +3 -3
  89. package/src/server/internal/screenText.ts +41 -0
  90. package/src/server/internal/screenWaits.ts +105 -0
  91. package/src/server/internal/start.ts +1 -1
  92. package/src/server/internal/waitForScreen.ts +48 -0
  93. package/src/server/outcomes.ts +19 -10
  94. package/src/server/screenDriver.ts +25 -73
  95. package/src/server/storyKit.ts +4 -2
  96. package/src/server/until.ts +60 -0
  97. package/dist/server/internal/screenActivity.d.ts +0 -5
  98. package/dist/server/internal/screenActivity.d.ts.map +0 -1
  99. package/dist/server/internal/screenActivity.js.map +0 -1
  100. package/dist/server/internal/screenElements.d.ts.map +0 -1
  101. package/dist/server/internal/screenElements.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,39 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.30.0 - 2026-10-31
4
+
5
+ ### Added
6
+
7
+ - `test-story` exports `lessThan`, `atMost`, `greaterThan` and `atLeast` from `server/adapters/outcomeMatchers.ts` for numeric bounds, including in nested expected values. Failure diffs show the bound and received value.
8
+ - Supply a native `Stream<boolean>` as the screen driver's `pending` signal to wake settlement and target searches when application work changes without a DOM mutation.
9
+ - Wait for visible text with `findText`, removal or hiding with `gone`, and a destination URL prefix with `navigatedAway`. Wait failures name their targets in the story report.
10
+ - Change native select controls with `select(target, value)` inside the renderer's `act` adapter.
11
+
12
+ ### Changed
13
+
14
+ - The shared story-testing skill teaches ordered lazy outcomes, nested partial expectations and numeric bounds. Quality’s grouped-outcomes diagnostic recommends the ordered callback form.
15
+
16
+ ### Fixed
17
+
18
+ - Reach portalled dialogs from the screen driver while keeping `within` scopes local, and find unnamed alerts by their visible text.
19
+ - Avoid holding `act` open between DOM mutations when no pending signal is supplied.
20
+
21
+ ### Breaking
22
+
23
+ - `test-story` outcomes now takes an ordered list of `[label, () => readout(), expected]` rows. Migrate each `label: [readout(), expected]` object entry to a tuple and wrap its readout in a callback. Keep labels natural and put rows in their intended run order. Readouts are built only when their row starts. Expected objects match partially at every depth with native `toMatchObject` semantics; arrays retain length and order. Use a plain `expect(...).toEqual(...)` when exact object equality is required.
24
+ - Screen settlement and target searches react to DOM mutations instead of polling. Boolean pending samplers run on the initial check and mutations. Migrate samplers that complete work without a mutation to a pending stream. Target searches now wait for pending work to finish and for the target to render, with the existing timeout diagnostics.
25
+
26
+ ## 0.29.0 - 2026-10-31
27
+
28
+ ### Added
29
+
30
+ - Let story kit `inspect` hooks return Effects or generators to read engine state with the kit's services before its Scope closes, including in composed kits.
31
+ - Wait for native stream signals with `until` and `collectUntil`, using a live-time deadline without advancing the story clock. Missing signals fail with their name, last observation and actionable help.
32
+
33
+ ### Breaking
34
+
35
+ - `screenDriver.text()` separates visible block elements and `<br>` with a newline when adjacent text has no whitespace, while preserving inline text. Update assertions that expected concatenated card titles, messages and actions to expect separated parts, and remove application-side splitting of those parts.
36
+
3
37
  ## 0.28.0 - 2026-10-31
4
38
 
5
39
  ### Added
package/README.md CHANGED
@@ -55,7 +55,7 @@ An application has an **engine**: the real thing a test drives, such as a bakery
55
55
 
56
56
  Every story belongs to a **genre**, the kind of engine it runs. The kit names each of its tests after its genre, such as `Bakery Story: steps until the condition holds`, so a report shows which engine a test runs and one run can pick the bakery's stories and leave the others.
57
57
 
58
- The package runs on Effect and Vitest, but an engine needs neither: every hook, trait and test body may be a plain function. Use a generator function to yield Effects when a hook needs a service or fails with a typed error; the kit runs it, so no definition needs `Effect.gen`. Creation, stage `after` hooks and traits may also be plain functions that return an Effect directly. The kit runs that Effect in the story's Scope, with the services from its layer.
58
+ The package runs on Effect and Vitest, but an engine needs neither: every hook, trait and test body may be a plain function. Use a generator function to yield Effects when a hook needs a service or fails with a typed error; the kit runs it, so no definition needs `Effect.gen`. Creation, stage `after` hooks, `inspect` and traits may also be plain functions that return an Effect directly. The kit runs that Effect in the story's Scope, with the services from its layer.
59
59
 
60
60
  The work splits into three layers, and each is written by a different hand at a different time:
61
61
  1. **Once per engine**, a story kit in `test-support/` says how to create the engine, which services it needs, and how to seed, step and show it.
@@ -308,10 +308,10 @@ app.it("exports the work span without the planted secret", [], function* ({ runW
308
308
  yield* runWork();
309
309
  yield* disposeRuntime();
310
310
 
311
- yield* outcomes({
312
- "exported spans": [exportedSpanNames(), ["CountWords"]],
313
- "exports with the planted secret": [exportsContaining("planted-secret"), 0],
314
- });
311
+ yield* outcomes([
312
+ ["exported spans", () => exportedSpanNames(), ["CountWords"]],
313
+ ["exports with the planted secret", () => exportsContaining("planted-secret"), 0],
314
+ ]);
315
315
  });
316
316
  ```
317
317
 
@@ -489,7 +489,7 @@ bakery.it("tells each step into the story", [ovenIsLit()], function* ({ baker, o
489
489
 
490
490
  A spec starts a story, acts through verbs and checks what a user would see. When it needs a setup or an action the kit lacks, add a trait or verb to the kit instead of building it in the spec.
491
491
 
492
- For several outcomes after one action, use `outcomes` from `@shivaedev/test-story/server/outcomes.ts`. Each row puts its label beside an Effect readout and its expected value:
492
+ For several outcomes after one action, use `outcomes` from `@shivaedev/test-story/server/outcomes.ts`. Each row is `[label, () => readout(), expected]`. The list states the run order, independently of alphabetical key sorting:
493
493
 
494
494
  ```ts
495
495
  import { outcomes } from "@shivaedev/test-story/server/outcomes.ts";
@@ -497,15 +497,33 @@ import { outcomes } from "@shivaedev/test-story/server/outcomes.ts";
497
497
  accounts.it("removing Bob leaves Alice signed in", [bobAndAliceAreSignedIn()], function* ({ remove, request, sessions }) {
498
498
  yield* remove("bob");
499
499
 
500
- yield* outcomes({
501
- "bob's next request": [request("bob"), "unauthorized"],
502
- "bob's sessions": [sessions("bob"), 0],
503
- "alice's next request": [request("alice"), "ok"],
504
- });
500
+ yield* outcomes([
501
+ ["bob's next request", () => request("bob"), "unauthorized"],
502
+ ["bob's sessions", () => sessions("bob"), 0],
503
+ ["alice's next request", () => request("alice"), "ok"],
504
+ ]);
505
+ });
506
+ ```
507
+
508
+ `outcomes` builds and runs each readout only when its row starts, so a verb that tells its line before returning an Effect still prints in row order. It compares all results with one native Vitest `toMatchObject`: objects match partially at every depth, arrays keep their length and order, and asymmetric matchers such as `expect.any(Number)` still work. Each expected value is checked against its own readout’s success type. Repeated labels remain separate rows. A failing readout keeps its typed error and stops later rows; a mismatch shows a labelled diff and the story report points to the `outcomes` call.
509
+
510
+ Import `lessThan`, `atMost`, `greaterThan` or `atLeast` from `@shivaedev/test-story/server/adapters/outcomeMatchers.ts` to state numeric bounds, including inside nested partial values:
511
+
512
+ ```ts
513
+ import { atMost, lessThan } from "@shivaedev/test-story/server/adapters/outcomeMatchers.ts";
514
+ import { outcomes } from "@shivaedev/test-story/server/outcomes.ts";
515
+
516
+ accounts.it("removing Bob leaves no sessions within the request budget", [bobIsSignedIn()], function* ({ remove, details, elapsed }) {
517
+ yield* remove("bob");
518
+
519
+ yield* outcomes([
520
+ ["bob’s account", () => details("bob"), { account: { sessions: atMost(0) } }],
521
+ ["request time", () => elapsed(), lessThan(100)],
522
+ ]);
505
523
  });
506
524
  ```
507
525
 
508
- `outcomes` runs readouts in row order, then compares the actual and expected label-keyed objects with one native Vitest `toEqual`. Expected values follow their readout's success type and accept Vitest asymmetric matchers such as `expect.objectContaining(...)`. A failing readout keeps its typed error; an equality failure shows one labelled diff and the story report points to the `outcomes` call. For one outcome, keep a plain `expect`:
526
+ `lessThan` and `greaterThan` exclude the limit; `atMost` and `atLeast` include it. A bound mismatch prints its name and limit beside the received value. For one outcome, keep a plain `expect`:
509
527
 
510
528
  ```ts
511
529
  accounts.it("removing Bob ends his session", [bobIsSignedIn()], function* ({ remove, request }) {
@@ -573,6 +591,30 @@ help: either the bakery never gets there, so check the setup and the engine, or
573
591
 
574
592
  That is what `oven.bakesEverything(12)` dies with when the baker keeps a sourdough starter, so the dough never runs out. The typed failures of `step`, `failed`, `diagnose` and the condition stay in the Effect's error channel: a step that fails with `BurntLoaf` gives the test a `BurntLoaf` to assert on. A kit without `run` hooks dies with a message that says to add them.
575
593
 
594
+ ### Waiting for a signal
595
+
596
+ Use `until` in a kit verb to consume a native stream through its first matching value. `collectUntil` collects values in arrival order and stops when its predicate matches the collection, including the value that completes it. Supply a name that says what the story is waiting for.
597
+
598
+ ```ts
599
+ import { SubscriptionRef } from "effect";
600
+ import { collectUntil, until } from "@shivaedev/test-story/server/until.ts";
601
+
602
+ const ready = yield* until(
603
+ SubscriptionRef.changes(status),
604
+ (value) => value === "ready",
605
+ { name: "worker ready" },
606
+ );
607
+ const deliveries = yield* collectUntil(
608
+ deliveryStream,
609
+ (values) => values.some((delivery) => delivery.id === requestedId),
610
+ { name: "requested delivery", timeout: "2 seconds" },
611
+ );
612
+ ```
613
+
614
+ The helpers subscribe by running the stream before inspecting its values. Use a stream that includes the current value, such as `SubscriptionRef.changes` or `AtomRegistry.toStream`, when readiness may already hold. They release the subscription on completion or timeout. Their default deadline is five seconds of live time; `timeout` accepts an Effect duration. Only the deadline uses live time: the source keeps the story's clock, and neither helper advances its TestClock.
615
+
616
+ A deadline or stream ending without a match fails with `SignalNotReceived` in the error channel. Its message names the missing signal, shows the last observation (the collection for `collectUntil`, or that no value arrived), and includes a `help:` line. Source failures pass through.
617
+
576
618
  ### When a story fails
577
619
 
578
620
  After the engine has been created, a failing story test adds the story to its first error, as in the examples above:
@@ -606,7 +648,7 @@ For repository-level tests on a migrated template, `withTestTransaction` from `@
606
648
 
607
649
  React screen traits acquire roots in Scope and use a fresh native atom registry for each screen. Cleanup unmounts roots before disposing registries and servers. Screen verbs dispatch DOM events and use bounded observations of rendered output. Select a live clock once on an HTTP/DOM kit; keep TestClock for deterministic local stories. `runUntil` is for engines with a meaningful step hook, not HTTP or DOM polling. Creation forms use the same pattern with `useCreate` from `@shivaedev/react/client/create.ts`.
608
650
 
609
- For cookie sessions, use the DOM host setup below. Native `RpcTest` can exercise handlers in faster local stories, but omits serialization and transport. Failure inspection is synchronous: keep redacted observed values in the engine instead of trying to query PostgreSQL inside `inspect`.
651
+ For cookie sessions, use the DOM host setup below. Native `RpcTest` can exercise handlers in faster local stories, but omits serialization and transport. An `inspect` hook may read engine state through an Effect or generator, using the kit’s layer before the story’s Scope closes.
610
652
 
611
653
  ### DOM stories with cookie sessions
612
654
 
@@ -719,15 +761,18 @@ pnpm add --save-dev react react-dom @effect/atom-react @types/react @types/react
719
761
 
720
762
  `screenDriver(options)` supplies DOM verbs and readouts for a kit's `verbs` hook. Give it the mounted `root` (or a getter for a root that navigation replaces) and the story's `tell`. The `pending` option is required for `settle()`; `nextLiveHint()` requires client activity in that option. DOM actions, lookups and synchronous readouts work without it. Without `pending`, `settle()` fails immediately in its error channel with `MissingScreenPending`, exported from `server/screenDriver.ts`, even when the screen is idle.
721
763
 
722
- To use `settle()`, supply a `pending()` function that reads the application's own request or atom state. Settlement then keeps its `Effect<void>` type with no typed errors and waits until that signal is false; repeated identical renders never count as completion. The application must keep the signal true until its resulting screen work is ready to render.
764
+ To use `settle()`, supply a native `Stream<boolean>` as `pending`, emitting the current pending state on subscription and every subsequent change. For example, a package that tracks work in a native `SubscriptionRef<boolean>` supplies `pending: SubscriptionRef.changes(requests.pending)`. For a native boolean atom, use `AtomRegistry.toStream(view.registry, pendingAtom)` from `effect/reactivity/AtomRegistry`. Keep pending true until the resulting screen work is ready to render. Settlement keeps its `Effect<void>` type with no typed errors and waits until the stream emits false; DOM mutations also wake the driver, and repeated identical renders never count as completion. `find()` waits for pending work to finish and its target to appear, reacting to both signals and mutations.
765
+
766
+ A `pending: () => boolean` sampler remains available for packages whose pending work completes with a DOM mutation. It is sampled after the initial renderer flush and on mutations, without a polling timer. Use the stream when pending can become false without changing the DOM.
723
767
 
724
768
  ```ts
769
+ import { SubscriptionRef } from "effect";
725
770
  import { screenDriver } from "@shivaedev/test-story/server/screenDriver.ts";
726
771
 
727
772
  verbs: ({ view, requests }, story) =>
728
773
  screenDriver({
729
774
  root: view.container,
730
- pending: () => requests.pending,
775
+ pending: SubscriptionRef.changes(requests.pending),
731
776
  tell: story.tell,
732
777
  });
733
778
  ```
@@ -744,18 +789,24 @@ yield* screen.settle();
744
789
  expect(screen.text("output")).toBe("Saved title");
745
790
  ```
746
791
 
747
- This form of `settle()` observes client activity changes and flushes the renderer before returning. Finite RPC calls, coalesced invalidations and refreshing query atoms all keep it waiting; subscription streams themselves do not. With client activity, `find()` settles before looking up its target once. Keep live coalescing enabled. `nextLiveHint()` waits for the next subscription update received after the verb starts, including initial or resync updates; it does not wait for a refresh. Start the wait before another viewer writes, then settle before reading the resulting screen. It needs client activity; a callback-only driver fails with `MissingClientActivity`.
792
+ This form of `settle()` observes client activity changes and flushes the renderer before returning. Finite RPC calls, coalesced invalidations and refreshing query atoms all keep it waiting; subscription streams themselves do not. `find()` waits for idle client activity and a matching target, including a target rendered by a later DOM mutation. Keep live coalescing enabled. `nextLiveHint()` waits for the next subscription update received after the verb starts, including initial or resync updates; it does not wait for a refresh. Start the wait before another viewer writes, then settle before reading the resulting screen. It needs client activity; a callback-only driver fails with `MissingClientActivity`.
748
793
 
749
- `click(selector)`, `enter(selector, value)` and `submit(selector = "form")` return Effects. Selectors identify exactly one descendant of the root; missing or ambiguous controls fail. Hidden targets and targets inside hidden ancestors refuse actions and readouts. Text entry focuses an input or textarea and dispatches input and change events. Disabled controls refuse clicks and entry, inert ancestors also prevent form submission, and read-only fields refuse entry. Actions do not wait for settlement, so a story can release a held request before calling `settle()`.
794
+ `click(selector)`, `enter(selector, value)`, `select(selector, value)` and `submit(selector = "form")` return Effects. Selectors identify exactly one descendant of the root or a dialog portalled into its document; missing or ambiguous controls fail. Hidden targets and targets inside hidden ancestors refuse actions and readouts. Text entry focuses an input or textarea and dispatches input and change events. Select focuses a native `<select>`, sets an available option value and dispatches change inside `act`. Disabled controls refuse clicks, entry and selection, inert ancestors also prevent form submission, and read-only fields refuse entry. Actions do not wait for settlement, so a story can release a held request before calling `settle()`.
750
795
 
751
- `within(container)` returns the same driver scoped to that container, including nested `within` calls. Pass a selector, a role/name target or an `HTMLElement`. Selector and role containers must resolve to one rendered descendant and use the usual missing or ambiguous target diagnostics. For example, `within({ role: "region", name: "Billing" }).click({ role: "button", name: "Save" })` can address a Save button when Delivery has an identical button. Settlement keeps the original pending signal and error type.
796
+ `within(container)` returns the same driver scoped to that container, including nested `within` calls. Pass a selector, a role/name target or an `HTMLElement`. Selector and role containers must resolve to one rendered descendant and use the usual missing or ambiguous target diagnostics. For example, `within({ role: "region", name: "Billing" }).click({ role: "button", name: "Save" })` can address a Save button when Delivery has an identical button. A scoped driver searches only that container, including when the container is a portalled dialog. Settlement keeps the original pending signal and error type.
752
797
 
753
- `text(selector?)` concatenates visible HTML text nodes from the selected element or the whole root, without CSS text transforms or layout line breaks. `value(selector)` returns the current input or textarea value. Both narrate what they read through `tell` and leave assertions to the spec. Entry narration omits the supplied value.
798
+ `text(selector?)` reads visible HTML text from the selected element or the whole root. Block boundaries (using CSS display) and `<br>` separate adjacent text with a newline when there is no existing whitespace; inline text, including emphasis, stays joined. A card's title, message and action read as separate parts. Text transforms and layout wrapping are not applied. `value(selector)` returns the current input or textarea value. Both narrate what they read through `tell` and leave assertions to the spec. Entry narration omits the supplied value.
754
799
 
755
- `click`, `enter`, `submit`, `text` and `value` also accept a `ScreenTarget` object such as `{ role: "button", name: "Save" }` or `{ role: "textbox", name: /email/i }`. The role and computed accessible name must match exactly when strings are used; regular expressions match the name. Like Testing Library's role queries, these targets exclude hidden elements, including `aria-hidden` ancestors. Missing or ambiguous targets fail with the requested role, name and the visible candidates on screen. Narration names the role and name instead of a selector.
800
+ `click`, `enter`, `select`, `submit`, `text` and `value` also accept a `ScreenTarget` object such as `{ role: "button", name: "Save" }` or `{ role: "textbox", name: /email/i }`. The role and computed accessible name must match exactly when strings are used; regular expressions match the name. An alert without an accessible name can instead match its visible text. Like Testing Library's role queries, these targets exclude hidden elements, including `aria-hidden` ancestors. Missing or ambiguous targets fail with the requested role, name and the visible candidates on screen. Narration names the role and name instead of a selector.
756
801
 
757
802
  `find(target, { timeout }?)` returns an Effect that waits for exactly one matching rendered element and returns that `HTMLElement`. It accepts the same selectors and role/name targets as the actions, narrates the lookup, and uses the driver's live-time `timeoutMs` limit unless `timeout` overrides it in milliseconds. If no unique element appears before the limit, it fails with the same target diagnostics as the actions, including visible candidates for role/name targets.
758
803
 
804
+ `findText(text, { timeout }?)` waits for one visible element with matching text, returning the deepest matching `HTMLElement`. Strings match exactly after whitespace normalization; regular expressions also work. Inline markup stays joined and hidden text is excluded. Separate visible matches are ambiguous, and a timeout names the text being awaited.
805
+
806
+ `gone(target, { timeout }?)` waits until no rendered element matches the selector or role/name target. It accepts an already absent target and observes removal and hiding through DOM mutations, without polling. Like `find`, both waits also observe a supplied pending signal and wait until it is idle.
807
+
808
+ `navigatedAway(prefix, { timeout }?)` waits until the document's URL starts with the expected destination prefix, such as `https://identity.example/authorize`. It accepts navigation that already happened and observes happy-dom location assignment, including `assign` and `replace`, without polling or waiting for app work to settle. A timeout reports the prefix and current URL. The temporary location observer is released on completion, timeout or interruption. These waits use the driver's `timeoutMs` unless a per-call `timeout` overrides it.
809
+
759
810
  `accessible(selector)` returns `{ name, role }` computed by `dom-accessibility-api`, including native roles and label references that take precedence over `aria-label`. It narrates the readout and uses the same single rendered target checks as other readouts. Assert on this result when checking a control's accessible name; reading its raw attributes does not compute that name. This DOM computation does not inspect a browser's accessibility tree or prove speech from a screen reader.
760
811
 
761
812
  `accessible(element)` uses the same computation on an `Element` the kit already holds and tells no story line.
@@ -783,22 +834,24 @@ A story calls `const hints = yield* watchHints()` before the write, then `yield*
783
834
 
784
835
  Import each module with the prefix `@shivaedev/test-story/`; there is no root entry.
785
836
 
786
- | Module | Exports |
787
- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
788
- | `server/storyKit.ts` | `storyKit`, `Trait`, `RunUntilOptions`, `Story`, `RunHooks`, `StoryKitDefinition`, `Told`, `StoryBody`, `StoryTest`, `StoryIt`, `StoryKit` |
789
- | `server/outcomes.ts` | `outcomes(rows)` |
790
- | `server/browserReads.ts` | `browserReads(options)`, `BrowserReadsOptions`, `BrowserRead`, `BrowserSubscription` |
791
- | `server/domFetch.ts` | `domFetch(baseUrl, target?)` |
792
- | `server/seedCookies.ts` | `seedCookies(cookies, target?)`, `DomCookie` |
793
- | `server/routeOutbound.ts` | `routeOutbound(routes)` |
794
- | `server/screenDriver.ts` | `screenDriver(options)`, `ScreenDriverOptions`, `ScreenDriver`, `ScreenTarget`, `MissingScreenPending` |
795
- | `server/memberScreens.ts` | `memberScreens(options)`, `MemberScreen` |
796
- | `server/domNavigate.ts` | `domNavigate(url?)` |
797
- | `server/genreTags.ts` | `genreTags(...kitNames)`, `GenreTag` |
798
- | `server/domEnvironment.config.ts` | Default Vitest environment preserving Node host globals and happy-dom document transport |
799
- | `server/fakeHttpService.ts` | `fakeHttpService(options)`, `FakeHttpRoute`, `FakeHttpRequest`, `FakeHttpRequestRecord` (`status`: number, `"pending"` or `"unanswered"`), `FakeHttpReply`, `FakeHttpReplySource` (fixed or request/time function), `FakeHttpFault`, `FakeHttpHold`, `FakeHttpHoldOptions` (`params`, `once`), `FakeHttpScope`, `FakeHttpScriptOptions`, `FakeHttpScript`, `FakeHttpServiceOptions` |
800
- | `server/forwardingProxy.ts` | `forwardingProxy(upstream, options?)`, `ForwardingProxyOptions` |
801
- | `server/otlpReceiver.ts` | `otlpReceiver(options?)`, `OtlpSpan`, `OtlpExport`, `OtlpReceiverOptions` |
837
+ | Module | Exports |
838
+ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
839
+ | `server/storyKit.ts` | `storyKit`, `Trait`, `RunUntilOptions`, `Story`, `RunHooks`, `StoryKitDefinition`, `Told`, `StoryBody`, `StoryTest`, `StoryIt`, `StoryKit` |
840
+ | `server/adapters/outcomeMatchers.ts` | `lessThan(limit)`, `atMost(limit)`, `greaterThan(limit)`, `atLeast(limit)`, `NumericBound` |
841
+ | `server/outcomes.ts` | `outcomes(rows)` |
842
+ | `server/until.ts` | `until(stream, matches, options)`, `collectUntil(stream, matches, options)`, `UntilOptions`, `SignalNotReceived` |
843
+ | `server/browserReads.ts` | `browserReads(options)`, `BrowserReadsOptions`, `BrowserRead`, `BrowserSubscription` |
844
+ | `server/domFetch.ts` | `domFetch(baseUrl, target?)` |
845
+ | `server/seedCookies.ts` | `seedCookies(cookies, target?)`, `DomCookie` |
846
+ | `server/routeOutbound.ts` | `routeOutbound(routes)` |
847
+ | `server/screenDriver.ts` | `screenDriver(options)`, `ScreenDriverOptions`, `ScreenDriver`, `ScreenTarget`, `MissingScreenPending` |
848
+ | `server/memberScreens.ts` | `memberScreens(options)`, `MemberScreen` |
849
+ | `server/domNavigate.ts` | `domNavigate(url?)` |
850
+ | `server/genreTags.ts` | `genreTags(...kitNames)`, `GenreTag` |
851
+ | `server/domEnvironment.config.ts` | Default Vitest environment preserving Node host globals and happy-dom document transport |
852
+ | `server/fakeHttpService.ts` | `fakeHttpService(options)`, `FakeHttpRoute`, `FakeHttpRequest`, `FakeHttpRequestRecord` (`status`: number, `"pending"` or `"unanswered"`), `FakeHttpReply`, `FakeHttpReplySource` (fixed or request/time function), `FakeHttpFault`, `FakeHttpHold`, `FakeHttpHoldOptions` (`params`, `once`), `FakeHttpScope`, `FakeHttpScriptOptions`, `FakeHttpScript`, `FakeHttpServiceOptions` |
853
+ | `server/forwardingProxy.ts` | `forwardingProxy(upstream, options?)`, `ForwardingProxyOptions` |
854
+ | `server/otlpReceiver.ts` | `otlpReceiver(options?)`, `OtlpSpan`, `OtlpExport`, `OtlpReceiverOptions` |
802
855
 
803
856
  ### Install and limits
804
857
 
@@ -812,6 +865,6 @@ Test-story is an application's one test dependency: it brings [`@shivaedev/test`
812
865
  - The package runs inside Vitest. The story reaches the failure by rewriting the first error's message in Vitest's `onTestFailed` hook.
813
866
  - Layer acquisition and engine creation failures precede that hook and carry no story appendix. A printed rerun command still needs a Vitest configuration that collects its file.
814
867
  - A kit's `it` is created when the kit is defined, so a kit lives in a module that only Vitest test files import.
815
- - `inspect` runs after the test has failed, so it reads the engine synchronously.
868
+ - `inspect` runs when the story fails, before its Scope closes. Plain functions, generators and functions returning an Effect are supported.
816
869
  - The spec line under the `✗` is found by matching the spec's path in the failure's stack, or else in the call site of the last line the story told or the last `runUntil`. A failure raised inside an Effect that the spec does not call directly may have none.
817
870
  - The package is built for ShivaeDev applications and may change without a deprecation period.
@@ -0,0 +1,12 @@
1
+ export interface NumericBound {
2
+ readonly $$typeof: symbol;
3
+ readonly asymmetricMatch: (actual: unknown) => boolean;
4
+ readonly getExpectedType: () => string;
5
+ readonly toAsymmetricMatcher: () => string;
6
+ readonly toString: () => string;
7
+ }
8
+ export declare function lessThan(limit: number): NumericBound;
9
+ export declare function atMost(limit: number): NumericBound;
10
+ export declare function greaterThan(limit: number): NumericBound;
11
+ export declare function atLeast(limit: number): NumericBound;
12
+ //# sourceMappingURL=outcomeMatchers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"outcomeMatchers.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/outcomeMatchers.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACvD,QAAQ,CAAC,eAAe,EAAE,MAAM,MAAM,CAAC;IACvC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,MAAM,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAC;CAChC;AAYD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,gBAErC;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,gBAEnC;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,gBAExC;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,gBAEpC"}
@@ -0,0 +1,22 @@
1
+ function bound(name, limit, compare) {
2
+ return {
3
+ $$typeof: Symbol.for("jest.asymmetricMatcher"),
4
+ asymmetricMatch: (actual) => typeof actual === "number" && compare(actual, limit),
5
+ getExpectedType: () => "number",
6
+ toAsymmetricMatcher: () => `${name}(${limit})`,
7
+ toString: () => name,
8
+ };
9
+ }
10
+ export function lessThan(limit) {
11
+ return bound("lessThan", limit, (actual, value) => actual < value);
12
+ }
13
+ export function atMost(limit) {
14
+ return bound("atMost", limit, (actual, value) => actual <= value);
15
+ }
16
+ export function greaterThan(limit) {
17
+ return bound("greaterThan", limit, (actual, value) => actual > value);
18
+ }
19
+ export function atLeast(limit) {
20
+ return bound("atLeast", limit, (actual, value) => actual >= value);
21
+ }
22
+ //# sourceMappingURL=outcomeMatchers.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"outcomeMatchers.js","sourceRoot":"","sources":["../../../src/server/adapters/outcomeMatchers.ts"],"names":[],"mappings":"AAQA,SAAS,KAAK,CAAC,IAAY,EAAE,KAAa,EAAE,OAAmD;IAC9F,OAAO;QACN,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC;QAC9C,eAAe,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC;QACjF,eAAe,EAAE,GAAG,EAAE,CAAC,QAAQ;QAC/B,mBAAmB,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,IAAI,KAAK,GAAG;QAC9C,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI;KACpB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAa;IACrC,OAAO,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,KAAa;IACnC,OAAO,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAa;IACxC,OAAO,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAa;IACpC,OAAO,KAAK,CAAC,SAAS,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC;AACpE,CAAC"}
@@ -1,11 +1,15 @@
1
+ import { screenText } from "#internal/screenText.ts";
1
2
  import type { ScreenTarget } from "#screenDriver.ts";
2
- export declare function screenElements(root: () => HTMLElement): {
3
+ export declare function screenElements(root: () => HTMLElement, dialogs?: boolean): {
3
4
  element: (selector: ScreenTarget) => HTMLElement;
4
5
  enabled: (found: HTMLElement, selector: ScreenTarget) => void;
5
6
  enter: (selector: ScreenTarget, value: string) => void;
6
7
  form: (selector: ScreenTarget) => HTMLFormElement;
7
8
  input: (selector: ScreenTarget) => HTMLInputElement | HTMLTextAreaElement;
9
+ matches: (target: ScreenTarget) => HTMLElement[];
8
10
  rendered: (found: HTMLElement, selector: string) => HTMLElement;
9
- text: (found: HTMLElement) => string;
11
+ select: (selector: ScreenTarget, value: string) => void;
12
+ text: typeof screenText;
13
+ textElement: (text: string | RegExp) => HTMLElement;
10
14
  };
11
15
  //# sourceMappingURL=screenElements.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"screenElements.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/screenElements.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGrD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,WAAW,EAAE,OAAO,UAAO;wBAQ1C,YAAY;qBAsBf,WAAW,YAAY,YAAY;sBAQxC,YAAY,SAAS,MAAM;qBAY5B,YAAY;sBA7BL,YAAY;;sBAnBZ,WAAW,YAAY,MAAM;uBA2DlC,YAAY,SAAS,MAAM;;;EAgB/C"}
@@ -1,5 +1,8 @@
1
- import { isRendered, roleElement, targetName } from "#internal/screenAccessibility.ts";
2
- export function screenElements(root) {
1
+ import { isRendered, targetName } from "#internal/screenAccessibility.ts";
2
+ import { screenText } from "#internal/screenText.ts";
3
+ import { screenQueries } from "./screenQueries.js";
4
+ export function screenElements(root, dialogs = true) {
5
+ const queries = screenQueries(root, dialogs);
3
6
  function rendered(found, selector) {
4
7
  if (!isRendered(found)) {
5
8
  throw new Error(`The screen's ${selector} is not rendered.\nhelp: Reveal the target and its ancestors before acting on or reading it.`);
@@ -8,9 +11,9 @@ export function screenElements(root) {
8
11
  }
9
12
  function element(selector) {
10
13
  if (typeof selector !== "string") {
11
- return roleElement(root(), selector);
14
+ return queries.roleElement(selector);
12
15
  }
13
- const matches = root().querySelectorAll(selector);
16
+ const matches = queries.query(selector);
14
17
  const found = matches[0];
15
18
  if (matches.length !== 1 || found === undefined) {
16
19
  throw new Error(`The screen has ${matches.length} matches for ${JSON.stringify(selector)}.\nhelp: Use a selector for exactly one rendered control or readout.`);
@@ -29,16 +32,6 @@ export function screenElements(root) {
29
32
  throw new Error(`The screen's ${targetName(selector)} is disabled.\nhelp: Wait for the app to enable the control before acting on it.`);
30
33
  }
31
34
  }
32
- function text(found) {
33
- const walker = found.ownerDocument.createTreeWalker(found, NodeFilter.SHOW_TEXT);
34
- const parts = [];
35
- for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
36
- if (node.parentElement instanceof HTMLElement && isRendered(node.parentElement)) {
37
- parts.push(node.textContent ?? "");
38
- }
39
- }
40
- return parts.join("");
41
- }
42
35
  return {
43
36
  element,
44
37
  enabled,
@@ -63,8 +56,23 @@ export function screenElements(root) {
63
56
  return found;
64
57
  },
65
58
  input,
59
+ matches: queries.matches,
66
60
  rendered,
67
- text,
61
+ select: (selector, value) => {
62
+ const field = element(selector);
63
+ if (!(field instanceof HTMLSelectElement)) {
64
+ throw new Error(`The screen's ${targetName(selector)} is not a select.\nhelp: Select a rendered select control.`);
65
+ }
66
+ enabled(field, selector);
67
+ if (!Array.from(field.options).some((option) => option.value === value)) {
68
+ throw new Error(`The screen's ${targetName(selector)} has no option ${JSON.stringify(value)}.\nhelp: Choose an available option value.`);
69
+ }
70
+ field.focus();
71
+ field.value = value;
72
+ field.dispatchEvent(new Event("change", { bubbles: true }));
73
+ },
74
+ text: screenText,
75
+ textElement: queries.textElement,
68
76
  };
69
77
  }
70
78
  //# sourceMappingURL=screenElements.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"screenElements.js","sourceRoot":"","sources":["../../../src/server/adapters/screenElements.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,3 @@
1
+ import { Effect } from "effect";
2
+ export declare function screenMutations(root: HTMLElement, changed: () => void): Effect.Effect<MutationObserver, never, import("effect/Scope").Scope>;
3
+ //# sourceMappingURL=screenMutations.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"screenMutations.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/screenMutations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,IAAI,wEAWrE"}
@@ -0,0 +1,11 @@
1
+ import { Effect } from "effect";
2
+ export function screenMutations(root, changed) {
3
+ return Effect.acquireRelease(Effect.sync(() => {
4
+ const observer = new MutationObserver(changed);
5
+ // Root getters can follow navigation, and visibility can change on an ancestor.
6
+ observer.observe(root.ownerDocument, { attributes: true, characterData: true, childList: true, subtree: true });
7
+ observer.observe(root, { attributes: true, characterData: true, childList: true, subtree: true });
8
+ return observer;
9
+ }), (observer) => Effect.sync(() => observer.disconnect()));
10
+ }
11
+ //# sourceMappingURL=screenMutations.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"screenMutations.js","sourceRoot":"","sources":["../../../src/server/adapters/screenMutations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,UAAU,eAAe,CAAC,IAAiB,EAAE,OAAmB;IACrE,OAAO,MAAM,CAAC,cAAc,CAC3B,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;QAChB,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAC/C,gFAAgF;QAChF,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAChH,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAClG,OAAO,QAAQ,CAAC;IACjB,CAAC,CAAC,EACF,CAAC,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC,CACtD,CAAC;AACH,CAAC"}
@@ -0,0 +1,3 @@
1
+ import { Effect } from "effect";
2
+ export declare function screenNavigation(root: () => HTMLElement, prefix: string): Effect.Effect<void, never, never>;
3
+ //# sourceMappingURL=screenNavigation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"screenNavigation.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/screenNavigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,WAAW,EAAE,MAAM,EAAE,MAAM,qCAkCvE"}
@@ -0,0 +1,34 @@
1
+ import { Effect } from "effect";
2
+ export function screenNavigation(root, prefix) {
3
+ return Effect.suspend(() => {
4
+ const location = root().ownerDocument.location;
5
+ const original = Object.getOwnPropertyDescriptor(location, "href");
6
+ const descriptor = original ?? Object.getOwnPropertyDescriptor(Object.getPrototypeOf(location), "href");
7
+ const wait = Effect.callback((resume) => {
8
+ function changed() {
9
+ if (location.href.startsWith(prefix)) {
10
+ resume(Effect.void);
11
+ }
12
+ }
13
+ // happy-dom's detached window changes location without emitting a navigation event.
14
+ Object.defineProperty(location, "href", {
15
+ configurable: true,
16
+ get: () => descriptor?.get?.call(location),
17
+ set: (value) => {
18
+ descriptor?.set?.call(location, value);
19
+ changed();
20
+ },
21
+ });
22
+ changed();
23
+ });
24
+ return wait.pipe(Effect.ensuring(Effect.sync(() => {
25
+ if (original) {
26
+ Object.defineProperty(location, "href", original);
27
+ }
28
+ else {
29
+ Reflect.deleteProperty(location, "href");
30
+ }
31
+ })));
32
+ });
33
+ }
34
+ //# sourceMappingURL=screenNavigation.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"screenNavigation.js","sourceRoot":"","sources":["../../../src/server/adapters/screenNavigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,UAAU,gBAAgB,CAAC,IAAuB,EAAE,MAAc;IACvE,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;QAC1B,MAAM,QAAQ,GAAG,IAAI,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC;QAC/C,MAAM,QAAQ,GAAG,MAAM,CAAC,wBAAwB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACnE,MAAM,UAAU,GAAG,QAAQ,IAAI,MAAM,CAAC,wBAAwB,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;QACxG,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAO,CAAC,MAAM,EAAE,EAAE;YAC7C,SAAS,OAAO;gBACf,IAAI,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;oBACtC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBACrB,CAAC;YACF,CAAC;YACD,oFAAoF;YACpF,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE;gBACvC,YAAY,EAAE,IAAI;gBAClB,GAAG,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC;gBAC1C,GAAG,EAAE,CAAC,KAAa,EAAE,EAAE;oBACtB,UAAU,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;oBACvC,OAAO,EAAE,CAAC;gBACX,CAAC;aACD,CAAC,CAAC;YACH,OAAO,EAAE,CAAC;QACX,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,IAAI,CACf,MAAM,CAAC,QAAQ,CACd,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;YAChB,IAAI,QAAQ,EAAE,CAAC;gBACd,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;YACnD,CAAC;iBAAM,CAAC;gBACP,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC1C,CAAC;QACF,CAAC,CAAC,CACF,CACD,CAAC;IACH,CAAC,CAAC,CAAC;AACJ,CAAC"}
@@ -0,0 +1,8 @@
1
+ import type { ScreenTarget } from "#screenDriver.ts";
2
+ export declare function screenQueries(root: () => HTMLElement, dialogs: boolean): {
3
+ matches: (target: ScreenTarget) => HTMLElement[];
4
+ query: (selector: string) => HTMLElement[];
5
+ roleElement: (target: Exclude<ScreenTarget, string>) => HTMLElement;
6
+ textElement: (text: string | RegExp) => HTMLElement;
7
+ };
8
+ //# sourceMappingURL=screenQueries.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"screenQueries.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/screenQueries.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAMrD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,WAAW,EAAE,OAAO,EAAE,OAAO;sBAgCnD,YAAY;sBA/BN,MAAM;0BAoCR,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC;wBAa/B,MAAM,GAAG,MAAM;EAepC"}
@@ -0,0 +1,62 @@
1
+ import { isInaccessible } from "dom-accessibility-api";
2
+ import { accessibility, isRendered, targetName } from "#internal/screenAccessibility.ts";
3
+ import { screenText } from "#internal/screenText.ts";
4
+ function matchesText(value, expected) {
5
+ return typeof expected === "string" ? value === expected : new RegExp(expected.source, expected.flags).test(value);
6
+ }
7
+ export function screenQueries(root, dialogs) {
8
+ function query(selector) {
9
+ const current = root();
10
+ const found = new Set(current.querySelectorAll(selector));
11
+ const portals = dialogs
12
+ ? [...current.ownerDocument.querySelectorAll('dialog,[role="dialog"],[role="alertdialog"]')].filter((dialog) => !current.contains(dialog))
13
+ : [];
14
+ for (const dialog of portals) {
15
+ if (dialog.matches(selector)) {
16
+ found.add(dialog);
17
+ }
18
+ for (const child of dialog.querySelectorAll(selector)) {
19
+ found.add(child);
20
+ }
21
+ }
22
+ return [...found];
23
+ }
24
+ function candidates() {
25
+ return query("*")
26
+ .filter((element) => isRendered(element) && !isInaccessible(element))
27
+ .map((element) => {
28
+ const { role, name } = accessibility(element);
29
+ return { element, name: role === "alert" && name === "" ? screenText(element).replace(/\s+/gu, " ").trim() : name, role };
30
+ })
31
+ .filter(({ role }) => role !== null);
32
+ }
33
+ function roles(target) {
34
+ return candidates().filter(({ role, name }) => role === target.role && matchesText(name, target.name));
35
+ }
36
+ return {
37
+ matches: (target) => (typeof target === "string" ? query(target).filter(isRendered) : roles(target).map(({ element }) => element)).filter((element) => element.isConnected),
38
+ query,
39
+ roleElement: (target) => {
40
+ const matches = roles(target);
41
+ const found = matches[0];
42
+ if (matches.length === 1 && found) {
43
+ return found.element;
44
+ }
45
+ const listing = candidates()
46
+ .map(({ role, name }) => ` - ${role} named ${JSON.stringify(name)}`)
47
+ .join("\n");
48
+ throw new Error(`The screen has ${matches.length} matches for ${targetName(target)}.\nhelp: Use a role and name for exactly one visible target.\nCandidates on screen:\n${listing || " (none)"}`);
49
+ },
50
+ textElement: (text) => {
51
+ const current = root();
52
+ const matches = [current, ...query("*")].filter((element) => isRendered(element) && matchesText(screenText(element).replace(/\s+/gu, " ").trim(), text));
53
+ const deepest = matches.filter((element) => !matches.some((other) => element !== other && element.contains(other)));
54
+ const found = deepest[0];
55
+ if (deepest.length !== 1 || found === undefined) {
56
+ throw new Error(`The screen has ${deepest.length} matches for text ${String(text instanceof RegExp ? text : JSON.stringify(text))}.\nhelp: Use text that identifies exactly one visible element.`);
57
+ }
58
+ return found;
59
+ },
60
+ };
61
+ }
62
+ //# sourceMappingURL=screenQueries.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"screenQueries.js","sourceRoot":"","sources":["../../../src/server/adapters/screenQueries.ts"],"names":[],"mappings":"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"}
@@ -1 +1 @@
1
- {"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../../src/server/internal/compose.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,+BAA+B,CAAC;AAG5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,eAAe,CAsCpE"}
1
+ {"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../../src/server/internal/compose.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,+BAA+B,CAAC;AAG5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,eAAe,CA0CpE"}