@wardic/test 0.0.0-stage → 1.0.0-rc.2

package/src/input.ts

@@ -0,0 +1,104 @@
+import * as InputSource from "@wardic/core/InputSource"
+import * as Bool from "effect/Boolean"
+import * as Effect from "effect/Effect"
+import * as Predicate from "effect/Predicate"
+import * as Layer from "effect/Layer"
+import * as UndefinedOr from "effect/UndefinedOr"
+import * as Option from "effect/Option"
+import * as Feeds from "./feeds.ts"
+
+/**
+ * An InputSource that replays fixed scripts of events, as **Input feeds** that end after their
+ * script: a Stream over one ends too. `pointer(target)` replays the same `pointerEvents`,
+ * `focus(target)` the same `focusEvents` and `keyboard(target)` the same `keyEvents` to each
+ * subscriber (each ignores `target` — tests address a single surface). The first positional arg is
+ * pointer events for back-compat; focus and key events are optional, defaulting to empty so existing
+ * call sites emit nothing on them. Each script plays whole when its feed is subscribed, so scripts of
+ * two kinds don't interleave: a test that needs them to pushes them ({@link pushable}). Called with no
+ * args it yields an InputSource that emits nothing — for tests that don't exercise gestures. It adopts
+ * no pointer: `adoptPointer` delivers nothing.
+ */
+// Input feeds: #318. adoptPointer: #431.
+export const layer = (
+  pointerEvents: ReadonlyArray<InputSource.PointerLikeEvent> = [],
+  focusEvents: ReadonlyArray<InputSource.FocusLikeEvent> = [],
+  keyEvents: ReadonlyArray<InputSource.KeyboardLikeEvent> = [],
+): Layer.Layer<InputSource.InputSource> =>
+  Layer.succeed(InputSource.InputSource, {
+    pointer: () => Feeds.script(pointerEvents),
+    keyboard: () => Feeds.script(keyEvents),
+    focus: () => Feeds.script(focusEvents),
+    adoptPointer: () => Option.none(),
+  })
+
+/**
+ * A push-based InputSource for tests that need to interleave pointer events with
+ * other effects (e.g. advancing the Clock between a release and a re-grab). Unlike
+ * {@link layer} — which replays a fixed script that drains immediately — this
+ * form lets the test `push` events one at a time, on its own schedule.
+ *
+ * Backed by a hub (`feeds.ts`) so that every subscription to `pointer(target)`
+ * hears every event: a consumer may subscribe to `input.pointer(target)` more than once
+ * (a binding's drag track reads the drag fold and the grabs). There is no replay buffer,
+ * so only events pushed *after* a subscription is live reach it.
+ *
+ * `push` doesn't yield: a subscriber handles the event inside the push, as an
+ * Environment's consumers handle a real event inside its dispatch, so a pipeline that hops
+ * through Effect's scheduler on its way to its sink hasn't got there when `push` returns,
+ * and its test sees it.
+ *
+ * Returns `{ layer, push }`. Resolve it inside an `Effect.gen`, provide `layer`,
+ * and drive the surface with `push`:
+ *
+ * @example
+ * const input = yield* TestInput.pushable()
+ * yield* Stream.runForEach(drag(undefined), …).pipe(Effect.fork…)  // subscribe
+ * yield* input.push(ev("down", 0, 0, 0))
+ *
+ * Returns `pushFocus` and `pushKey` alongside `push` so focus/blur transitions and keys can be
+ * driven on the same schedule; `focus(target)` and `keyboard(target)` mirror `pointer(target)`, each
+ * with its own hub.
+ *
+ * `adoptPointer(target, raw)` takes a pointer event as its `raw`: a pressed one is pushed on
+ * the pointer hub as an adopted down, inside the call, as the DOM's is. The hub holds no pointer, so
+ * the test pushes that pointer's later events itself.
+ *
+ * `options.focusWithin` is the source's `focusWithin`, for a test of a **Keyboard press** that
+ * holds its keys only while focus is within its target. Without it the source says nothing of focus,
+ * and a press hears every key pushed.
+ */
+// The hub: #318. No yield: ADR-0032. Keys: #427. adoptPointer: #431. focusWithin: #460.
+export const pushable = (options?: { readonly focusWithin?: ((target: unknown) => boolean) | undefined }): Effect.Effect<{
+  readonly layer: Layer.Layer<InputSource.InputSource>
+  readonly push: (event: InputSource.PointerLikeEvent) => Effect.Effect<void>
+  readonly pushFocus: (event: InputSource.FocusLikeEvent) => Effect.Effect<void>
+  readonly pushKey: (event: InputSource.KeyboardLikeEvent) => Effect.Effect<void>
+}> =>
+  Effect.sync(() => {
+    const pointer = Feeds.hub<InputSource.PointerLikeEvent>()
+    const focus = Feeds.hub<InputSource.FocusLikeEvent>()
+    const keys = Feeds.hub<InputSource.KeyboardLikeEvent>()
+    return {
+      layer: Layer.succeed(InputSource.InputSource, {
+        pointer: () => pointer.feed,
+        keyboard: () => keys.feed,
+        focus: () => focus.feed,
+        focusWithin: UndefinedOr.map(options, (o) => o.focusWithin),
+        adoptPointer: (_target, raw) => {
+          if (isPressedPointer(raw)) {
+            const down: InputSource.PointerLikeEvent = { ...raw, type: "down", adopted: true }
+            Effect.runSync(pointer.push(down))
+            return Option.some(down)
+          }
+          return Option.none()
+        },
+      }),
+      push: pointer.push,
+      pushFocus: focus.push,
+      pushKey: keys.push,
+    }
+  })
+
+/** Whether `raw` is a pointer event with a button pressed: one the pushable InputSource adopts (#431). */
+const isPressedPointer = (raw: unknown): raw is InputSource.PointerLikeEvent =>
+  Bool.and(Predicate.hasProperty(raw, "pointerId"), Predicate.hasProperty(raw, "pressed")) && (raw as InputSource.PointerLikeEvent).pressed

