@shivaedev/test-story 0.21.1 → 0.23.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.
- package/CHANGELOG.md +24 -0
- package/README.md +258 -193
- package/dist/server/forwardingProxy.d.ts.map +1 -1
- package/dist/server/forwardingProxy.js +44 -7
- package/dist/server/forwardingProxy.js.map +1 -1
- package/dist/server/internal/compose.d.ts +4 -0
- package/dist/server/internal/compose.d.ts.map +1 -0
- package/dist/server/internal/compose.js +38 -0
- package/dist/server/internal/compose.js.map +1 -0
- package/dist/server/internal/compositionTypes.d.ts +37 -0
- package/dist/server/internal/compositionTypes.d.ts.map +1 -0
- package/dist/server/internal/compositionTypes.js +2 -0
- package/dist/server/internal/compositionTypes.js.map +1 -0
- package/dist/server/internal/documentRedirect.d.ts.map +1 -1
- package/dist/server/internal/documentRedirect.js +3 -1
- package/dist/server/internal/documentRedirect.js.map +1 -1
- package/dist/server/internal/documentTransport.d.ts.map +1 -1
- package/dist/server/internal/documentTransport.js +4 -1
- package/dist/server/internal/documentTransport.js.map +1 -1
- package/dist/server/internal/fakeHttpAnswer.d.ts.map +1 -1
- package/dist/server/internal/fakeHttpAnswer.js +3 -2
- package/dist/server/internal/fakeHttpAnswer.js.map +1 -1
- package/dist/server/internal/fakeHttpControls.d.ts.map +1 -1
- package/dist/server/internal/fakeHttpControls.js +2 -1
- package/dist/server/internal/fakeHttpControls.js.map +1 -1
- package/dist/server/internal/fakeHttpReceive.d.ts.map +1 -1
- package/dist/server/internal/fakeHttpReceive.js +5 -4
- package/dist/server/internal/fakeHttpReceive.js.map +1 -1
- package/dist/server/internal/fakeHttpSend.d.ts.map +1 -1
- package/dist/server/internal/fakeHttpSend.js +3 -2
- package/dist/server/internal/fakeHttpSend.js.map +1 -1
- package/dist/server/internal/hookInference.d.ts +3 -3
- package/dist/server/internal/hookInference.d.ts.map +1 -1
- package/dist/server/internal/screenElements.d.ts +1 -0
- package/dist/server/internal/screenElements.d.ts.map +1 -1
- package/dist/server/internal/screenElements.js +11 -0
- package/dist/server/internal/screenElements.js.map +1 -1
- package/dist/server/internal/storyIt.d.ts.map +1 -1
- package/dist/server/internal/storyIt.js +7 -5
- package/dist/server/internal/storyIt.js.map +1 -1
- package/dist/server/otlpReceiver.d.ts.map +1 -1
- package/dist/server/otlpReceiver.js +5 -4
- package/dist/server/otlpReceiver.js.map +1 -1
- package/dist/server/outcomes.d.ts +6 -0
- package/dist/server/outcomes.d.ts.map +1 -0
- package/dist/server/outcomes.js +13 -0
- package/dist/server/outcomes.js.map +1 -0
- package/dist/server/screenDriver.js +1 -1
- package/dist/server/screenDriver.js.map +1 -1
- package/dist/server/storyKit.d.ts +6 -3
- package/dist/server/storyKit.d.ts.map +1 -1
- package/dist/server/storyKit.js +5 -1
- package/dist/server/storyKit.js.map +1 -1
- package/package.json +8 -6
- package/src/server/forwardingProxy.ts +59 -23
- package/src/server/internal/compose.ts +45 -0
- package/src/server/internal/compositionTypes.ts +56 -0
- package/src/server/internal/documentRedirect.ts +4 -1
- package/src/server/internal/documentTransport.ts +12 -1
- package/src/server/internal/fakeHttpAnswer.ts +3 -2
- package/src/server/internal/fakeHttpControls.ts +2 -1
- package/src/server/internal/fakeHttpReceive.ts +5 -4
- package/src/server/internal/fakeHttpSend.ts +3 -2
- package/src/server/internal/hookInference.ts +3 -3
- package/src/server/internal/screenElements.ts +11 -0
- package/src/server/internal/storyIt.ts +9 -8
- package/src/server/otlpReceiver.ts +5 -4
- package/src/server/outcomes.ts +21 -0
- package/src/server/screenDriver.ts +1 -1
- package/src/server/storyKit.ts +11 -5
package/README.md
CHANGED
|
@@ -8,9 +8,9 @@ When agents write most of the code, test files grow into hundreds of lines nobod
|
|
|
8
8
|
|
|
9
9
|
```ts
|
|
10
10
|
bakery.it("steps until the condition holds", [ovenIsLit(), hasDough(3)], function* ({ oven }) {
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
11
|
+
yield* oven.bakesEverything();
|
|
12
|
+
expect(oven.loaves()).toBe(3);
|
|
13
|
+
expect(oven.minutes()).toBe(3);
|
|
14
14
|
});
|
|
15
15
|
```
|
|
16
16
|
|
|
@@ -54,7 +54,6 @@ Every story belongs to a **genre**, the kind of engine it runs. The kit names ea
|
|
|
54
54
|
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.
|
|
55
55
|
|
|
56
56
|
The work splits into three layers, and each is written by a different hand at a different time:
|
|
57
|
-
|
|
58
57
|
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.
|
|
59
58
|
2. **Once per feature**, traits and verbs in the kit name that feature in domain words.
|
|
60
59
|
3. **In every test**, a spec tells a story with the kit's `it` and checks what a user would see.
|
|
@@ -65,80 +64,81 @@ A verb performs one action on the real engine or reads one observation. An actio
|
|
|
65
64
|
|
|
66
65
|
Acquire real services in `create` or a trait inside the story's per-test Scope, with dependencies provided by `layer`. Keep those services on the engine so verbs use the same running instance; scoped cleanup releases them after the story. Do not build and tear down services inside each verb. When closing a service is the action under test, expose that action separately from acquisition and observation.
|
|
67
66
|
|
|
68
|
-
| Shape to avoid
|
|
69
|
-
|
|
|
70
|
-
| A verb runs a whole scenario and returns the measurements the spec asserts.
|
|
71
|
-
| A verb hard-codes the expected outcome or hides assertions.
|
|
72
|
-
| A verb does two jobs and returns both results.
|
|
73
|
-
| A verb silently does nothing when its target is missing, such as `button?.click()`.
|
|
67
|
+
| Shape to avoid | What to do instead |
|
|
68
|
+
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
|
69
|
+
| A verb runs a whole scenario and returns the measurements the spec asserts. | Give each action and observation its own verb; let the spec compose them and compare the observations. |
|
|
70
|
+
| A verb hard-codes the expected outcome or hides assertions. | Return the real response or observation, and put expected values and all assertions in the spec. |
|
|
71
|
+
| A verb does two jobs and returns both results. | Split the jobs into two verbs and show both calls in the spec. |
|
|
72
|
+
| A verb silently does nothing when its target is missing, such as `button?.click()`. | Fail with a message naming the missing target, then perform the action only once the target exists. |
|
|
74
73
|
| An engine default hides what the story declares, such as a lit oven, signed-in user or authorization header. | Start with a neutral engine and name the precondition in a trait or pass the input explicitly in the action. |
|
|
75
74
|
|
|
76
75
|
The bakery below starts with a cold oven and no dough. Its traits declare heat and dough, its baking action returns no report, and its readouts expose loaves and elapsed minutes separately. `runUntil` waits for that one engine action to complete; it does not replace a spec's sequence of actions.
|
|
77
76
|
|
|
77
|
+
Every story gets Effect's native `TestCrypto` service with seed `0`, created afresh before its wrapper, engine creation, traits and body. A command that yields `Crypto` from `effect/Crypto` can therefore produce the same invite code in every story, without a kit-specific random source. Digests use the Node implementation. UUIDv7 also reads the story's clock; pin it when asserting the complete value. These deterministic values belong only in tests.
|
|
78
|
+
|
|
78
79
|
### 1. Once per engine: the story kit
|
|
79
80
|
|
|
80
81
|
`storyKit(definition)` from `@shivaedev/test-story/server/storyKit.ts` turns one definition into the kit. Every type, the engine's, the stages', the verbs' and the services', is inferred from it.
|
|
81
82
|
|
|
82
83
|
```ts
|
|
83
84
|
export const bakery = storyKit({
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
}),
|
|
85
|
+
after: {
|
|
86
|
+
*kitchen(state) {
|
|
87
|
+
if (state.bowls === 0) {
|
|
88
|
+
return yield* new NoBowls();
|
|
89
|
+
}
|
|
90
|
+
state.capacity = state.bowls * DOUGH_PER_BOWL;
|
|
91
|
+
},
|
|
92
|
+
},
|
|
93
|
+
create: emptyBakery,
|
|
94
|
+
layer: Supplier.layer,
|
|
95
|
+
name: "bakery",
|
|
96
|
+
run: {
|
|
97
|
+
diagnose: stillWaiting,
|
|
98
|
+
failed: ovenTrouble,
|
|
99
|
+
maxSteps: 60,
|
|
100
|
+
*step(state, tell) {
|
|
101
|
+
state.minute += 1;
|
|
102
|
+
if (state.overfired) {
|
|
103
|
+
return yield* new BurntLoaf({ minute: state.minute });
|
|
104
|
+
}
|
|
105
|
+
state.dough += state.starter ? 0 : -1;
|
|
106
|
+
state.loaves += 1;
|
|
107
|
+
tell(`${state.minute}m a loaf comes out of the oven`);
|
|
108
|
+
},
|
|
109
|
+
},
|
|
110
|
+
stages: ["kitchen", "pantry"],
|
|
111
|
+
verbs: (state, story) => ({
|
|
112
|
+
baker: {
|
|
113
|
+
kneads: (count: number) => {
|
|
114
|
+
story.tell(`the baker kneads ${count} balls of dough`);
|
|
115
|
+
state.dough += count;
|
|
116
|
+
},
|
|
117
|
+
},
|
|
118
|
+
oven: {
|
|
119
|
+
bakesEverything: (maxSteps?: number): Effect.Effect<void, BurntLoaf> => story.runUntil((current) => current.dough === 0, { maxSteps }),
|
|
120
|
+
loaves: () => state.loaves,
|
|
121
|
+
minutes: () => state.minute,
|
|
122
|
+
},
|
|
123
|
+
}),
|
|
124
124
|
});
|
|
125
125
|
```
|
|
126
126
|
|
|
127
127
|
This is the bakery kit this package tests itself with. `emptyBakery`, `stillWaiting` and `ovenTrouble` are plain functions beside it. `kitchen` and `step` are generators because they fail with typed errors, `NoBowls` and `BurntLoaf`.
|
|
128
128
|
|
|
129
|
-
| Hook
|
|
130
|
-
|
|
|
131
|
-
| `name`
|
|
132
|
-
| `outbound`
|
|
133
|
-
| `around(effect)`
|
|
134
|
-
| `clock`
|
|
135
|
-
| `create()`
|
|
136
|
-
| `layer`
|
|
137
|
-
| `stages`
|
|
138
|
-
| `after`
|
|
139
|
-
| `run`
|
|
140
|
-
| `inspect`
|
|
141
|
-
| `verbs(engine, story)` | One action or one observation per verb. A verb that waits for a stepped engine returns the Effect from `story.runUntil`; the spec reads observations and asserts separately.
|
|
129
|
+
| Hook | Says |
|
|
130
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
131
|
+
| `name` | What the engine is called in failures, "the bakery", and the kit's genre, "Bakery Story". |
|
|
132
|
+
| `outbound` | Optional. A map of exact hostnames to fake server origins for Node fetch and the DOM environment's document requests. |
|
|
133
|
+
| `around(effect)` | Optional. Wraps creation, staged seeding and the body; worker Layer acquisition remains outside it. It may require the worker services and per-test Scope. |
|
|
134
|
+
| `clock` | Optional. `"test"` by default, `"live"` for real time, or a UTC `DateTime` to start TestClock at that instant. A story’s `options.clock` takes precedence. |
|
|
135
|
+
| `create()` | A fresh engine. Every story starts from a new one. |
|
|
136
|
+
| `layer` | Optional. The worker Effect layer that provides the services hooks, traits and test bodies use. Per-test Scope is already available to creation, staged and run hooks, traits and bodies. A hook that needs a service the layer does not provide does not compile, and neither does a test whose traits or body need one. |
|
|
137
|
+
| `stages` | The order traits are applied in. A trait names its stage, and one that names a stage the kit does not declare does not compile. |
|
|
138
|
+
| `after` | Optional. A hook per stage that runs once that stage's traits are applied, even when no trait names the stage, so a value it derives is ready before a later stage reads it. Its typed failure fails the test. |
|
|
139
|
+
| `run` | Optional. What `story.runUntil` needs: `step(engine, tell)` advances the engine once and tells what happened, `maxSteps` caps one run, `failed(engine)` returns a sentence when the engine is in a state it cannot recover from, and `diagnose(engine)` says why it has not finished. |
|
|
140
|
+
| `inspect` | Optional. The part of the engine a failure prints. Without it, the failure prints the whole engine. |
|
|
141
|
+
| `verbs(engine, story)` | One action or one observation per verb. A verb that waits for a stepped engine returns the Effect from `story.runUntil`; the spec reads observations and asserts separately. |
|
|
142
142
|
|
|
143
143
|
Every test of the kit is named `Bakery Story: <its name>`, so `vitest run -t "Bakery Story: "` runs only the bakery's stories with no setup. A project that splits runs by Vitest tags can also tag them:
|
|
144
144
|
|
|
@@ -147,26 +147,56 @@ import { genreTags } from "@shivaedev/test-story/server/genreTags.ts";
|
|
|
147
147
|
import { defineConfig } from "vitest/config";
|
|
148
148
|
|
|
149
149
|
export default defineConfig({
|
|
150
|
-
|
|
150
|
+
test: { tags: genreTags("bakery", "mill") },
|
|
151
151
|
});
|
|
152
152
|
```
|
|
153
153
|
|
|
154
154
|
`genreTags(...kitNames)` declares one tag per kit, named after it: `bakery-story` and `mill-story` here, and `game-store-story` for a kit named "game store". A kit tags its tests only with a genre the config declares, because Vitest refuses a test whose tag the config leaves out, so a config without the line runs every story untagged and prints nothing about it. With the tags declared, `vitest run --tags-filter=mill-story` runs the mill's stories and skips the bakery's, and `--tags-filter` takes any of Vitest's tag expressions, such as `'!mill-story'`. A root config whose inline projects extend the package's config gets these tags from it, so `--tags-filter` works from the root too.
|
|
155
155
|
|
|
156
|
+
#### Composing feature kits
|
|
157
|
+
|
|
158
|
+
Compose kits when one story crosses features that already have their own engines, traits and verbs. Keep each feature kit independent; an integration kit imports the kits and their public trait factories, so neither feature needs to import the other's internals.
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
import { expect } from "vitest";
|
|
162
|
+
import { storyKit } from "@shivaedev/test-story/server/storyKit.ts";
|
|
163
|
+
import { bakery, hasDough, ovenIsLit } from "./bakery.ts";
|
|
164
|
+
import { mill, sailsAreTurning } from "./mill.ts";
|
|
165
|
+
|
|
166
|
+
export const village = storyKit({
|
|
167
|
+
extends: [mill, bakery],
|
|
168
|
+
name: "village",
|
|
169
|
+
});
|
|
170
|
+
|
|
171
|
+
village.it("mills flour and bakes loaves", [sailsAreTurning(), ovenIsLit(), hasDough(2)], function* ({ miller, oven, story }) {
|
|
172
|
+
miller.grinds(3);
|
|
173
|
+
yield* oven.bakesEverything();
|
|
174
|
+
expect(story.engine.sacks).toBe(3);
|
|
175
|
+
expect(story.engine.sails).toBe("turning");
|
|
176
|
+
expect(oven.loaves()).toBe(2);
|
|
177
|
+
});
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
`extends` takes one or more kits. The composed engine includes each kit's engine fields, the body receives all their verbs, and traits from either kit work directly. Types for engines, stages, verbs and layer services remain inferred. A composed kit can itself appear in `extends`.
|
|
181
|
+
|
|
182
|
+
Creation runs in dependency order, left to right, before any traits. Stages and their `after` hooks then run in that same order, regardless of the order traits appear in the spec. All creation, traits, hooks and the body share one per-test Scope, whose finalizers release resources in reverse acquisition order, including after a failed story. Feature verbs retain their own `runUntil` hooks, so the bakery's waiting verb still steps the bakery. Use each feature's waiting verbs when driving a composed story.
|
|
183
|
+
|
|
184
|
+
Top-level engine fields, verb names and trait stage names must be unique across the kits. A collision fails typechecking with a message such as `Cannot compose story kits: duplicate verb names` and the conflicting name. Give stages feature-specific names when composing; a trait's stage selects its feature's setup hooks. Traits are each feature kit's own `kit.trait` values and `kit.traits` combinations.
|
|
185
|
+
|
|
156
186
|
#### Routing outbound HTTP
|
|
157
187
|
|
|
158
188
|
When application code calls a hard-coded third-party URL, set `outbound` on its kit to send those requests to a fake server:
|
|
159
189
|
|
|
160
190
|
```ts
|
|
161
191
|
const app = storyKit({
|
|
162
|
-
|
|
163
|
-
|
|
192
|
+
...appDefinition,
|
|
193
|
+
outbound: { "github.com": fakeUrl, "api.github.com": fakeUrl },
|
|
164
194
|
});
|
|
165
195
|
```
|
|
166
196
|
|
|
167
197
|
`appDefinition` holds the application's kit hooks, and `fakeUrl` is the listening fake server's HTTP or HTTPS origin, such as `http://127.0.0.1:4321`. The map matches exact URL hostnames, across ports. It replaces the destination origin while keeping the request's path, query, method, headers and body. For example, a POST to `https://github.com/login/oauth/access_token` reaches the fake's `/login/oauth/access_token`. In Node stories, other hostnames pass through the previous dispatcher unchanged. In the DOM environment, only loopback hosts (`localhost`, IPv4 loopback addresses and `[::1]`) may pass through without a route; every other hostname must have an `outbound` fake. A refused request fails the story and names its hostname, even when application code catches the fetch error.
|
|
168
198
|
|
|
169
|
-
`routeOutbound(routes)` from `@shivaedev/test-story/server/routeOutbound.ts` installs the same routing in the current Effect Scope. Acquire a `fakeHttpService` in `create`, then yield `routeOutbound({ "api.example.com": api.url })` so the fake listener and its routing belong to that story.
|
|
199
|
+
`routeOutbound(routes)` from `@shivaedev/test-story/server/routeOutbound.ts` installs the same routing in the current Effect Scope. Acquire a `fakeHttpService` in `create`, then yield `routeOutbound({ "api.example.com": api.url })` so the fake listener and its routing belong to that story.
|
|
170
200
|
|
|
171
201
|
Routing uses the global dispatcher that Node's built-in `fetch` already uses. The kit's `outbound` option installs routing before `around`, creation, traits and the body, stays active during scoped cleanup, and restores the previous dispatcher after each story, including a failing story. Stories within one worker must run one at a time because that dispatcher is shared; parallelism belongs between workers or inside one story. The DOM environment uses the same routing for host-side Node fetch and document requests, including redirect destinations. It refuses external hosts even when the kit omits `outbound`.
|
|
172
202
|
|
|
@@ -185,49 +215,50 @@ import { expect } from "vitest";
|
|
|
185
215
|
import { storyKit } from "@shivaedev/test-story/server/storyKit.ts";
|
|
186
216
|
|
|
187
217
|
const app = storyKit({
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
218
|
+
around: (effect) => effect.pipe(Effect.withSpan("story")),
|
|
219
|
+
*create() {
|
|
220
|
+
const spans: Tracer.NativeSpan[] = [];
|
|
221
|
+
const tracer = Tracer.make({
|
|
222
|
+
span: (options) => {
|
|
223
|
+
const span = new Tracer.NativeSpan(options);
|
|
224
|
+
spans.push(span);
|
|
225
|
+
return span;
|
|
226
|
+
},
|
|
227
|
+
});
|
|
228
|
+
const context = yield* Effect.context<never>().pipe(Effect.withTracer(tracer));
|
|
229
|
+
const handler = HttpEffect.toWebHandlerWith(context)(Effect.succeed(HttpServerResponse.text("ok")));
|
|
230
|
+
return { handler, spans };
|
|
231
|
+
},
|
|
232
|
+
name: "traced application",
|
|
233
|
+
stages: ["ready"],
|
|
234
|
+
verbs: ({ handler, spans }) => ({
|
|
235
|
+
request: (headers: HeadersInit = {}) =>
|
|
236
|
+
Effect.promise(async () => {
|
|
237
|
+
const response = await handler(new Request("http://app.test/", { headers }));
|
|
238
|
+
return response.text();
|
|
239
|
+
}),
|
|
240
|
+
requestSpan: () => {
|
|
241
|
+
const span = spans.filter((span) => span.kind === "server").at(-1);
|
|
242
|
+
if (span === undefined) throw new Error("The request exported no server span");
|
|
243
|
+
return span;
|
|
244
|
+
},
|
|
245
|
+
}),
|
|
215
246
|
});
|
|
216
247
|
|
|
217
248
|
app.it("a request is its own root trace", [], function* ({ request, requestSpan }) {
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
249
|
+
const storySpan = yield* Effect.currentSpan;
|
|
250
|
+
expect(yield* request()).toBe("ok");
|
|
251
|
+
const span = requestSpan();
|
|
252
|
+
expect(span.parent._tag).toBe("None");
|
|
253
|
+
expect(span.traceId).not.toBe(storySpan.traceId);
|
|
254
|
+
expect(span.status._tag).toBe("Ended");
|
|
224
255
|
});
|
|
225
256
|
|
|
226
257
|
app.it("a request continues its supplied trace", [], function* ({ request, requestSpan }) {
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
258
|
+
yield* request({ traceparent: "00-1234567890abcdef1234567890abcdef-1234567890abcdef-01" });
|
|
259
|
+
const span = requestSpan();
|
|
260
|
+
expect(span.traceId).toBe("1234567890abcdef1234567890abcdef");
|
|
261
|
+
expect(span.parent).toMatchObject({ value: { spanId: "1234567890abcdef" } });
|
|
231
262
|
});
|
|
232
263
|
```
|
|
233
264
|
|
|
@@ -261,10 +292,10 @@ Use `otlpReceiver` from `@shivaedev/test-story/server/otlpReceiver.ts` in a kit'
|
|
|
261
292
|
|
|
262
293
|
```ts
|
|
263
294
|
app.it("exports the work span", [], function* ({ runWork, disposeRuntime, spans, requests }) {
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
295
|
+
yield* runWork();
|
|
296
|
+
yield* disposeRuntime();
|
|
297
|
+
expect(spans()).toContainEqual(expect.objectContaining({ name: "CountWords" }));
|
|
298
|
+
expect(requests().some(({ body }) => body.includes(Buffer.from("planted-secret")))).toBe(true);
|
|
268
299
|
});
|
|
269
300
|
```
|
|
270
301
|
|
|
@@ -320,7 +351,7 @@ const bytes = yield* Fiber.join(pending);
|
|
|
320
351
|
|
|
321
352
|
`stall(route)` sends the reply's status and headers, then pauses its body. Its `waiting` effect completes at that pause. Its `release` lets the body continue; a client that gives up also stops waiting on the server. Like a hold, a stall remains installed for matching requests until released. Holds pause before headers. `releaseOnArrival(heldRoute, arrivingRoute, scope?)` releases the current hold when an authorized request reaches the named route; script it before that arrival. Rejected requests do not trigger release.
|
|
322
353
|
|
|
323
|
-
`fault(route, fault)` acts on an arrived request in the required phase. `{ kind: "status", reply: { status: 503, body: { error: "unavailable" } } }` replaces a held reply before headers. `{ kind: "drop" }` drops a connection before headers. `{ kind: "reset" }` terminates a reply after headers, including after body chunks have arrived. Wait for the hold, stall or client observation before injecting the fault. A fault fails with guidance when no request is in the required phase; it does not queue a failure for a future call. `failOnce`
|
|
354
|
+
`fault(route, fault)` acts on an arrived request in the required phase. `{ kind: "status", reply: { status: 503, body: { error: "unavailable" } } }` replaces a held reply before headers. `{ kind: "drop" }` drops a connection before headers. `{ kind: "reset" }` terminates a reply after headers, including after body chunks have arrived. Wait for the hold, stall or client observation before injecting the fault. A fault fails with guidance when no request is in the required phase; it does not queue a failure for a future call. `failOnce` queues a status reply for the next request.
|
|
324
355
|
|
|
325
356
|
`hold(route, scope)`, `stall(route, scope)`, `fault(route, fault, scope)`, `failOnce(route, reply, scope)` and `replyOnce(route, reply, scope)` accept an optional `{ params: { number: "7" } }`. Every supplied parameter must equal the decoded request parameter. Other resources on the same named route answer normally and do not consume the scoped reply. Scoped holds and stalls return `waiting` and `release`. `hold(route, { once: true, params: { number: "7" } })` holds only the first matching request; later matching requests answer while it remains held. Omit `params` to hold only the first request across the route. Omit `once` to keep holding every matching request until release. Pass the same parameter scope as the third argument to `releaseOnArrival` to release that hold.
|
|
326
357
|
|
|
@@ -366,24 +397,24 @@ A trait is a line and a change, tagged with a stage:
|
|
|
366
397
|
|
|
367
398
|
```ts
|
|
368
399
|
export function hasDough(count: number) {
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
400
|
+
return bakery.trait("pantry", `the baker has ${count} balls of dough`, (state) => {
|
|
401
|
+
if (count > state.capacity) {
|
|
402
|
+
throw new Error(`the bowls hold only ${state.capacity}`);
|
|
403
|
+
}
|
|
404
|
+
state.dough = count;
|
|
405
|
+
});
|
|
375
406
|
}
|
|
376
407
|
|
|
377
408
|
export function hasFlourDelivered(sacks: number) {
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
409
|
+
return bakery.trait("pantry", `the supplier has delivered ${sacks} sacks of flour`, function* (state) {
|
|
410
|
+
const supplier = yield* Supplier;
|
|
411
|
+
yield* supplier.deliver(sacks);
|
|
412
|
+
state.flour = sacks;
|
|
413
|
+
});
|
|
383
414
|
}
|
|
384
415
|
|
|
385
416
|
export function morningShift() {
|
|
386
|
-
|
|
417
|
+
return bakery.traits(ovenIsLit(), hasBowls(1));
|
|
387
418
|
}
|
|
388
419
|
```
|
|
389
420
|
|
|
@@ -421,15 +452,15 @@ A verb that a feature adds goes into the kit's `verbs`. It acts through the engi
|
|
|
421
452
|
|
|
422
453
|
```ts
|
|
423
454
|
bakery.it("tells each step into the story", [ovenIsLit()], function* ({ baker, oven, story }) {
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
455
|
+
baker.kneads(2);
|
|
456
|
+
yield* oven.bakesEverything();
|
|
457
|
+
|
|
458
|
+
expect(story.lines).toEqual([
|
|
459
|
+
"the oven is lit",
|
|
460
|
+
"the baker kneads 2 balls of dough",
|
|
461
|
+
"1m a loaf comes out of the oven",
|
|
462
|
+
"2m a loaf comes out of the oven",
|
|
463
|
+
]);
|
|
433
464
|
});
|
|
434
465
|
```
|
|
435
466
|
|
|
@@ -437,6 +468,32 @@ bakery.it("tells each step into the story", [ovenIsLit()], function* ({ baker, o
|
|
|
437
468
|
|
|
438
469
|
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.
|
|
439
470
|
|
|
471
|
+
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:
|
|
472
|
+
|
|
473
|
+
```ts
|
|
474
|
+
import { outcomes } from "@shivaedev/test-story/server/outcomes.ts";
|
|
475
|
+
|
|
476
|
+
accounts.it("removing Bob leaves Alice signed in", [bobAndAliceAreSignedIn()], function* ({ remove, request, sessions }) {
|
|
477
|
+
yield* remove("bob");
|
|
478
|
+
|
|
479
|
+
yield* outcomes({
|
|
480
|
+
"bob's next request": [request("bob"), "unauthorized"],
|
|
481
|
+
"bob's sessions": [sessions("bob"), 0],
|
|
482
|
+
"alice's next request": [request("alice"), "ok"],
|
|
483
|
+
});
|
|
484
|
+
});
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
`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`:
|
|
488
|
+
|
|
489
|
+
```ts
|
|
490
|
+
accounts.it("removing Bob ends his session", [bobIsSignedIn()], function* ({ remove, request }) {
|
|
491
|
+
yield* remove("bob");
|
|
492
|
+
|
|
493
|
+
expect(yield* request("bob")).toBe("unauthorized");
|
|
494
|
+
});
|
|
495
|
+
```
|
|
496
|
+
|
|
440
497
|
### Pinning time
|
|
441
498
|
|
|
442
499
|
Pass a UTC `DateTime` as the story's `clock` option to pin time before its wrapper, creation, traits and hooks run. Code that uses `Clock` or `DateTime.now` reads that instant. Advance it explicitly with native `TestClock.adjust`:
|
|
@@ -445,27 +502,31 @@ Pass a UTC `DateTime` as the story's `clock` option to pin time before its wrapp
|
|
|
445
502
|
import { DateTime } from "effect";
|
|
446
503
|
import * as TestClock from "effect/testing/TestClock";
|
|
447
504
|
|
|
448
|
-
app.it(
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
505
|
+
app.it(
|
|
506
|
+
"shows the worker's date",
|
|
507
|
+
[],
|
|
508
|
+
function* ({ click, settle, text }) {
|
|
509
|
+
yield* click("button");
|
|
510
|
+
yield* settle();
|
|
511
|
+
expect(text("#worker")).toBe("Worker: since Oct 17");
|
|
512
|
+
yield* TestClock.adjust("1 day");
|
|
513
|
+
yield* click("button");
|
|
514
|
+
yield* settle();
|
|
515
|
+
expect(text("#worker")).toBe("Worker: since Oct 18");
|
|
516
|
+
},
|
|
517
|
+
{ clock: DateTime.makeUnsafe("2026-10-17T12:34:56.000Z") },
|
|
518
|
+
);
|
|
457
519
|
```
|
|
458
520
|
|
|
459
521
|
Acquire hosts, workers and screens in per-story Scope so they inherit the story's Clock. An independent runtime or native HTTP handler must capture the Effect Context at acquisition, as with `HttpEffect.toWebHandlerWith(context)` or `Effect.runPromiseWith(context)`. Worker-scoped kit `layer` acquisition stays outside the per-story clock; shared services acquired there do not acquire a new clock for each story. Direct JavaScript wall-time reads are not replaced. Formatting stays with the application, including its locale and time zone.
|
|
460
522
|
|
|
461
|
-
|
|
523
|
+
A live-clock kit still runs on real time when a story omits the override.
|
|
462
524
|
|
|
463
525
|
### Running the engine
|
|
464
526
|
|
|
465
527
|
Hooks and steps that wait for real workers can use `withLive(Effect.sleep(...))` or `withLive(eventually(...))` from `@shivaedev/test/withLive.ts` and `@shivaedev/test/eventually.ts`. Both work under the kit's live clock and a story's TestClock override. The wrapped work uses live time without advancing the story's virtual time; outside it, the selected clock still applies. Unwrapped `eventually` uses the active clock and advances TestClock between attempts.
|
|
466
528
|
|
|
467
529
|
`story.runUntil(condition, { maxSteps })` returns an Effect that asks three questions before every step:
|
|
468
|
-
|
|
469
530
|
1. `run.failed` returns a sentence: it dies with it, even when the condition also holds.
|
|
470
531
|
2. The condition holds: it succeeds.
|
|
471
532
|
3. `maxSteps` steps have run, or the kit's `run.maxSteps` when the call names none: it dies with `run.diagnose`.
|
|
@@ -482,7 +543,6 @@ That is what `oven.bakesEverything(12)` dies with when the baker keeps a sourdou
|
|
|
482
543
|
### When a story fails
|
|
483
544
|
|
|
484
545
|
After the engine has been created, a failing story test adds the story to its first error, as in the examples above:
|
|
485
|
-
|
|
486
546
|
- a short guide to reading the story, in a box;
|
|
487
547
|
- every line in order, traits marked `given`;
|
|
488
548
|
- `✗` after the last line, on the trait that refused, or alone when the test failed before the story told a line, and under it the spec line where the test stopped or that named the refusing trait;
|
|
@@ -511,28 +571,28 @@ For full-app stories, use `around: withIsolatedDatabase` from `@shivaedev/test-s
|
|
|
511
571
|
|
|
512
572
|
For repository-level tests on a migrated template, `withTestTransaction` from `@shivaedev/test-sql/server/withTestTransaction.ts` provides rollback isolation when all work uses its transaction connection. See the [database test helpers](https://github.com/ShivaeDev/platform/blob/main/packages/test-sql/README.md) for template preparation and both wrappers.
|
|
513
573
|
|
|
514
|
-
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
|
|
574
|
+
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`.
|
|
515
575
|
|
|
516
576
|
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`.
|
|
517
577
|
|
|
518
578
|
### DOM stories with cookie sessions
|
|
519
579
|
|
|
520
|
-
Install `happy-dom
|
|
580
|
+
Install `happy-dom` as a dev dependency. Select the `@shivaedev/test-story/server/domEnvironment.config.ts` Vitest environment for DOM tests that start their host in the same process:
|
|
521
581
|
|
|
522
582
|
```ts
|
|
523
583
|
import { fileURLToPath } from "node:url";
|
|
524
584
|
import { defineConfig } from "vitest/config";
|
|
525
585
|
|
|
526
586
|
export default defineConfig({
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
587
|
+
test: {
|
|
588
|
+
environment: fileURLToPath(import.meta.resolve("@shivaedev/test-story/server/domEnvironment.config.ts")),
|
|
589
|
+
},
|
|
530
590
|
});
|
|
531
591
|
```
|
|
532
592
|
|
|
533
593
|
The environment keeps Node's global `fetch`, `Request`, `Response`, `Headers`, `AbortController` and `AbortSignal` for the in-process host. The separate `window` keeps happy-dom's constructors and cookie jar. Its asynchronous HTTP requests use Node fetch through the same `outbound` dispatcher, including XMLHttpRequest. Synchronous document HTTP requests are refused. The starter's [Vitest config](https://github.com/ShivaeDev/platform/blob/main/examples/starter/vitest.config.ts) selects this environment only for its DOM project while retaining the shared test projects. Use Vitest's standard forks or threads pool.
|
|
534
594
|
|
|
535
|
-
`domFetch(baseUrl)` from `@shivaedev/test-story/server/domFetch.ts` sets the document's location to the real HTTP host and returns a document fetch that resolves relative request strings against that URL. It translates Node `Request` and `Headers` inputs for happy-dom. Responses have happy-dom's status, headers and body methods; they are not instances of Node's global `Response`. The document keeps and sends cookies, including HttpOnly session cookies. Keep the default `same-origin` credentials policy for same-origin requests, and pass this fetch explicitly to browser clients, such as Better Auth's `fetchOptions.customFetchImpl`. The host
|
|
595
|
+
`domFetch(baseUrl)` from `@shivaedev/test-story/server/domFetch.ts` sets the document's location to the real HTTP host and returns a document fetch that resolves relative request strings against that URL. It translates Node `Request` and `Headers` inputs for happy-dom. Responses have happy-dom's status, headers and body methods; they are not instances of Node's global `Response`. The document keeps and sends cookies, including HttpOnly session cookies. Keep the default `same-origin` credentials policy for same-origin requests, and pass this fetch explicitly to browser clients, such as Better Auth's `fetchOptions.customFetchImpl`. The host uses global Node fetch without browser cookies.
|
|
536
596
|
|
|
537
597
|
Call it in the kit's `create` hook after starting the host:
|
|
538
598
|
|
|
@@ -541,18 +601,18 @@ import { createAuthClient } from "better-auth/react";
|
|
|
541
601
|
import { domFetch } from "@shivaedev/test-story/server/domFetch.ts";
|
|
542
602
|
|
|
543
603
|
const cookieApp = storyKit({
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
604
|
+
around: withIsolatedDatabase,
|
|
605
|
+
clock: "live",
|
|
606
|
+
*create() {
|
|
607
|
+
const { baseUrl } = yield* startHost();
|
|
608
|
+
const fetch = domFetch(baseUrl);
|
|
609
|
+
const client = createAuthClient({ baseURL: baseUrl, fetchOptions: { customFetchImpl: fetch } });
|
|
610
|
+
return { client, fetch };
|
|
611
|
+
},
|
|
612
|
+
layer: postgres,
|
|
613
|
+
name: "cookie auth",
|
|
614
|
+
stages: ["account"],
|
|
615
|
+
verbs: ({ client, fetch }, story) => authVerbs(client, fetch, story.tell),
|
|
556
616
|
});
|
|
557
617
|
```
|
|
558
618
|
|
|
@@ -584,15 +644,19 @@ The starter's [social application kit](https://github.com/ShivaeDev/platform/blo
|
|
|
584
644
|
The kit renders a Better Auth client whose `customFetchImpl` is `domFetch(baseUrl)`. The story calls `clickGitHubSignIn`, `settle` and `followRedirect` separately, then reads the heading, cookie and session. The screen driver settles on the screen's request state and reads the heading from the current document after navigation. The provider uses `fakeHttpService`. The authorize, token and user requests at the fake and a later session response provide evidence across the provider and application boundaries. The kit does not copy cookies into request headers.
|
|
585
645
|
|
|
586
646
|
```ts
|
|
587
|
-
socialApp.it(
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
647
|
+
socialApp.it(
|
|
648
|
+
"a social sign-in returns with a cookie session",
|
|
649
|
+
[],
|
|
650
|
+
function* ({ clickGitHubSignIn, settle, followRedirect, heading, cookie, session }) {
|
|
651
|
+
yield* clickGitHubSignIn();
|
|
652
|
+
yield* settle();
|
|
653
|
+
const response = yield* followRedirect();
|
|
654
|
+
expect(response.status).toBe(200);
|
|
655
|
+
expect(heading()).toBe("Signed in as alice@social.test");
|
|
656
|
+
expect(cookie()).not.toContain("session_token");
|
|
657
|
+
expect(yield* session()).toMatchObject({ user: { email: "alice@social.test" } });
|
|
658
|
+
},
|
|
659
|
+
);
|
|
596
660
|
```
|
|
597
661
|
|
|
598
662
|
`domFetch` uses the current window and its cookie jar; it does not isolate multiple users. Run stories using that window serially, and let the application's cleanup end its sessions, restore the page location and close its host. Cookies follow hostnames, not listener ports, so a different loopback port alone does not isolate accounts.
|
|
@@ -606,16 +670,17 @@ To use `settle()`, supply a `pending()` function that reads the application's ow
|
|
|
606
670
|
```ts
|
|
607
671
|
import { screenDriver } from "@shivaedev/test-story/server/screenDriver.ts";
|
|
608
672
|
|
|
609
|
-
verbs: ({ view, requests }, story) =>
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
673
|
+
verbs: ({ view, requests }, story) =>
|
|
674
|
+
screenDriver({
|
|
675
|
+
root: view.container,
|
|
676
|
+
pending: () => requests.pending,
|
|
677
|
+
tell: story.tell,
|
|
678
|
+
});
|
|
614
679
|
```
|
|
615
680
|
|
|
616
681
|
`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()`.
|
|
617
682
|
|
|
618
|
-
`text(selector?)`
|
|
683
|
+
`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.
|
|
619
684
|
|
|
620
685
|
`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.
|
|
621
686
|
|
|
@@ -625,38 +690,38 @@ verbs: ({ view, requests }, story) => screenDriver({
|
|
|
625
690
|
|
|
626
691
|
`accessible(element)` uses the same computation on an `Element` the kit already holds and tells no story line.
|
|
627
692
|
|
|
628
|
-
For React, pass `act: async (action) => { await act(action); }` using React's `act`. The adapter wraps each action and flushes renderer work before checking the pending signal, including while waiting for an asynchronous response. The
|
|
693
|
+
For React, pass `act: async (action) => { await act(action); }` using React's `act`. The adapter wraps each action and flushes renderer work before checking the pending signal, including while waiting for an asynchronous response. The driver itself has no renderer dependency.
|
|
629
694
|
|
|
630
|
-
Settlement has a live-time limit of 3 seconds, configurable with the driver's `timeoutMs` or per call with `settle({ timeoutMs })`, and fails with the current screen text and advice when that limit expires. Use the
|
|
695
|
+
Settlement has a live-time limit of 3 seconds, configurable with the driver's `timeoutMs` or per call with `settle({ timeoutMs })`, and fails with the current screen text and advice when that limit expires. Use the DOM environment above and scoped `routeOutbound` routing to reach `fakeHttpService`; the driver does not install another transport. The driver acts on happy-dom over loopback HTTP; it does not drive a real browser.
|
|
631
696
|
|
|
632
697
|
### API by module
|
|
633
698
|
|
|
634
699
|
Import each module with the prefix `@shivaedev/test-story/`; there is no root entry.
|
|
635
700
|
|
|
636
|
-
| Module
|
|
637
|
-
|
|
|
638
|
-
| `server/storyKit.ts`
|
|
639
|
-
| `server/
|
|
640
|
-
| `server/
|
|
641
|
-
| `server/
|
|
642
|
-
| `server/
|
|
643
|
-
| `server/
|
|
644
|
-
| `server/
|
|
645
|
-
| `server/
|
|
646
|
-
| `server/
|
|
647
|
-
| `server/
|
|
648
|
-
| `server/
|
|
701
|
+
| Module | Exports |
|
|
702
|
+
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
703
|
+
| `server/storyKit.ts` | `storyKit`, `Trait`, `RunUntilOptions`, `Story`, `RunHooks`, `StoryKitDefinition`, `Told`, `StoryBody`, `StoryTest`, `StoryIt`, `StoryKit` |
|
|
704
|
+
| `server/outcomes.ts` | `outcomes(rows)` |
|
|
705
|
+
| `server/domFetch.ts` | `domFetch(baseUrl)` |
|
|
706
|
+
| `server/seedCookies.ts` | `seedCookies(cookies)`, `DomCookie` |
|
|
707
|
+
| `server/routeOutbound.ts` | `routeOutbound(routes)` |
|
|
708
|
+
| `server/screenDriver.ts` | `screenDriver(options)`, `ScreenDriverOptions`, `ScreenDriver`, `ScreenTarget`, `MissingScreenPending` |
|
|
709
|
+
| `server/domNavigate.ts` | `domNavigate(url?)` |
|
|
710
|
+
| `server/genreTags.ts` | `genreTags(...kitNames)`, `GenreTag` |
|
|
711
|
+
| `server/domEnvironment.config.ts` | Default Vitest environment preserving Node host globals and happy-dom document transport |
|
|
712
|
+
| `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` |
|
|
713
|
+
| `server/forwardingProxy.ts` | `forwardingProxy(upstream, options?)`, `ForwardingProxyOptions` |
|
|
714
|
+
| `server/otlpReceiver.ts` | `otlpReceiver(options?)`, `OtlpSpan`, `OtlpExport`, `OtlpReceiverOptions` |
|
|
649
715
|
|
|
650
716
|
### Install and limits
|
|
651
717
|
|
|
652
718
|
```sh
|
|
653
|
-
pnpm add --save-dev @shivaedev/test-story @effect/vitest
|
|
719
|
+
pnpm add --save-dev @shivaedev/test-story @effect/platform-node @effect/vitest effect vitest
|
|
654
720
|
```
|
|
655
721
|
|
|
656
|
-
`@effect/vitest`, `effect` and `vitest` are peers, so the application's own versions run the stories.
|
|
722
|
+
`@effect/platform-node`, `@effect/vitest`, `effect` and `vitest` are peers, so the application's own versions run the stories. The Node adapter supplies the digest implementation retained by `TestCrypto`.
|
|
657
723
|
|
|
658
724
|
Test-story is an application's one test dependency: it brings [`@shivaedev/test`](https://github.com/ShivaeDev/platform/tree/main/packages/test#readme) and [`@shivaedev/test-sql`](https://github.com/ShivaeDev/platform/tree/main/packages/test-sql#readme), which an application on `@shivaedev/platform` imports by their own names without listing them. `@effect/sql-pg` is an optional peer for `test-sql`'s PostgreSQL helpers; install it when the stories use them. A library that tests with test-story still declares `test` or `test-sql` directly when it imports them.
|
|
659
|
-
|
|
660
725
|
- The package runs inside Vitest. The story reaches the failure by rewriting the first error's message in Vitest's `onTestFailed` hook.
|
|
661
726
|
- 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.
|
|
662
727
|
- A kit's `it` is created when the kit is defined, so a kit lives in a module that only Vitest test files import.
|