@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
@@ -19,10 +19,12 @@ export type InferredDefinition<
19
19
  TStep extends AnyEffect,
20
20
  TFailed extends AnyEffect,
21
21
  TDiagnose extends AnyEffect,
22
+ TInspect extends (engine: HookValue<ReturnType<TCreate>>) => unknown,
22
23
  > = Omit<
23
24
  StoryKitDefinition<HookValue<ReturnType<TCreate>>, TStage, TVerbs, TProvided, never, Record<never, never>, TStep, TFailed, TDiagnose>,
24
- "create" | "after"
25
+ "create" | "after" | "inspect"
25
26
  > & {
26
27
  readonly create: TCreate;
28
+ readonly inspect?: TInspect;
27
29
  readonly after?: { readonly [TKey in keyof TAfter]: (engine: HookValue<ReturnType<TCreate>>) => TAfter[TKey] };
28
- } & LayerFor<HookEffects<ReturnType<TCreate> | TAfter[keyof TAfter]> | TStep | TFailed | TDiagnose, TProvided>;
30
+ } & LayerFor<HookEffects<ReturnType<TCreate> | TAfter[keyof TAfter]> | TStep | TFailed | TDiagnose | HookEffects<ReturnType<TInspect>>, TProvided>;
@@ -1,6 +1,8 @@
1
+ import { Cause, Effect } from "effect";
1
2
  import type { TestContext } from "vitest";
2
3
  import { callSite } from "#internal/callSite.ts";
3
4
  import { failureReport } from "#internal/failureReport.ts";
5
+ import { hooked } from "#internal/hooked.ts";
4
6
  import { describeFailure } from "#internal/render.ts";
5
7
 
6
8
  export interface Refusal {
@@ -22,6 +24,7 @@ export interface Subject<TEngine> {
22
24
  readonly engine: TEngine;
23
25
  readonly inspect: ((engine: TEngine) => unknown) | undefined;
24
26
  readonly name: string;
27
+ readonly snapshot?: { readonly value: unknown } | { readonly threw: unknown };
25
28
  }
26
29
 
27
30
  export function narrate<TEngine>(subject: Subject<TEngine>, { onTestFailed, task }: Pick<TestContext, "onTestFailed" | "task">) {
@@ -48,9 +51,18 @@ export function narrate<TEngine>(subject: Subject<TEngine>, { onTestFailed, task
48
51
  }
49
52
  });
50
53
  return {
51
- captureFailure: (stack: string | undefined) => {
52
- captured = failureReport(narration, subject, { file: task.file.filepath, name: task.name, stack });
53
- },
54
+ captureFailure: (stack: string | undefined) =>
55
+ hooked(() => (subject.inspect === undefined ? subject.engine : subject.inspect(subject.engine))).pipe(
56
+ Effect.matchCause({
57
+ onFailure: (cause) => ({ threw: Cause.squash(cause) }),
58
+ onSuccess: (value) => ({ value }),
59
+ }),
60
+ Effect.tap((snapshot) =>
61
+ Effect.sync(() => {
62
+ captured = failureReport(narration, { ...subject, snapshot }, { file: task.file.filepath, name: task.name, stack });
63
+ }),
64
+ ),
65
+ ),
54
66
  narration,
55
67
  };
56
68
  }
@@ -1,9 +1,5 @@
1
1
  import { Effect, Stream } from "effect";
2
- import { type ClientActivity, isClientIdle } from "@shivaedev/contract/clientActivity.ts";
3
-
4
- export function waitForClient(activity: ClientActivity) {
5
- return activity.pipe(Stream.filter(isClientIdle), Stream.take(1), Stream.runDrain);
6
- }
2
+ import type { ClientActivity } from "@shivaedev/contract/clientActivity.ts";
7
3
 