package/src/layer.ts

@@ -0,0 +1,78 @@
+import * as Announcer from "@wardic/core/Announcer"
+import type * as Clock from "@wardic/core/Clock"
+import * as DefaultTransition from "@wardic/core/DefaultTransition"
+import * as DragActivity from "@wardic/core/DragActivity"
+import * as FrameLoop from "@wardic/core/FrameLoop"
+import type * as InputSource from "@wardic/core/InputSource"
+import * as InterpolatorRegistry from "@wardic/core/InterpolatorRegistry"
+import * as PressClaims from "@wardic/core/PressClaims"
+import type * as Probe from "@wardic/core/Probe"
+import * as ReducedMotion from "@wardic/core/ReducedMotion"
+import * as RefreshFrameSource from "@wardic/core/RefreshFrameSource"
+import type * as Renderer from "@wardic/core/Renderer"
+import { constUndefined, constVoid } from "effect/Function"
+import * as Layer from "effect/Layer"
+import { AtomRegistry } from "effect/reactivity"
+import * as TestClock from "./clock.ts"
+import * as TestInput from "./input.ts"
+import * as TestProbe from "./probe.ts"
+import * as TestRenderer from "./renderer.ts"
+
+/**
+ * The headless Environment's Refresh frame source: it never calls back, as its Clock never ticks
+ * on its own, so a flush gate built on it never flushes by itself. A test that fires frames
+ * provides `TestClock.pushable()`'s layer over it (ADR-0031, decision 6).
+ */
+const stillFrames: RefreshFrameSource.Shape = { requestFrame: constUndefined, cancelFrame: constVoid }
+
+/**
+ * The full headless environment: deterministic Clock (driven by `frames`), a Refresh frame
+ * source that never calls back, recording Renderer, static Probe, silent InputSource, core's real
+ * interpolator registry, a fresh AtomRegistry for reading Probe atoms
+ * (`viewport`, `prefersReducedMotion`), and a fresh Drag activity, so one test's
+ * drag never blocks another's hover or press, and core's Frame loop over that
+ * Clock. Provide this in place of `DomLive` to test animation code without a
+ * page. It draws nothing on one: an element rendered under it keeps its Starting style, so an
+ * app's components are tested with `DomLive` under the test runner's fake timers instead
+ * (https://wardic.dev/guides/testing).
+ */
+// The Drag activity: ADR-0019. The Frame loop: ADR-0027. The testing guide: #558.
+export const testLayer = (
+  frames: ReadonlyArray<number> = [],
+): Layer.Layer<
+  | Clock.Clock
+  | RefreshFrameSource.RefreshFrameSource
+  | FrameLoop.FrameLoop
+  | Renderer.Renderer
+  | Probe.Probe
+  | InputSource.InputSource
+  | InterpolatorRegistry.InterpolatorRegistry
+  | ReducedMotion.PositionalKeys
+  | DefaultTransition.DefaultTransition
+  | Announcer.Announcer
+  | AtomRegistry.AtomRegistry
+> =>
+  FrameLoop.layer.pipe(
+    Layer.provideMerge(
+      Layer.mergeAll(
+        TestClock.layer(frames),
+        RefreshFrameSource.layer(stillFrames),
+        TestRenderer.layer,
+        TestProbe.layer(),
+        TestInput.layer(),
+        InterpolatorRegistry.layer,
+        // The transforms only: the Test Environment names no box keys (ADR-0036).
+        ReducedMotion.transformsOnly,
+        // No opinion on a key's Default transition: every key on one spring (ADR-0051).
+        DefaultTransition.layerOneSpring,
+        // No assistive technology to reach headless (ADR-0037).
+        Announcer.layerSilent,
+        AtomRegistry.layer,
+        Layer.sync(DragActivity.DragActivity, DragActivity.make),
+        Layer.sync(PressClaims.PressClaims, PressClaims.make),
+      ),
+    ),
+  )
+
+/** `testLayer()` with an empty clock — for tests that drive their own frames. It never ticks on its own. */
+export const TestLive = testLayer()

