@shivaedev/test-story 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.4.1 - 2026-10-17
+
+### Fixed
+
+- Run engine creation without the story's parent span, so in-process HTTP handlers capture an independent context: requests without trace headers start root traces, and `traceparent` continues the supplied trace. Traits, steps and the story body retain their story span.
+
 ## 0.4.0 - 2026-10-17
 
 ### Added

package/README.md

@@ -146,6 +146,63 @@ const app = storyKit({
 
 Routing uses the global dispatcher that Node's built-in `fetch` already uses. It is installed 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`.
 
+#### Asserting on application traces
+
+Start an in-process host in `create`. That hook runs without the ambient parent span, so an Effect HTTP handler that captures its context does not inherit a span placed around the story. A request without trace headers starts a root trace; a request with `traceparent` continues that trace. The tracer, services and per-story Scope remain available during creation. Traits, engine steps and the story body keep the span supplied by `around`.
+
+A kit can collect spans with a native in-memory tracer, or start a fake OTLP receiver and point the application's exporter at it. Keep collection and any exporter flush or bounded wait in the kit's verbs. Assert only after the request span has ended. This small in-memory kit uses Effect's Web Request handler as its host:
+
+```ts
+import { Effect, Tracer } from "effect";
+import { HttpEffect, HttpServerResponse } from "effect/http";
+import { expect } from "vitest";
+import { storyKit } from "@shivaedev/test-story/storyKit.ts";
+
+const spans: Tracer.NativeSpan[] = [];
+const tracer = Tracer.make({
+  span: (options) => {
+    const span = new Tracer.NativeSpan(options);
+    spans.push(span);
+    return span;
+  },
+});
+
+const app = storyKit({
+  around: (effect) => effect.pipe(Effect.withSpan("story"), Effect.withTracer(tracer)),
+  *create() {
+    const context = yield* Effect.context<never>();
+    return HttpEffect.toWebHandlerWith(context)(Effect.succeed(HttpServerResponse.text("ok")));
+  },
+  name: "traced application",
+  stages: ["ready"],
+  verbs: (handler) => ({
+    request: (headers: HeadersInit = {}) => Effect.promise(async () => {
+      const response = await handler(new Request("http://app.test/", { headers }));
+      await response.text();
+      const span = spans.filter((span) => span.kind === "server").at(-1);
+      if (span === undefined) throw new Error("The request exported no server span");
+      return span;
+    }),
+  }),
+});
+
+app.it("a request is its own root trace", [], function* ({ request }) {
+  const storySpan = yield* Effect.currentSpan;
+  const span = yield* request();
+  expect(span.parent._tag).toBe("None");
+  expect(span.traceId).not.toBe(storySpan.traceId);
+  expect(span.status._tag).toBe("Ended");
+});
+
+app.it("a request continues its supplied trace", [], function* ({ request }) {
+  const span = yield* request({ traceparent: "00-1234567890abcdef1234567890abcdef-1234567890abcdef-01" });
+  expect(span.traceId).toBe("1234567890abcdef1234567890abcdef");
+  expect(span.parent).toMatchObject({ value: { spanId: "1234567890abcdef" } });
+});
+```
+
+The package's [tracing kit](https://github.com/ShivaeDev/platform/blob/main/packages/test-story/src/test-support/tracingApp.ts) and [stories](https://github.com/ShivaeDev/platform/blob/main/packages/test-story/src/server/hostTracing.spec.ts) also assert that two requests have different trace IDs, request work stays under its request span, and traits and engine steps stay under the story span. Creation only removes the incoming parent: spans that application startup explicitly creates still follow native Effect semantics.
+
 ### 2. Once per feature: traits and verbs
 
 A trait is a line and a change, tagged with a stage:

package/dist/server/internal/start.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../../src/server/internal/start.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAK1C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAQ,MAAM,mBAAmB,CAAC;AAEjG,eAAO,MAAM,KAAK;;oBAehB,CAAC"}
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../../src/server/internal/start.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,MAAM,EAAU,MAAM,QAAQ,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAK1C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAQ,MAAM,mBAAmB,CAAC;AAEjG,eAAO,MAAM,KAAK;;oBAehB,CAAC"}

package/dist/server/internal/start.js

@@ -1,11 +1,11 @@
-import { Effect } from "effect";
+import { Context, Effect, Tracer } from "effect";
 import { callSite } from "#internal/callSite.ts";
 import { hooked } from "#internal/hooked.ts";
 import { narrate } from "#internal/narration.ts";
 import { runUntil } from "#internal/runUntil.ts";
 import { seed } from "#internal/seed.ts";
 export const start = Effect.fnUntraced(function* (definition, given, context) {
-    const engine = yield* hooked(definition.create);
+    const engine = yield* hooked(definition.create).pipe(Effect.updateContext(Context.omit(Tracer.ParentSpan)));
     const narration = narrate({ engine, inspect: definition.inspect, name: definition.name }, context);
     yield* seed(definition, engine, narration, given);
     const story = {

package/dist/server/internal/start.js.map

@@ -1 +1 @@
-{"version":3,"file":"start.js","sourceRoot":"","sources":["../../../src/server/internal/start.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAA0D,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEjG,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,UAA2B,EAAE,KAA4B,EAAE,OAAoB;IAChI,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IACnG,KAAK,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAClD,MAAM,KAAK,GAAe;QACzB,MAAM;QACN,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;YAC5B,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAC;YACxB,SAAS,CAAC,EAAE,GAAG,IAAI,CAAC;YACpB,OAAO,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QACvI,CAAC;QACD,IAAI,EAAE,SAAS,CAAC,IAAI;KACpB,CAAC;IACF,OAAO,EAAE,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;AACtD,CAAC,CAAC,CAAC"}
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../../../src/server/internal/start.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAA0D,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEjG,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,UAA2B,EAAE,KAA4B,EAAE,OAAoB;IAChI,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC5G,MAAM,SAAS,GAAG,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IACnG,KAAK,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAClD,MAAM,KAAK,GAAe;QACzB,MAAM;QACN,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;YAC5B,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAC;YACxB,SAAS,CAAC,EAAE,GAAG,IAAI,CAAC;YACpB,OAAO,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QACvI,CAAC;QACD,IAAI,EAAE,SAAS,CAAC,IAAI;KACpB,CAAC;IACF,OAAO,EAAE,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;AACtD,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/test-story",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Tests that read like stories over the real engine: a story kit per engine with its own it, traits per feature, and a failure that prints the story, where it stopped and the engine's state",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/test-story#readme",
   "bugs": {

package/src/server/internal/start.ts

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { Context, Effect, Tracer } from "effect";
 import type { TestContext } from "vitest";
 import { callSite } from "#internal/callSite.ts";
 import { hooked } from "#internal/hooked.ts";
@@ -7,7 +7,7 @@ import { runUntil } from "#internal/runUntil.ts";
 import { type LooseDefinition, type LooseStory, type LooseTrait, seed } from "#internal/seed.ts";
 
 export const start = Effect.fnUntraced(function* (definition: LooseDefinition, given: readonly LooseTrait[], context: TestContext) {
-	const engine = yield* hooked(definition.create);
+	const engine = yield* hooked(definition.create).pipe(Effect.updateContext(Context.omit(Tracer.ParentSpan)));
 	const narration = narrate({ engine, inspect: definition.inspect, name: definition.name }, context);
 	yield* seed(definition, engine, narration, given);
 	const story: LooseStory = {