@shivaedev/test-story 0.22.0 → 0.24.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 +40 -0
- package/README.md +252 -213
- package/dist/server/domFetch.d.ts +6 -1
- package/dist/server/domFetch.d.ts.map +1 -1
- package/dist/server/domFetch.js +3 -3
- package/dist/server/domFetch.js.map +1 -1
- package/dist/server/forwardingProxy.d.ts +2 -0
- package/dist/server/forwardingProxy.d.ts.map +1 -1
- package/dist/server/forwardingProxy.js +65 -6
- package/dist/server/forwardingProxy.js.map +1 -1
- package/dist/server/internal/adapters/memberFetch.d.ts +3 -0
- package/dist/server/internal/adapters/memberFetch.d.ts.map +1 -0
- package/dist/server/internal/adapters/memberFetch.js +68 -0
- package/dist/server/internal/adapters/memberFetch.js.map +1 -0
- 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/memberScreens.d.ts +20 -0
- package/dist/server/memberScreens.d.ts.map +1 -0
- package/dist/server/memberScreens.js +40 -0
- package/dist/server/memberScreens.js.map +1 -0
- package/dist/server/screenDriver.d.ts +3 -2
- package/dist/server/screenDriver.d.ts.map +1 -1
- package/dist/server/screenDriver.js +15 -3
- package/dist/server/screenDriver.js.map +1 -1
- package/dist/server/seedCookies.d.ts +2 -1
- package/dist/server/seedCookies.d.ts.map +1 -1
- package/dist/server/seedCookies.js +4 -4
- package/dist/server/seedCookies.js.map +1 -1
- package/package.json +11 -11
- package/src/server/domFetch.ts +6 -3
- package/src/server/forwardingProxy.ts +81 -23
- package/src/server/internal/adapters/memberFetch.ts +67 -0
- package/src/server/internal/screenElements.ts +11 -0
- package/src/server/memberScreens.ts +61 -0
- package/src/server/screenDriver.ts +18 -5
- package/src/server/seedCookies.ts +4 -4
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
|
|
|
@@ -43,7 +43,7 @@ The first line is the assertion's own message. The box under it tells a reader w
|
|
|
43
43
|
|
|
44
44
|
## Using it
|
|
45
45
|
|
|
46
|
-
Before writing or reviewing
|
|
46
|
+
Before writing or reviewing stories, follow the [story-testing skill](https://github.com/ShivaeDev/platform/blob/main/packages/skills/skills/story-testing/SKILL.md), shipped by `@shivaedev/skills`. It owns the rules for how a story reads, observable evidence, boundary-driven setup, verbs and readouts, assertions, jobs, framework gaps, faked preconditions, database isolation and focused runs. The examples below explain this package's API; framework fixtures exercise this package's responsibilities, rather than prescribe application scenarios.
|
|
47
47
|
|
|
48
48
|
### How to think about it
|
|
49
49
|
|
|
@@ -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,12 +64,12 @@ 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.
|
|
@@ -83,64 +82,63 @@ Every story gets Effect's native `TestCrypto` service with seed `0`, created afr
|
|
|
83
82
|
|
|
84
83
|
```ts
|
|
85
84
|
export const bakery = storyKit({
|
|
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
|
-
|
|
124
|
-
|
|
125
|
-
}),
|
|
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
|
+
}),
|
|
126
124
|
});
|
|
127
125
|
```
|
|
128
126
|
|
|
129
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`.
|
|
130
128
|
|
|
131
|
-
| Hook
|
|
132
|
-
|
|
|
133
|
-
| `name`
|
|
134
|
-
| `outbound`
|
|
135
|
-
| `around(effect)`
|
|
136
|
-
| `clock`
|
|
137
|
-
| `create()`
|
|
138
|
-
| `layer`
|
|
139
|
-
| `stages`
|
|
140
|
-
| `after`
|
|
141
|
-
| `run`
|
|
142
|
-
| `inspect`
|
|
143
|
-
| `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. |
|
|
144
142
|
|
|
145
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:
|
|
146
144
|
|
|
@@ -149,7 +147,7 @@ import { genreTags } from "@shivaedev/test-story/server/genreTags.ts";
|
|
|
149
147
|
import { defineConfig } from "vitest/config";
|
|
150
148
|
|
|
151
149
|
export default defineConfig({
|
|
152
|
-
|
|
150
|
+
test: { tags: genreTags("bakery", "mill") },
|
|
153
151
|
});
|
|
154
152
|
```
|
|
155
153
|
|
|
@@ -166,16 +164,16 @@ import { bakery, hasDough, ovenIsLit } from "./bakery.ts";
|
|
|
166
164
|
import { mill, sailsAreTurning } from "./mill.ts";
|
|
167
165
|
|
|
168
166
|
export const village = storyKit({
|
|
169
|
-
|
|
170
|
-
|
|
167
|
+
extends: [mill, bakery],
|
|
168
|
+
name: "village",
|
|
171
169
|
});
|
|
172
170
|
|
|
173
171
|
village.it("mills flour and bakes loaves", [sailsAreTurning(), ovenIsLit(), hasDough(2)], function* ({ miller, oven, story }) {
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
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);
|
|
179
177
|
});
|
|
180
178
|
```
|
|
181
179
|
|
|
@@ -183,7 +181,7 @@ village.it("mills flour and bakes loaves", [sailsAreTurning(), ovenIsLit(), hasD
|
|
|
183
181
|
|
|
184
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.
|
|
185
183
|
|
|
186
|
-
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
|
|
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.
|
|
187
185
|
|
|
188
186
|
#### Routing outbound HTTP
|
|
189
187
|
|
|
@@ -191,14 +189,14 @@ When application code calls a hard-coded third-party URL, set `outbound` on its
|
|
|
191
189
|
|
|
192
190
|
```ts
|
|
193
191
|
const app = storyKit({
|
|
194
|
-
|
|
195
|
-
|
|
192
|
+
...appDefinition,
|
|
193
|
+
outbound: { "github.com": fakeUrl, "api.github.com": fakeUrl },
|
|
196
194
|
});
|
|
197
195
|
```
|
|
198
196
|
|
|
199
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.
|
|
200
198
|
|
|
201
|
-
`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.
|
|
202
200
|
|
|
203
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`.
|
|
204
202
|
|
|
@@ -217,49 +215,50 @@ import { expect } from "vitest";
|
|
|
217
215
|
import { storyKit } from "@shivaedev/test-story/server/storyKit.ts";
|
|
218
216
|
|
|
219
217
|
const app = storyKit({
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
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
|
+
}),
|
|
247
246
|
});
|
|
248
247
|
|
|
249
248
|
app.it("a request is its own root trace", [], function* ({ request, requestSpan }) {
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
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");
|
|
256
255
|
});
|
|
257
256
|
|
|
258
257
|
app.it("a request continues its supplied trace", [], function* ({ request, requestSpan }) {
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
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" } });
|
|
263
262
|
});
|
|
264
263
|
```
|
|
265
264
|
|
|
@@ -293,10 +292,10 @@ Use `otlpReceiver` from `@shivaedev/test-story/server/otlpReceiver.ts` in a kit'
|
|
|
293
292
|
|
|
294
293
|
```ts
|
|
295
294
|
app.it("exports the work span", [], function* ({ runWork, disposeRuntime, spans, requests }) {
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
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);
|
|
300
299
|
});
|
|
301
300
|
```
|
|
302
301
|
|
|
@@ -352,7 +351,7 @@ const bytes = yield* Fiber.join(pending);
|
|
|
352
351
|
|
|
353
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.
|
|
354
353
|
|
|
355
|
-
`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.
|
|
356
355
|
|
|
357
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.
|
|
358
357
|
|
|
@@ -398,24 +397,24 @@ A trait is a line and a change, tagged with a stage:
|
|
|
398
397
|
|
|
399
398
|
```ts
|
|
400
399
|
export function hasDough(count: number) {
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
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
|
+
});
|
|
407
406
|
}
|
|
408
407
|
|
|
409
408
|
export function hasFlourDelivered(sacks: number) {
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
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
|
+
});
|
|
415
414
|
}
|
|
416
415
|
|
|
417
416
|
export function morningShift() {
|
|
418
|
-
|
|
417
|
+
return bakery.traits(ovenIsLit(), hasBowls(1));
|
|
419
418
|
}
|
|
420
419
|
```
|
|
421
420
|
|
|
@@ -453,15 +452,15 @@ A verb that a feature adds goes into the kit's `verbs`. It acts through the engi
|
|
|
453
452
|
|
|
454
453
|
```ts
|
|
455
454
|
bakery.it("tells each step into the story", [ovenIsLit()], function* ({ baker, oven, story }) {
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
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
|
+
]);
|
|
465
464
|
});
|
|
466
465
|
```
|
|
467
466
|
|
|
@@ -475,13 +474,13 @@ For several outcomes after one action, use `outcomes` from `@shivaedev/test-stor
|
|
|
475
474
|
import { outcomes } from "@shivaedev/test-story/server/outcomes.ts";
|
|
476
475
|
|
|
477
476
|
accounts.it("removing Bob leaves Alice signed in", [bobAndAliceAreSignedIn()], function* ({ remove, request, sessions }) {
|
|
478
|
-
|
|
477
|
+
yield* remove("bob");
|
|
479
478
|
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
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
|
+
});
|
|
485
484
|
});
|
|
486
485
|
```
|
|
487
486
|
|
|
@@ -489,41 +488,57 @@ accounts.it("removing Bob leaves Alice signed in", [bobAndAliceAreSignedIn()], f
|
|
|
489
488
|
|
|
490
489
|
```ts
|
|
491
490
|
accounts.it("removing Bob ends his session", [bobIsSignedIn()], function* ({ remove, request }) {
|
|
492
|
-
|
|
491
|
+
yield* remove("bob");
|
|
493
492
|
|
|
494
|
-
|
|
493
|
+
expect(yield* request("bob")).toBe("unauthorized");
|
|
495
494
|
});
|
|
496
495
|
```
|
|
497
496
|
|
|
498
497
|
### Pinning time
|
|
499
498
|
|
|
500
|
-
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
|
|
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 with native `TestClock.adjust` in a kit verb, so the spec names the time that passes:
|
|
501
500
|
|
|
502
501
|
```ts
|
|
503
|
-
import { DateTime } from "effect";
|
|
504
502
|
import * as TestClock from "effect/testing/TestClock";
|
|
505
503
|
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
504
|
+
verbs: (engine, story) => ({
|
|
505
|
+
aDayPasses: () => {
|
|
506
|
+
story.tell("a day passes");
|
|
507
|
+
return TestClock.adjust("1 day");
|
|
508
|
+
},
|
|
509
|
+
}),
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
```ts
|
|
513
|
+
import { DateTime } from "effect";
|
|
514
|
+
|
|
515
|
+
app.it(
|
|
516
|
+
"a day later, the worker shows the next date",
|
|
517
|
+
[],
|
|
518
|
+
function* ({ aDayPasses, click, settle, text }) {
|
|
519
|
+
yield* click("button");
|
|
520
|
+
yield* settle();
|
|
521
|
+
expect(text("#worker")).toBe("Worker: since Oct 17");
|
|
522
|
+
|
|
523
|
+
yield* aDayPasses();
|
|
524
|
+
|
|
525
|
+
yield* click("button");
|
|
526
|
+
yield* settle();
|
|
527
|
+
expect(text("#worker")).toBe("Worker: since Oct 18");
|
|
528
|
+
},
|
|
529
|
+
{ clock: DateTime.makeUnsafe("2026-10-17T12:34:56.000Z") },
|
|
530
|
+
);
|
|
515
531
|
```
|
|
516
532
|
|
|
517
533
|
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.
|
|
518
534
|
|
|
519
|
-
|
|
535
|
+
A live-clock kit still runs on real time when a story omits the override.
|
|
520
536
|
|
|
521
537
|
### Running the engine
|
|
522
538
|
|
|
523
539
|
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.
|
|
524
540
|
|
|
525
541
|
`story.runUntil(condition, { maxSteps })` returns an Effect that asks three questions before every step:
|
|
526
|
-
|
|
527
542
|
1. `run.failed` returns a sentence: it dies with it, even when the condition also holds.
|
|
528
543
|
2. The condition holds: it succeeds.
|
|
529
544
|
3. `maxSteps` steps have run, or the kit's `run.maxSteps` when the call names none: it dies with `run.diagnose`.
|
|
@@ -540,7 +555,6 @@ That is what `oven.bakesEverything(12)` dies with when the baker keeps a sourdou
|
|
|
540
555
|
### When a story fails
|
|
541
556
|
|
|
542
557
|
After the engine has been created, a failing story test adds the story to its first error, as in the examples above:
|
|
543
|
-
|
|
544
558
|
- a short guide to reading the story, in a box;
|
|
545
559
|
- every line in order, traits marked `given`;
|
|
546
560
|
- `✗` 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;
|
|
@@ -569,28 +583,28 @@ For full-app stories, use `around: withIsolatedDatabase` from `@shivaedev/test-s
|
|
|
569
583
|
|
|
570
584
|
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.
|
|
571
585
|
|
|
572
|
-
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
|
|
586
|
+
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`.
|
|
573
587
|
|
|
574
588
|
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`.
|
|
575
589
|
|
|
576
590
|
### DOM stories with cookie sessions
|
|
577
591
|
|
|
578
|
-
Install `happy-dom
|
|
592
|
+
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:
|
|
579
593
|
|
|
580
594
|
```ts
|
|
581
595
|
import { fileURLToPath } from "node:url";
|
|
582
596
|
import { defineConfig } from "vitest/config";
|
|
583
597
|
|
|
584
598
|
export default defineConfig({
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
599
|
+
test: {
|
|
600
|
+
environment: fileURLToPath(import.meta.resolve("@shivaedev/test-story/server/domEnvironment.config.ts")),
|
|
601
|
+
},
|
|
588
602
|
});
|
|
589
603
|
```
|
|
590
604
|
|
|
591
605
|
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.
|
|
592
606
|
|
|
593
|
-
`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
|
|
607
|
+
`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.
|
|
594
608
|
|
|
595
609
|
Call it in the kit's `create` hook after starting the host:
|
|
596
610
|
|
|
@@ -599,18 +613,18 @@ import { createAuthClient } from "better-auth/react";
|
|
|
599
613
|
import { domFetch } from "@shivaedev/test-story/server/domFetch.ts";
|
|
600
614
|
|
|
601
615
|
const cookieApp = storyKit({
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
616
|
+
around: withIsolatedDatabase,
|
|
617
|
+
clock: "live",
|
|
618
|
+
*create() {
|
|
619
|
+
const { baseUrl } = yield* startHost();
|
|
620
|
+
const fetch = domFetch(baseUrl);
|
|
621
|
+
const client = createAuthClient({ baseURL: baseUrl, fetchOptions: { customFetchImpl: fetch } });
|
|
622
|
+
return { client, fetch };
|
|
623
|
+
},
|
|
624
|
+
layer: postgres,
|
|
625
|
+
name: "cookie auth",
|
|
626
|
+
stages: ["account"],
|
|
627
|
+
verbs: ({ client, fetch }, story) => authVerbs(client, fetch, story.tell),
|
|
614
628
|
});
|
|
615
629
|
```
|
|
616
630
|
|
|
@@ -642,18 +656,40 @@ The starter's [social application kit](https://github.com/ShivaeDev/platform/blo
|
|
|
642
656
|
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.
|
|
643
657
|
|
|
644
658
|
```ts
|
|
645
|
-
socialApp.it(
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
659
|
+
socialApp.it(
|
|
660
|
+
"a social sign-in returns with a cookie session",
|
|
661
|
+
[],
|
|
662
|
+
function* ({ clickGitHubSignIn, settle, followRedirect, heading, cookie, session }) {
|
|
663
|
+
yield* clickGitHubSignIn();
|
|
664
|
+
yield* settle();
|
|
665
|
+
const response = yield* followRedirect();
|
|
666
|
+
expect(response.status).toBe(200);
|
|
667
|
+
expect(heading()).toBe("Signed in as alice@social.test");
|
|
668
|
+
expect(cookie()).not.toContain("session_token");
|
|
669
|
+
expect(yield* session()).toMatchObject({ user: { email: "alice@social.test" } });
|
|
670
|
+
},
|
|
671
|
+
);
|
|
654
672
|
```
|
|
655
673
|
|
|
656
|
-
`domFetch`
|
|
674
|
+
`domFetch` defaults to the current window and its cookie jar. 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.
|
|
675
|
+
|
|
676
|
+
#### Several members on one host
|
|
677
|
+
|
|
678
|
+
Use `memberScreens` from `@shivaedev/test-story/server/memberScreens.ts` inside a DOM kit's `create` hook. Supply `baseUrl`, `mount(member)` returning an Effect, and `verbs(member, tell)` returning that member's verbs and readouts. Each `MemberScreen` carries its `name`, `fetch`, `registry` and `root`. Mount the application into that root with that registry, and give its auth and HTTP clients the member's fetch. Cookie contexts are independent even when every member uses the same host.
|
|
679
|
+
|
|
680
|
+
A trait calls `yield* members.open("ada", cookies)` with a minted session's cookies. The kit's verbs hook returns `members.verbs(story.tell)`, exposing `as("ada")` to the spec. Member narration includes the name. The calling Scope closes every cookie context, disposes every registry and removes every root. Register renderer unmounting in the mount hook with `Effect.acquireRelease` so it runs before the registry and root are released.
|
|
681
|
+
|
|
682
|
+
```ts
|
|
683
|
+
sharedLists.it("grace sees ada's addition", [signedInMembers("ada", "grace")], function* ({ as }) {
|
|
684
|
+
yield* as("ada").enter("input", "Bread");
|
|
685
|
+
yield* as("ada").submit();
|
|
686
|
+
yield* as("ada").settle();
|
|
687
|
+
yield* as("grace").click({ role: "button", name: "Refresh" });
|
|
688
|
+
yield* as("grace").settle();
|
|
689
|
+
|
|
690
|
+
expect(as("grace").text("output")).toBe("grace's list: ada: Bread");
|
|
691
|
+
});
|
|
692
|
+
```
|
|
657
693
|
|
|
658
694
|
### Driving a screen
|
|
659
695
|
|
|
@@ -664,16 +700,19 @@ To use `settle()`, supply a `pending()` function that reads the application's ow
|
|
|
664
700
|
```ts
|
|
665
701
|
import { screenDriver } from "@shivaedev/test-story/server/screenDriver.ts";
|
|
666
702
|
|
|
667
|
-
verbs: ({ view, requests }, story) =>
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
703
|
+
verbs: ({ view, requests }, story) =>
|
|
704
|
+
screenDriver({
|
|
705
|
+
root: view.container,
|
|
706
|
+
pending: () => requests.pending,
|
|
707
|
+
tell: story.tell,
|
|
708
|
+
});
|
|
672
709
|
```
|
|
673
710
|
|
|
674
711
|
`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()`.
|
|
675
712
|
|
|
676
|
-
`
|
|
713
|
+
`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.
|
|
714
|
+
|
|
715
|
+
`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.
|
|
677
716
|
|
|
678
717
|
`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.
|
|
679
718
|
|
|
@@ -683,39 +722,39 @@ verbs: ({ view, requests }, story) => screenDriver({
|
|
|
683
722
|
|
|
684
723
|
`accessible(element)` uses the same computation on an `Element` the kit already holds and tells no story line.
|
|
685
724
|
|
|
686
|
-
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
|
|
725
|
+
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.
|
|
687
726
|
|
|
688
|
-
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
|
|
727
|
+
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.
|
|
689
728
|
|
|
690
729
|
### API by module
|
|
691
730
|
|
|
692
731
|
Import each module with the prefix `@shivaedev/test-story/`; there is no root entry.
|
|
693
732
|
|
|
694
|
-
| Module
|
|
695
|
-
|
|
|
696
|
-
| `server/storyKit.ts`
|
|
697
|
-
| `server/outcomes.ts`
|
|
698
|
-
| `server/domFetch.ts`
|
|
699
|
-
| `server/seedCookies.ts`
|
|
700
|
-
| `server/routeOutbound.ts`
|
|
701
|
-
| `server/screenDriver.ts`
|
|
702
|
-
| `server/
|
|
703
|
-
| `server/
|
|
704
|
-
| `server/
|
|
705
|
-
| `server/
|
|
706
|
-
| `server/
|
|
707
|
-
| `server/
|
|
733
|
+
| Module | Exports |
|
|
734
|
+
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
735
|
+
| `server/storyKit.ts` | `storyKit`, `Trait`, `RunUntilOptions`, `Story`, `RunHooks`, `StoryKitDefinition`, `Told`, `StoryBody`, `StoryTest`, `StoryIt`, `StoryKit` |
|
|
736
|
+
| `server/outcomes.ts` | `outcomes(rows)` |
|
|
737
|
+
| `server/domFetch.ts` | `domFetch(baseUrl, target?)` |
|
|
738
|
+
| `server/seedCookies.ts` | `seedCookies(cookies, target?)`, `DomCookie` |
|
|
739
|
+
| `server/routeOutbound.ts` | `routeOutbound(routes)` |
|
|
740
|
+
| `server/screenDriver.ts` | `screenDriver(options)`, `ScreenDriverOptions`, `ScreenDriver`, `ScreenTarget`, `MissingScreenPending` |
|
|
741
|
+
| `server/memberScreens.ts` | `memberScreens(options)`, `MemberScreen` |
|
|
742
|
+
| `server/domNavigate.ts` | `domNavigate(url?)` |
|
|
743
|
+
| `server/genreTags.ts` | `genreTags(...kitNames)`, `GenreTag` |
|
|
744
|
+
| `server/domEnvironment.config.ts` | Default Vitest environment preserving Node host globals and happy-dom document transport |
|
|
745
|
+
| `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` |
|
|
746
|
+
| `server/forwardingProxy.ts` | `forwardingProxy(upstream, options?)`, `ForwardingProxyOptions` |
|
|
747
|
+
| `server/otlpReceiver.ts` | `otlpReceiver(options?)`, `OtlpSpan`, `OtlpExport`, `OtlpReceiverOptions` |
|
|
708
748
|
|
|
709
749
|
### Install and limits
|
|
710
750
|
|
|
711
751
|
```sh
|
|
712
|
-
pnpm add --save-dev @shivaedev/test-story @effect/platform-node
|
|
752
|
+
pnpm add --save-dev @shivaedev/test-story @effect/platform-node @effect/vitest effect vitest
|
|
713
753
|
```
|
|
714
754
|
|
|
715
755
|
`@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`.
|
|
716
756
|
|
|
717
757
|
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.
|
|
718
|
-
|
|
719
758
|
- The package runs inside Vitest. The story reaches the failure by rewriting the first error's message in Vitest's `onTestFailed` hook.
|
|
720
759
|
- 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.
|
|
721
760
|
- A kit's `it` is created when the kit is defined, so a kit lives in a module that only Vitest test files import.
|