package/src/probe.ts

@@ -0,0 +1,87 @@
+import * as Probe from "@wardic/core/Probe"
+import * as Arr from "effect/Array"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Stream from "effect/Stream"
+import { Atom, AtomRegistry } from "effect/reactivity"
+import * as Feeds from "./feeds.ts"
+
+const ZERO_BOUNDS: Probe.Bounds = { x: 0, y: 0, width: 0, height: 0, top: 0, right: 0, bottom: 0, left: 0 }
+const VIEWPORT = { width: 1024, height: 768 }
+/** A page that doesn't scroll: no range, and progress 1, as Motion reads a container with none. */
+const STILL_SCROLL: Probe.Scroll = { x: { current: 0, length: 0, progress: 1 }, y: { current: 0, length: 0, progress: 1 } }
+
+/** A scripted in-view boolean as the Probe reports it, with no platform record. */
+const toIntersection = (intersecting: boolean): Probe.Intersection => ({ intersecting })
+
+/** Options for the static test Probe. */
+// pageVisible: #443. scroll: #234. intersection, an Input feed: #318.
+export interface Options {
+  readonly bounds?: Probe.Bounds
+  readonly viewport?: { readonly width: number; readonly height: number }
+  readonly prefersReducedMotion?: boolean
+  /** Whether the page is shown: `true` when left out. */
+  readonly pageVisible?: boolean
+  /** Every container's scroll, as `scroll` gives it: a page that doesn't scroll when left out. */
+  readonly scroll?: Probe.Scroll
+  /**
+   * Script of intersection (in-view) booleans replayed by `observeIntersection`, an **Input feed**
+   * that ends after it. Mirrors the InputSource test harness: omitted (or empty) means it
+   * emits nothing and ends.
+   */
+  readonly intersection?: ReadonlyArray<boolean>
+}
+
+/**
+ * A static Probe: fixed bounds/viewport. `observeIntersection` replays the
+ * optional `intersection` script to each subscriber (empty by default, so it
+ * emits nothing); `observeResize` stays empty.
+ */
+export const layer = (options: Options = {}): Layer.Layer<Probe.Probe> => {
+  const { intersection = [], scroll = STILL_SCROLL } = options
+  return Layer.succeed(Probe.Probe, {
+    ...fixed(options, Atom.make(scroll)),
+    observeIntersection: () => Feeds.script(Arr.map(intersection, toIntersection)),
+  })
+}
+
+/**
+ * Both Probes' fixed part: the bounds, the viewport, the preference and the page's visibility, each defaulted, no resizes,
+ * and one scroll Atom for every container, target and offset (#234).
+ */
+const fixed = ({ bounds = ZERO_BOUNDS, viewport = VIEWPORT, prefersReducedMotion = false, pageVisible = true }: Options, scroll: Atom.Atom<Probe.Scroll>) => ({
+  measure: () => Effect.sync(() => bounds),
+  viewport: Atom.make(viewport),
+  prefersReducedMotion: Atom.make(prefersReducedMotion),
+  pageVisible: Atom.make(pageVisible),
+  scroll: () => Effect.succeed(scroll),
+  observeResize: () => Stream.empty,
+})
+
+/**
+ * A push-based Probe for tests that need to interleave intersection
+ * (in-view/out-of-view) transitions with other effects on their own schedule —
+ * mirroring {@link TestInput.pushable}. `observeIntersection(target)` subscribes
+ * to a hub, so every subscriber sees the same transitions and only
+ * events pushed *after* a subscription is live reach it. `pushIntersection`
+ * doesn't yield: a subscriber handles the transition inside the push,
+ * as `TestInput.pushable`'s do. `pushScroll` sets the scroll every container reads,
+ * through the Environment's registry, as a scroll event would.
+ * measure/viewport/prefersReducedMotion/observeResize behave as in {@link layer}.
+ */
+// The hub: #318. No yield: ADR-0032. Scroll: #234.
+export const pushable = (options: Options = {}): Effect.Effect<{
+  readonly layer: Layer.Layer<Probe.Probe>
+  readonly pushIntersection: (inView: boolean) => Effect.Effect<void>
+  readonly pushScroll: (scroll: Probe.Scroll) => Effect.Effect<void, never, AtomRegistry.AtomRegistry>
+}> =>
+  Effect.sync(() => {
+    const intersections = Feeds.hub<Probe.Intersection>()
+    const { scroll = STILL_SCROLL } = options
+    const scrollAtom = Atom.make(scroll)
+    return {
+      layer: Layer.succeed(Probe.Probe, { ...fixed(options, scrollAtom), observeIntersection: () => intersections.feed }),
+      pushIntersection: (inView: boolean) => intersections.push(toIntersection(inView)),
+      pushScroll: (next: Probe.Scroll) => AtomRegistry.AtomRegistry.use((registry) => Effect.sync(() => registry.set(scrollAtom, next))),
+    }
+  })

