@shivaedev/test-story 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.11.0 - 2026-10-18
+
+### Added
+
+- Pass a UTC `DateTime` to the existing `clock` option to pin a story or Effect fixture before its per-test setup runs. The exported `EffectClock` type now accepts `DateTime.Utc` alongside `"test"` and `"live"`. Hosts, workers and screens acquired with the story's Effect Context share native `Clock` / `TestClock`, including explicit `TestClock.adjust` advances; application code using `Clock` or `DateTime.now` needs no changes.
+
 ## 0.10.0 - 2026-10-18
 
 ### Added

package/README.md

@@ -131,7 +131,7 @@ This is the bakery kit this package tests itself with. `emptyBakery`, `stillWait
 | `name` | What the engine is called in failures, "the bakery", and the kit's genre, "Bakery Story". |
 | `outbound` | Optional. A map of exact hostnames to fake server origins for Node fetch and the DOM environment's document requests. |
 | `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. |
-| `clock` | Optional. `"test"` by default, or `"live"` for HTTP and DOM stories. A story’s `options.clock` takes precedence. |
+| `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. |
 | `create()` | A fresh engine. Every story starts from a new one. |
 | `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. |
 | `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. |
@@ -379,6 +379,29 @@ bakery.it("tells each step into the story", [ovenIsLit()], function* ({ baker, o
 
 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.
 
+### Pinning time
+
+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`:
+
+```ts
+import { DateTime } from "effect";
+import * as TestClock from "effect/testing/TestClock";
+
+app.it("shows the worker's date", [], function* ({ click, settle, text }) {
+  yield* click("button");
+  yield* settle();
+  expect(text("#worker")).toBe("Worker: since Oct 17");
+  yield* TestClock.adjust("1 day");
+  yield* click("button");
+  yield* settle();
+  expect(text("#worker")).toBe("Worker: since Oct 18");
+}, { clock: DateTime.makeUnsafe("2026-10-17T12:34:56.000Z") });
+```
+
+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.
+
+The [clock application stories](src/server/fixedClock.dom.spec.ts) run loopback HTTP, a queued worker that writes a timestamp to a file, and a DOM screen with its own Effect runner. They check exact timestamps and rendered dates, advancing time, and a live story without the option. A live-clock kit still runs on real time when a story omits the override.
+
 ### Running the engine
 
 Hooks and steps that wait for real workers can use `withLive(Effect.sleep(...))` or `withLive(eventually(...))` from `@shivaedev/effect-test/withLive.ts` and `@shivaedev/effect-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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/test-story",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "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": {
@@ -41,7 +41,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@shivaedev/effect-test": "0.6.0",
+    "@shivaedev/effect-test": "0.7.0",
     "dom-accessibility-api": "0.7.1"
   },
   "devDependencies": {