8
4
  export const nextClientHint = Effect.fnUntraced(function* (activity: ClientActivity) {
9
5
  const before = (yield* activity.current).liveHints;
@@ -1,4 +1,4 @@
1
- import { computeAccessibleName, getRole, isInaccessible } from "dom-accessibility-api";
1
+ import { computeAccessibleName, getRole } from "dom-accessibility-api";
2
2
  import type { ScreenTarget } from "#screenDriver.ts";
3
3
 
4
4
  export function accessibility(element: Element) {
@@ -24,27 +24,3 @@ export function isRendered(found: HTMLElement) {
24
24
  }
25
25
  return true;
26
26
  }
27
-
28
- export function roleElement(root: HTMLElement, target: Exclude<ScreenTarget, string>) {
29
- const candidates = Array.from(root.querySelectorAll<HTMLElement>("*"))
30
- .filter((element) => isRendered(element) && !isInaccessible(element))
31
- .map((element) => ({ ...accessibility(element), element }))
32
- .filter(({ role }) => role !== null);
33
- const matches = candidates.filter(({ role, name }) => {
34
- if (role !== target.role) {
35
- return false;
36
- }
37
- if (typeof target.name === "string") {
38
- return name === target.name;
39
- }
40
- return new RegExp(target.name.source, target.name.flags).test(name);
41
- });
42
- const found = matches[0];
43
- if (matches.length === 1 && found) {
44
- return found.element;
45
- }
46
- const listing = candidates.map(({ role, name }) => ` - ${role} named ${JSON.stringify(name)}`).join("\n");
47
- throw new Error(
48
- `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
- }
@@ -1,9 +1,9 @@
1
+ import { screenElements } from "#adapters/screenElements.ts";
1
2
  import type { ScreenTarget } from "#screenDriver.ts";
2
3
  import { accessibility, targetName } from "./screenAccessibility.ts";
3
- import { screenElements } from "./screenElements.ts";
4
4
 
5
- export function screenReadouts(currentRoot: () => HTMLElement, tell: (line: string) => void) {
6
- const elements = screenElements(currentRoot);
5
+ export function screenReadouts(currentRoot: () => HTMLElement, tell: (line: string) => void, dialogs = true) {
6
+ const elements = screenElements(currentRoot, dialogs);
7
7
  return {
8
8
  accessible: (selector: string | Element) => {
9
9
  if (typeof selector !== "string") {
@@ -0,0 +1,41 @@
1
+ import { isRendered } from "./screenAccessibility.ts";
2
+
3
+ const blockDisplays = new Set(["block", "flow-root", "flex", "grid", "list-item", "table", "table-row", "table-caption"]);
4
+
5
+ export function screenText(root: HTMLElement): string {
6
+ let text = "";
7
+ let boundary = false;
8
+ function append(node: Node) {
9
+ if (!(node.parentElement instanceof HTMLElement && isRendered(node.parentElement))) {
10
+ return;
11
+ }
12
+ const content = node.textContent ?? "";
13
+ if (content.length === 0) {
14
+ return;
15
+ }
16
+ if (boundary && text.length > 0 && !/\s$/u.test(text) && !/^\s/u.test(content)) {
17
+ text += "\n";
18
+ }
19
+ text += content;
20
+ boundary = false;
21
+ }
22
+ function visit(node: Node) {
23
+ if (node.nodeType === Node.TEXT_NODE) {
24
+ append(node);
25
+ return;
26
+ }
27
+ const rendered = node instanceof HTMLElement && isRendered(node);
28
+ const block = rendered && blockDisplays.has(getComputedStyle(node).display);
29
+ if (block || (rendered && node.tagName === "BR")) {
30
+ boundary = true;
31
+ }
32
+ for (const child of node.childNodes) {
33
+ visit(child);
34
+ }
35
+ if (block) {
36
+ boundary = true;
37
+ }
38
+ }
39
+ visit(root);
40
+ return text;
41
+ }
@@ -0,0 +1,105 @@
1
+ import { Effect } from "effect";
2
+ import { withLive } from "@shivaedev/test/withLive.ts";
3
+ import type { screenElements } from "#adapters/screenElements.ts";
4
+ import { screenNavigation } from "#adapters/screenNavigation.ts";
5
+ import type { ScreenDriverOptions, ScreenTarget } from "#screenDriver.ts";
6
+ import { targetName } from "./screenAccessibility.ts";
7
+ import { waitForScreen } from "./waitForScreen.ts";
8
+
9
+ type Options = Omit<ScreenDriverOptions, "act" | "root" | "timeoutMs" | "pending"> & {
10
+ readonly act: NonNullable<ScreenDriverOptions["act"]>;
11
+ readonly pending: ScreenDriverOptions["pending"];
12
+ readonly root: () => HTMLElement;
13
+ readonly timeoutMs: number;
14
+ };
15
+
16
+ export function screenWaits(options: Options, elements: ReturnType<typeof screenElements>) {
17
+ const { act, pending, root, tell, timeoutMs } = options;
18
+ function unsettled(limit: number) {
19
+ return new Error(
20
+ `The screen did not settle within ${limit}ms.\nhelp: Release held requests and check the app's pending signal and renderer act adapter.\nScreen: ${root().textContent}`,
21
+ );
22
+ }
23
+ function wait<A>(line: string, read: () => A, timeout: number, expired: () => Effect.Effect<A>) {
24
+ return withLive(
25
+ Effect.sync(() => tell(line)).pipe(
26
+ Effect.andThen(waitForScreen({ act, pending, root }, Effect.try(read))),
27
+ Effect.timeoutOrElse({ duration: timeout, orElse: expired }),
28
+ ),
29
+ );
30
+ }
31
+ return {
32
+ find: (target: ScreenTarget, settings: { readonly timeout?: number } = {}) => {
33
+ const limit = settings.timeout ?? timeoutMs;
34
+ return wait(
35
+ `find ${targetName(target)}`,
36
+ () => elements.element(target),
37
+ limit,
38
+ () => {
39
+ const lookup = Effect.sync(() => elements.element(target));
40
+ return pending === undefined ? lookup : lookup.pipe(Effect.andThen(Effect.die(unsettled(limit))));
41
+ },
42
+ );
43
+ },
44
+ findText: (text: string | RegExp, settings: { readonly timeout?: number } = {}) => {
45
+ const name = typeof text === "string" ? JSON.stringify(text) : String(text);
46
+ const limit = settings.timeout ?? timeoutMs;
47
+ return wait(
48
+ `find text ${name}`,
49
+ () => elements.textElement(text),
50
+ limit,
51
+ () =>
52
+ Effect.sync(() => elements.textElement(text)).pipe(
53
+ Effect.andThen(
54
+ Effect.die(new Error(`The screen did not finish waiting for text ${name} within ${limit}ms.\nhelp: Check the app's pending signal.`)),
55
+ ),
56
+ ),
57
+ );
58
+ },
59
+ gone: (target: ScreenTarget, settings: { readonly timeout?: number } = {}) => {
60
+ const limit = settings.timeout ?? timeoutMs;
61
+ function stillHere() {
62
+ return new Error(
63
+ `The screen did not lose ${targetName(target)} within ${limit}ms.\nhelp: Remove or hide every matching target and complete pending work.`,
64
+ );
65
+ }
66
+ return withLive(
67
+ Effect.sync(() => tell(`wait for ${targetName(target)} to disappear`)).pipe(
68
+ Effect.andThen(
69
+ waitForScreen(
70
+ { act, pending, root },
71
+ Effect.suspend(() => (elements.matches(target).length === 0 ? Effect.void : Effect.fail(stillHere()))),
72
+ ),
73
+ ),
74
+ Effect.timeoutOrElse({ duration: limit, orElse: () => Effect.die(stillHere()) }),
75
+ ),
76
+ );
77
+ },
78
+ navigatedAway: (prefix: string, settings: { readonly timeout?: number } = {}) => {
79
+ const limit = settings.timeout ?? timeoutMs;
80
+ function timedOut() {
81
+ return Effect.die(
82
+ new Error(
83
+ `The screen did not navigate to ${JSON.stringify(prefix)} within ${limit}ms.\nhelp: Trigger the redirect and check its destination.\nLocation: ${root().ownerDocument.location.href}`,
84
+ ),
85
+ );
86
+ }
87
+ return withLive(
88
+ Effect.sync(() => tell(`wait for navigation to ${JSON.stringify(prefix)}`)).pipe(
89
+ Effect.andThen(screenNavigation(root, prefix)),
90
+ Effect.timeoutOrElse({ duration: limit, orElse: timedOut }),
91
+ ),
92
+ );
93
+ },
94
+ settle: (settings: { readonly timeoutMs?: number } = {}) => {
95
+ const limit = settings.timeoutMs ?? timeoutMs;
96
+ return withLive(
97
+ Effect.sync(() => tell("wait for the screen's pending work")).pipe(
98
+ Effect.andThen(waitForScreen({ act, pending, root }, Effect.void)),
99
+ Effect.tap(() => Effect.sync(() => tell("the screen has no pending work"))),
100
+ Effect.timeoutOrElse({ duration: limit, orElse: () => Effect.die(unsettled(limit)) }),
101
+ ),
102
+ );
103
+ },
104
+ };
105
+ }
@@ -35,5 +35,5 @@ export const start = Effect.fnUntraced(function* (
35
35
  },
36
36
  ),
37
37
  );