package/src/renderer.ts

@@ -0,0 +1,63 @@
+import * as Renderer from "@wardic/core/Renderer"
+import { constVoid } from "effect/Function"
+import * as Layer from "effect/Layer"
+
+/** A single recorded `project` call. */
+export interface ProjectCall {
+  readonly values: Record<string, unknown>
+}
+
+/** A single recorded `commit` call. */
+export interface CommitCall {
+  readonly target: unknown
+  readonly patch: Renderer.Patch
+}
+
+/**
+ * A Renderer that records every `project` and `commit` invocation into
+ * separate arrays instead of touching an environment — lets a test assert
+ * both the pure projection step and the imperative writes that would have
+ * been issued.
+ *
+ * Defaults:
+ *  - `project` is identity (`(values) => values as Patch`).
+ *  - `commit` pushes onto `commitCalls`.
+ */
+export const make = (): {
+  readonly service: {
+    readonly project: (values: Record<string, unknown>) => Renderer.Patch
+    readonly commit: (target: unknown, patch: Renderer.Patch) => void
+  }
+  readonly projectCalls: ReadonlyArray<ProjectCall>
+  readonly commitCalls: ReadonlyArray<CommitCall>
+} => {
+  const projectCalls: Array<ProjectCall> = []
+  const commitCalls: Array<CommitCall> = []
+  return {
+    service: {
+      project: (values: Record<string, unknown>): Renderer.Patch => {
+        projectCalls.push({ values })
+        return values as Renderer.Patch
+      },
+      commit: (target: unknown, patch: Renderer.Patch): void => {
+        commitCalls.push({ target, patch })
+      },
+    },
+    projectCalls,
+    commitCalls,
+  }
+}
+
+/**
+ * A Renderer that draws nothing and keeps nothing: `project` hands its values back as the patch, and
+ * `commit` drops it. A test that reads the calls makes its own with {@link make}.
+ */
+// #618 (decision 7): this was one recording renderer made at module load, whose calls every test in a
+// file added to and nothing read.
+const DISCARDING: Renderer.Renderer["Service"] = {
+  project: (values) => values as Renderer.Patch,
+  commit: constVoid,
+}
+
+/** The {@link DISCARDING} Renderer's Layer. */
+export const layer: Layer.Layer<Renderer.Renderer> = Layer.succeed(Renderer.Renderer, DISCARDING)