38
- }).pipe(Effect.tapCause((cause) => Effect.sync(() => captureFailure(Cause.prettyErrors(cause)[0]?.stack))));
38
+ }).pipe(Effect.tapCause((cause) => captureFailure(Cause.prettyErrors(cause)[0]?.stack)));
39
39
  });
@@ -0,0 +1,48 @@
1
+ import { Effect, Queue, Result, Stream } from "effect";
2
+ import { isClientIdle } from "@shivaedev/contract/clientActivity.ts";
3
+ import { screenMutations } from "#adapters/screenMutations.ts";
4
+ import type { ScreenDriverOptions } from "#screenDriver.ts";
5
+
6
+ type WaitOptions = Required<Pick<ScreenDriverOptions, "act">> & {
7
+ readonly pending: ScreenDriverOptions["pending"];
8
+ readonly root: () => HTMLElement;
9
+ };
10
+
11
+ const observePending = Effect.fnUntraced(function* (pending: ScreenDriverOptions["pending"], changes: Queue.Queue<void>) {
12
+ if (pending === undefined) {
13
+ return Effect.succeed(false);
14
+ }
15
+ if (typeof pending === "function") {
16
+ return Effect.sync(pending);
17
+ }
18
+ let busy = true;
19
+ const states = "current" in pending ? Stream.map(pending, (state) => !isClientIdle(state)) : pending;
20
+ yield* states.pipe(
21
+ Stream.runForEach((value) =>
22
+ Effect.sync(() => {
23
+ busy = value;
24
+ Queue.offerUnsafe(changes, undefined);
25
+ }),
26
+ ),
27
+ Effect.forkScoped,
28
+ );
29
+ return "current" in pending ? Effect.map(pending.current, (state) => !isClientIdle(state)) : Effect.sync(() => busy);
30
+ });
31
+
32
+ export const waitForScreen = Effect.fnUntraced(function* <A, E>({ act, pending, root }: WaitOptions, read: Effect.Effect<A, E>) {
33
+ const changes = yield* Queue.sliding<void>(1);
34
+ yield* screenMutations(root(), () => Queue.offerUnsafe(changes, undefined));
35
+ const isBusy = yield* observePending(pending, changes);
36
+ do {
37
+ if (pending !== undefined) {
38
+ yield* Effect.promise(() => act(() => Promise.resolve()));
39
+ }
40
+ if (!(yield* isBusy)) {
41
+ const result = yield* Effect.result(read);
42
+ if (Result.isSuccess(result)) {
43
+ return result.success;
44
+ }
45
+ }
46
+ yield* pending === undefined ? Queue.take(changes) : Effect.promise((signal) => act(() => Effect.runPromise(Queue.take(changes), { signal })));
47
+ } while (true);
48
+ }, Effect.scoped);
@@ -1,21 +1,30 @@
1
1
  import { Effect } from "effect";
2
2
  import { type DeeplyAllowMatchers, expect } from "vitest";
3
+ import type { NumericBound } from "#adapters/outcomeMatchers.ts";
3
4
 
4
5
  type AnyReadout = Effect.Effect<unknown, unknown, unknown>;
6
+ type NativeMatcher = Exclude<DeeplyAllowMatchers<number>, number>;
7
+ type Expected<T> =
8
+ | NativeMatcher
9
+ | (T extends readonly unknown[]
10
+ ? { readonly [TKey in keyof T]: Expected<T[TKey]> }
11
+ : T extends object
12
+ ? { readonly [TKey in keyof T]?: Expected<T[TKey]> }
13
+ : T | (T extends number ? NumericBound : never));
5
14
 
6
15
  export const outcomes = Effect.fn("Story.outcomes")(check);
7
16
 
8
- function check<TReadouts extends Record<string, AnyReadout>>(
17
+ function check<TReadouts extends readonly AnyReadout[]>(
9
18
  rows: {
10
- readonly [TKey in keyof TReadouts]: readonly [TReadouts[TKey], DeeplyAllowMatchers<Effect.Success<NoInfer<TReadouts[TKey]>>>];
19
+ readonly [TKey in keyof TReadouts]: readonly [string, () => TReadouts[TKey], Expected<Effect.Success<NoInfer<TReadouts[TKey]>>>];
11
20
  },
12
- ): Effect.fn.Return<void, Effect.Error<TReadouts[keyof TReadouts]>, Effect.Services<TReadouts[keyof TReadouts]>>;
13
- function* check(rows: Readonly<Record<string, readonly [AnyReadout, unknown]>>) {
14
- const actual: Record<string, unknown> = {};
15
- const expected: Record<string, unknown> = {};
16
- for (const [label, [readout, value]] of Object.entries(rows)) {
17
- actual[label] = yield* readout;
18
- expected[label] = value;
21
+ ): Effect.fn.Return<void, Effect.Error<TReadouts[number]>, Effect.Services<TReadouts[number]>>;
22
+ function* check(rows: readonly (readonly [string, () => AnyReadout, unknown])[]) {
23
+ const actual: Record<string, unknown>[] = [];
24
+ const expected: Record<string, unknown>[] = [];
25
+ for (const [label, readout, value] of rows) {
26
+ actual.push({ [label]: yield* Effect.suspend(readout) });
27
+ expected.push({ [label]: value });
19
28
  }
20
- expect(actual).toEqual(expected);
29
+ expect(actual).toMatchObject(expected);
21
30
  }
@@ -1,16 +1,17 @@
1
- import { Data, Effect, Schedule } from "effect";
2
- import { type ClientActivity, isClientIdle } from "@shivaedev/contract/clientActivity.ts";
1
+ import { Data, Effect, type Stream } from "effect";
2
+ import type { ClientActivity } from "@shivaedev/contract/clientActivity.ts";
3
3
  import { withLive } from "@shivaedev/test/withLive.ts";
4
+ import { screenElements } from "#adapters/screenElements.ts";
5
+ import { nextClientHint } from "#internal/nextClientHint.ts";
4
6
  import { targetName } from "#internal/screenAccessibility.ts";
5
- import { nextClientHint, waitForClient } from "#internal/screenActivity.ts";
6
- import { screenElements } from "#internal/screenElements.ts";
7
7
  import { screenReadouts } from "#internal/screenReadouts.ts";
8
+ import { screenWaits } from "#internal/screenWaits.ts";
8
9
 
9
10
  export type ScreenTarget = string | { readonly role: string; readonly name: string | RegExp };
10
11
 
11
12
  export interface ScreenDriverOptions {
12
13
  readonly act?: (action: () => Promise<void>) => PromiseLike<void>;
13
- readonly pending?: (() => boolean) | ClientActivity;
14
+ readonly pending?: (() => boolean) | Stream.Stream<boolean> | ClientActivity;
14
15
  readonly root: HTMLElement | (() => HTMLElement);
15
16
  readonly tell: (line: string) => void;
16
17
  readonly timeoutMs?: number;
@@ -33,93 +34,42 @@ export type ScreenDriver<E = never, THintError = MissingClientActivity> = Omit<R
33
34
  };
34
35
 
35
36
  export function screenDriver(options: ScreenDriverOptions & { readonly pending: ClientActivity }): ScreenDriver<never, never>;
36
- export function screenDriver(options: ScreenDriverOptions & { readonly pending: () => boolean }): ScreenDriver;
37
+ export function screenDriver(options: ScreenDriverOptions & { readonly pending: (() => boolean) | Stream.Stream<boolean> }): ScreenDriver;
37
38
  export function screenDriver(options: ScreenDriverOptions): ScreenDriver<MissingScreenPending>;
38
39
  export function screenDriver(options: ScreenDriverOptions): ScreenDriver<MissingScreenPending> {
40
+ return makeDriver(options, true);
41
+ }
42
+
43
+ function makeDriver(options: ScreenDriverOptions, dialogs: boolean): ScreenDriver<MissingScreenPending> {
39
44
  const suppliedRoot = options.root;
40
45
  const root = typeof suppliedRoot === "function" ? suppliedRoot : () => suppliedRoot;
41
- const elements = screenElements(root);
46
+ const elements = screenElements(root, dialogs);
42
47
  return {
43
- ...makeScreenActions(options),
48
+ ...makeScreenActions(options, dialogs),
44
49
  within: (container) => {
45
50
  function scopedRoot() {
46
51
  return container instanceof HTMLElement ? elements.rendered(container, container.tagName.toLowerCase()) : elements.element(container);
47
52
  }
48
53
  scopedRoot();
49
- return screenDriver({ ...options, root: scopedRoot });
54
+ return makeDriver({ ...options, root: scopedRoot }, false);
50
55
  },
51
56
  };
52
57
  }
53
58
 
54
- function makeScreenActions({ root, pending, tell, act = (action) => action(), timeoutMs = 3000 }: ScreenDriverOptions) {
59
+ function makeScreenActions({ root, pending, tell, act = (action) => action(), timeoutMs = 3000 }: ScreenDriverOptions, dialogs: boolean) {
55
60
  const currentRoot = typeof root === "function" ? root : () => root;
56
- const elements = screenElements(currentRoot);
61
+ const elements = screenElements(currentRoot, dialogs);
62
+ const waits = screenWaits({ act, pending, root: currentRoot, tell, timeoutMs }, elements);
57
63
  function perform(line: string, action: () => void) {
58
64
  return Effect.promise(async () => {
59
65
  tell(line);
60
66
  await act(async () => action());
61
67
  });
62
68
  }
63
- function settle(options: { readonly timeoutMs?: number } = {}) {
64
- if (pending === undefined) {
65
- return Effect.fail(new MissingScreenPending());
66
- }
67
- return settleWork(pending, options);
68
- }
69
- function settleWork(work: NonNullable<ScreenDriverOptions["pending"]>, options: { readonly timeoutMs?: number }) {
70
- const limit = options.timeoutMs ?? timeoutMs;
71
- const isIdle = typeof work === "function" ? Effect.sync(() => !work()) : Effect.map(work.current, isClientIdle);
72
- const wait = Effect.gen(function* () {
73
- tell("wait for the screen's pending work");
74
- do {
75
- yield* Effect.promise(() => act(async () => undefined));
76
- if (yield* isIdle) {
77
- tell("the screen has no pending work");
78
- return;
79
- }
80
- yield* typeof work === "function"
81
- ? Effect.promise(() => act(() => new Promise<void>((resolve) => setTimeout(resolve, 10))))
82
- : Effect.promise((signal) => act(() => Effect.runPromise(waitForClient(work), { signal })));
83
- } while (true);
84
- });
85
- function timedOut() {
86
- return Effect.die(
87
- new Error(
88
- `The screen did not settle within ${limit}ms.\nhelp: Release held requests and check the app's pending signal and renderer act adapter.\nScreen: ${currentRoot().textContent}`,
89
- ),
90
- );
91
- }
92
- return withLive(wait.pipe(Effect.timeoutOrElse({ duration: limit, orElse: timedOut })));
93
- }
94
- function find(target: ScreenTarget, options: { readonly timeout?: number } = {}) {
95
- if (pending !== undefined && typeof pending !== "function") {
96
- return settleWork(pending, { timeoutMs: options.timeout ?? timeoutMs }).pipe(
97
- Effect.andThen(
98
- Effect.sync(() => {
99
- tell(`find ${targetName(target)}`);
100
- return elements.element(target);
101
- }),
102
- ),
103
- );
104
- }
105
- return withLive(
106
- Effect.gen(function* () {
107
- tell(`find ${targetName(target)}`);
108
- return yield* Effect.tryPromise(async () => {
109
- await act(async () => undefined);
110
- return elements.element(target);
111
- }).pipe(
112
- Effect.retry(Schedule.spaced(10)),
113
- Effect.timeoutOrElse({
114
- duration: options.timeout ?? timeoutMs,
115
- orElse: () => Effect.sync(() => elements.element(target)),
116
- }),
117
- );
118
- }),
119
- );
120
- }
69
+
121
70
  return {
122
- ...screenReadouts(currentRoot, tell),
71
+ ...screenReadouts(currentRoot, tell, dialogs),
72
+ ...waits,
123
73
  click: (selector: ScreenTarget) =>
124
74
  perform(`click ${targetName(selector)}`, () => {
125
75
  const element = elements.element(selector);
@@ -128,9 +78,8 @@ function makeScreenActions({ root, pending, tell, act = (action) => action(), ti
128
78
  element.click();
129
79
  }),
130
80
  enter: (selector: ScreenTarget, value: string) => perform(`enter a value in ${targetName(selector)}`, () => elements.enter(selector, value)),
131
- find,
132
81
  nextLiveHint: () => {
133
- if (pending === undefined || typeof pending === "function") {
82
+ if (pending === undefined || typeof pending === "function" || !("current" in pending)) {
134
83
  return Effect.fail(new MissingClientActivity());
135
84
  }
136
85
  return withLive(
@@ -139,7 +88,10 @@ function makeScreenActions({ root, pending, tell, act = (action) => action(), ti
139
88
  ),
140
89
  );
141
90
  },
142
- settle,
91
+ select: (selector: ScreenTarget, value: string) =>
92
+ perform(`select ${JSON.stringify(value)} in ${targetName(selector)}`, () => elements.select(selector, value)),
93
+ settle: (settings?: { readonly timeoutMs?: number }) =>
94
+ pending === undefined ? Effect.fail(new MissingScreenPending()) : waits.settle(settings),
143
95
  submit: (selector: ScreenTarget = "form") => perform(`submit ${targetName(selector)}`, () => elements.form(selector).requestSubmit()),
144
96
  };
145
97
  }
@@ -112,8 +112,9 @@ export function storyKit<
112
112
  TStep extends AnyEffect = never,
113
113
  TFailed extends AnyEffect = never,
114
114
  TDiagnose extends AnyEffect = never,
115
+ TInspect extends (engine: HookValue<ReturnType<TCreate>>) => unknown = (engine: HookValue<ReturnType<TCreate>>) => unknown,
115
116
  >(
116
- definition: InferredDefinition<TCreate, TStage, TVerbs, TProvided, TAfter, TStep, TFailed, TDiagnose>,
117
+ definition: InferredDefinition<TCreate, TStage, TVerbs, TProvided, TAfter, TStep, TFailed, TDiagnose, TInspect>,
117
118
  ): StoryKit<HookValue<ReturnType<TCreate>>, TStage, TVerbs, TStep | TFailed | TDiagnose, TProvided>;
118
119
  export function storyKit<const TKits extends KitList>(definition: Composition<TKits>): ComposedKit<TKits>;
119
120
  // TypeScript reports the last overload's error, so it must check both definition shapes.
@@ -126,9 +127,10 @@ export function storyKit<
126
127
  TStep extends AnyEffect = never,
127
128
  TFailed extends AnyEffect = never,
128
129
  TDiagnose extends AnyEffect = never,
130
+ TInspect extends (engine: HookValue<ReturnType<TCreate>>) => unknown = (engine: HookValue<ReturnType<TCreate>>) => unknown,
129
131
  const TKits extends KitList = KitList,
130
132
  >(
131
- definition: InferredDefinition<TCreate, TStage, TVerbs, TProvided, TAfter, TStep, TFailed, TDiagnose> | Composition<TKits>,
133
+ definition: InferredDefinition<TCreate, TStage, TVerbs, TProvided, TAfter, TStep, TFailed, TDiagnose, TInspect> | Composition<TKits>,
132
134
  ): StoryKit<HookValue<ReturnType<TCreate>>, TStage, TVerbs, TStep | TFailed | TDiagnose, TProvided> | ComposedKit<TKits>;
133
135
  export function storyKit(input: LooseDefinition | Composition<KitList>): unknown {
134
136
  const definition = "extends" in input ? compose(input.name, input.extends) : input;
@@ -0,0 +1,60 @@
1
+ import { Data, type Duration, Effect, Option, Stream } from "effect";
2
+ import { withLive } from "@shivaedev/test/withLive.ts";
3
+ import { describeValue } from "#internal/render.ts";
4
+
5
+ export interface UntilOptions {
6
+ readonly name: string;
7
+ readonly timeout?: Duration.Input;
8
+ }
9
+
10
+ export class SignalNotReceived extends Data.TaggedError("SignalNotReceived")<{
11
+ readonly message: string;
12
+ }> {}
13
+
14
+ export function until<A, E, R>(stream: Stream.Stream<A, E, R>, matches: (value: A) => boolean, options: UntilOptions) {
15
+ return Effect.suspend(() => {
16
+ let last = "(no values received)";
17
+ let found: Option.Option<A> = Option.none();
18
+ function absent(reason: string) {
19
+ return new SignalNotReceived({
20
+ message: `Signal "${options.name}" never arrived: ${reason}.\nLast value seen: ${last}\nhelp: Check that the action emits this signal and that the predicate matches its expected value.`,
21
+ });
22
+ }
23
+ const read = stream.pipe(
24
+ Stream.runForEachWhile((value) =>
25
+ Effect.sync(() => {
26
+ last = describeValue(value);
27
+ if (!matches(value)) {
28
+ return true;
29
+ }
30
+ found = Option.some(value);
31
+ return false;
32
+ }),
33
+ ),
34
+ Effect.flatMap(() => (Option.isSome(found) ? Effect.succeed(found.value) : Effect.fail(absent("the stream ended")))),
35
+ );
36
+ const deadline = Effect.sleep(options.timeout ?? "5 seconds").pipe(
37
+ Effect.andThen(Effect.failSync(() => absent("the live-time deadline expired"))),
38
+ withLive,
39
+ );
40
+ return Effect.raceFirst(read, deadline);
41
+ });
42
+ }
43
+
44
+ export function collectUntil<A, E, R>(stream: Stream.Stream<A, E, R>, matches: (values: readonly A[]) => boolean, options: UntilOptions) {
45
+ return Effect.suspend(() => {
46
+ const values: A[] = [];
47
+ return until(
48
+ stream.pipe(
49
+ Stream.mapEffect((value) =>
50
+ Effect.sync((): readonly A[] => {
51
+ values.push(value);
52
+ return [...values];
53
+ }),
54
+ ),
55
+ ),
56
+ matches,
57
+ options,
58
+ );
59
+ });
60
+ }
@@ -1,5 +0,0 @@
1
- import { Effect } from "effect";
2
- import { type ClientActivity } from "@shivaedev/contract/clientActivity.ts";
3
- export declare function waitForClient(activity: ClientActivity): Effect.Effect<void, never, never>;
4
- export declare const nextClientHint: (activity: ClientActivity) => Effect.Effect<void, never, never>;
5
- //# sourceMappingURL=screenActivity.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"screenActivity.d.ts","sourceRoot":"","sources":["../../../src/server/internal/screenActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,KAAK,cAAc,EAAgB,MAAM,uCAAuC,CAAC;AAE1F,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,qCAErD;AAED,eAAO,MAAM,cAAc,iEAOzB,CAAC"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"screenActivity.js","sourceRoot":"","sources":["../../../src/server/internal/screenActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAuB,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAE1F,MAAM,UAAU,aAAa,CAAC,QAAwB;IACrD,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;AACpF,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,QAAwB;IAClF,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC;IACnD,OAAO,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,CAC1B,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,EAClD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EACd,MAAM,CAAC,QAAQ,CACf,CAAC;AACH,CAAC,CAAC,CAAC"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"screenElements.d.ts","sourceRoot":"","sources":["../../../src/server/internal/screenElements.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,WAAW;wBAO1B,YAAY;qBAsBf,WAAW,YAAY,YAAY;sBAkBxC,YAAY,SAAS,MAAM;qBAY5B,YAAY;sBAvCL,YAAY;sBAnBZ,WAAW,YAAY,MAAM;kBAiCjC,WAAW,KAAG,MAAM;EAqCzC"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"screenElements.js","sourceRoot":"","sources":["../../../src/server/internal/screenElements.ts"],"names":[],"mappings":"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"}