The best way to control Claude Code, Codex and more from any computer or phone

main
ts 453 lines 13.3 KB
Raw
1 /**
2 * Vitest integration for scoped Effect tests, shared layers, and property tests.
3 *
4 * @stability unstable
5 * @since 4.0.0
6 */
7 import type * as Arbitrary from "effect/Arbitrary"
8 import type * as Duration from "effect/Duration"
9 import type * as Effect from "effect/Effect"
10 import type * as Layer from "effect/Layer"
11 import type * as Schema from "effect/Schema"
12 import type * as Scope from "effect/Scope"
13 import type * as V from "vitest"
14 import * as internal from "./internal/internal.ts"
15
16 /**
17 * Re-exports the `vitest` API unchanged.
18 *
19 * @stability unstable
20 * @since 4.0.0
21 */
22 export * from "vitest"
23
24 /**
25 * Vitest test API without additional fixtures.
26 *
27 * @stability unstable
28 * @category models
29 * @since 4.0.0
30 */
31 export type API = V.TestAPI<{}>
32
33 /**
34 * Types for Effect-aware Vitest tests and helpers.
35 *
36 * @stability unstable
37 * @since 4.0.0
38 */
39 export declare namespace Vitest {
40 /**
41 * An Effect-returning test callback with the specified arguments.
42 *
43 * @since 4.0.0
44 */
45 export interface TestFunction<A, E, R, TestArgs extends Array<any>> {
46 (...args: TestArgs): Effect.Effect<A, E, R>
47 }
48
49 /**
50 * Registers an Effect test with a name and optional Vitest options.
51 *
52 * @since 4.0.0
53 */
54 export interface Test<R, ExtraContext = {}> {
55 <A, E>(
56 name: string,
57 self: TestFunction<A, E, R, [V.TestContext & ExtraContext]>,
58 timeout?: number | V.TestOptions
59 ): void
60 }
61
62 /**
63 * Schema or Arbitrary inputs for tuple-based or keyed property tests.
64 *
65 * @since 4.0.0
66 */
67 export type Arbitraries =
68 | Array<Schema.Schema<any> | Arbitrary.Arbitrary<any>>
69 | { [K in string]: Schema.Schema<any> | Arbitrary.Arbitrary<any> }
70
71 type ArbitraryValue<A> = A extends Schema.Schema<infer T> ? T
72 : A extends Arbitrary.Arbitrary<infer T> ? T
73 : never
74
75 /**
76 * Effect test registration API with modifiers and property testing.
77 *
78 * @since 4.0.0
79 */
80 export interface Tester<R, ExtraContext = {}> extends Vitest.Test<R, ExtraContext> {
81 skip: Vitest.Test<R, ExtraContext>
82 skipIf: (condition: unknown) => Vitest.Test<R, ExtraContext>
83 runIf: (condition: unknown) => Vitest.Test<R, ExtraContext>
84 only: Vitest.Test<R, ExtraContext>
85 each: <T>(
86 cases: ReadonlyArray<T>
87 ) => <A, E>(
88 name: string,
89 self: TestFunction<A, E, R, [T, V.TestContext & ExtraContext]>,
90 timeout?: number | V.TestOptions
91 ) => void
92 fails: Vitest.Test<R, ExtraContext>
93
94 /**
95 * Runs an Effectful property test using Schema or Arbitrary inputs.
96 *
97 * **Details**
98 *
99 * Returning `false` or completing with any non-interruption failure falsifies the property and triggers shrinking.
100 * This includes typed Effect failures, thrown exceptions, and defects such as failed assertions. Effect
101 * interruption continues to interrupt the test.
102 *
103 * The Vitest timeout interrupts the Effect fiber running generation, property evaluation, and shrinking. Effect
104 * finalizers run during that interruption.
105 *
106 * **Gotchas**
107 *
108 * A timeout cannot preempt a synchronous JavaScript callback that does not return.
109 *
110 * @since 4.0.0
111 */
112 prop: <const Arbs extends Arbitraries, A, E>(
113 name: string,
114 arbitraries: Arbs,
115 self: TestFunction<
116 A,
117 E,
118 R,
119 [
120 {
121 [K in keyof Arbs]: ArbitraryValue<Arbs[K]>
122 },
123 V.TestContext
124 ]
125 >,
126 timeout?:
127 | number
128 | V.TestOptions & {
129 arbitrary?: Arbitrary.CheckOptions
130 }
131 ) => void
132 }
133
134 /**
135 * Vitest test helpers with test services and shared layers.
136 *
137 * @since 4.0.0
138 */
139 export interface MethodsNonLive<R = never, ExtraContext = {}> extends V.TestAPI<ExtraContext> {
140 readonly effect: Vitest.Tester<R | Scope.Scope, ExtraContext>
141 readonly flakyTest: <A, E, R2>(
142 self: Effect.Effect<A, E, R2 | Scope.Scope>,
143 timeout?: Duration.Input
144 ) => Effect.Effect<A, never, R2>
145 readonly layer: <R2, E>(layer: Layer.Layer<R2, E, R>, options?: {
146 readonly concurrent?: boolean
147 readonly timeout?: Duration.Input
148 readonly buildPerTest?: boolean
149 }) => {
150 (f: (it: Vitest.MethodsNonLive<R | R2, ExtraContext>) => void): void
151 (
152 name: string,
153 f: (it: Vitest.MethodsNonLive<R | R2, ExtraContext>) => void
154 ): void
155 }
156
157 /**
158 * Runs a synchronous property test using Schema or Arbitrary inputs.
159 *
160 * **Details**
161 *
162 * Returning `false` or throwing falsifies the property and triggers shrinking. Returning `true` or `undefined`
163 * passes for that generated input. Other return values are rejected; use `it.effect.prop` for Effect callbacks.
164 *
165 * The Vitest timeout interrupts the Effect fiber running generation and shrinking.
166 *
167 * **Gotchas**
168 *
169 * A timeout cannot preempt a synchronous JavaScript callback that does not return.
170 *
171 * @since 4.0.0
172 */
173 readonly prop: <const Arbs extends Arbitraries>(
174 name: string,
175 arbitraries: Arbs,
176 self: (
177 properties: {
178 [K in keyof Arbs]: ArbitraryValue<Arbs[K]>
179 },
180 ctx: V.TestContext
181 ) => boolean | void,
182 timeout?:
183 | number
184 | V.TestOptions & {
185 arbitrary?: Arbitrary.CheckOptions
186 }
187 ) => void
188 }
189
190 /**
191 * Vitest test helpers including live-service tests and shared layers.
192 *
193 * @since 4.0.0
194 */
195 export interface Methods<R = never, ExtraContext = {}> extends MethodsNonLive<R, ExtraContext> {
196 readonly live: Vitest.Tester<Scope.Scope | R, ExtraContext>
197 readonly layer: <R2, E>(layer: Layer.Layer<R2, E, R>, options?: {
198 readonly concurrent?: boolean
199 readonly memoMap?: Layer.MemoMap
200 readonly timeout?: Duration.Input
201 readonly excludeTestServices?: boolean
202 readonly buildPerTest?: boolean
203 }) => {
204 (f: (it: Vitest.MethodsNonLive<R | R2, ExtraContext>) => void): void
205 (
206 name: string,
207 f: (it: Vitest.MethodsNonLive<R | R2, ExtraContext>) => void
208 ): void
209 }
210 }
211 }
212
213 /**
214 * Invokes the Effect Vitest equality-tester registration hook.
215 *
216 * @stability unstable
217 * @category utils
218 * @since 4.0.0
219 */
220 export const addEqualityTesters: () => void = internal.addEqualityTesters
221
222 /**
223 * Registers a callback to run once before all tests in the current suite. If
224 * the callback returns an `Effect`, it is run and awaited with a `Scope` that
225 * closes in a cleanup after the suite's `afterAll` hooks, within the hook's
226 * timeout. The `Effect` must not require any other services.
227 *
228 * **Details**
229 *
230 * If Vitest stops waiting for the setup, the setup is interrupted before the
231 * `Scope` closes. As with any `beforeAll` cleanup, Vitest reports a closing
232 * that exceeds the hook's timeout and does not wait for it.
233 *
234 * @stability unstable
235 * @category hooks
236 * @since 4.0.0
237 */
238 export const beforeAll: typeof V.beforeAll = internal.beforeAll
239
240 /**
241 * Registers a callback to run before each test in the current suite. If the
242 * callback returns an `Effect`, it is run and awaited with a `Scope` that
243 * closes when the test finishes, and interrupted if the hook times out. The
244 * `Effect` must not require any other services.
245 *
246 * @stability unstable
247 * @category hooks
248 * @since 4.0.0
249 */
250 export const beforeEach: typeof V.beforeEach = internal.beforeEach
251
252 /**
253 * Runs a scoped Effect test with test clock and console services.
254 *
255 * @stability unstable
256 * @category testing
257 * @since 4.0.0
258 */
259 export const effect: Vitest.Tester<Scope.Scope> = internal.effect
260
261 /**
262 * Runs a scoped Effect test with live services.
263 *
264 * @stability unstable
265 * @category testing
266 * @since 4.0.0
267 */
268 export const live: Vitest.Tester<Scope.Scope> = internal.live
269
270 /**
271 * Share a `Layer` between multiple tests, optionally wrapping
272 * the tests in a `describe` block if a name is provided.
273 *
274 * **Details**
275 *
276 * Named layers accept `concurrent` to override inherited suite concurrency.
277 * Anonymous layers always inherit the enclosing suite's concurrency.
278 * Use `ctx.expect` in concurrent tests for test-local snapshots and assertion counts.
279 *
280 * Pass `buildPerTest: true` to build the layer once per test instead of once
281 * per block. Each test gets new services, released when the test finishes,
282 * while services from an enclosing `layer` block stay shared. A build failure
283 * fails only that test. Blocks nested inside a per-test block are built per
284 * test as well. `timeout` has no effect on a per-test block, since the test's
285 * own timeout covers the build.
286 *
287 * **Example** (Sharing layers between tests)
288 *
289 * ```ts
290 * import { assert, layer } from "@effect/vitest"
291 * import { Effect, Layer, Context } from "effect"
292 *
293 * class Foo extends Context.Service<Foo, "foo">()("Foo") {
294 * static layer = Layer.succeed(Foo, "foo")
295 * }
296 *
297 * class Bar extends Context.Service<Bar, "bar">()("Bar") {
298 * static layer = Layer.effect(
299 * Bar,
300 * Effect.map(Foo, () => "bar" as const)
301 * )
302 * }
303 *
304 * layer(Foo.layer)("layer", (it) => {
305 * it.effect("adds context", () =>
306 * Effect.gen(function*() {
307 * const foo = yield* Foo
308 * assert.strictEqual(foo, "foo")
309 * }))
310 *
311 * it.layer(Bar.layer)("nested", (it) => {
312 * it.effect("adds context", () =>
313 * Effect.gen(function*() {
314 * const foo = yield* Foo
315 * const bar = yield* Bar
316 * assert.strictEqual(foo, "foo")
317 * assert.strictEqual(bar, "bar")
318 * }))
319 * })
320 * })
321 * ```
322 *
323 * **Example** (Building a layer for each test)
324 *
325 * ```ts
326 * import { assert, layer } from "@effect/vitest"
327 * import { Effect, Layer, Context, Ref } from "effect"
328 *
329 * class Database extends Context.Service<Database, "database">()("Database") {
330 * static layer = Layer.succeed(Database, "database")
331 * }
332 *
333 * class Cache extends Context.Service<Cache, Ref.Ref<Array<string>>>()("Cache") {
334 * static layer = Layer.effect(
335 * Cache,
336 * Effect.andThen(Database, Ref.make<Array<string>>([]))
337 * )
338 * }
339 *
340 * layer(Database.layer)("repository", (it) => {
341 * // Database is shared, Cache is built for each test
342 * it.layer(Cache.layer, { buildPerTest: true })((it) => {
343 * it.effect("writes to the cache", () =>
344 * Effect.gen(function*() {
345 * const cache = yield* Cache
346 * yield* Ref.update(cache, (keys) => [...keys, "a"])
347 * assert.deepStrictEqual(yield* Ref.get(cache), ["a"])
348 * }))
349 *
350 * it.effect("starts with an empty cache", () =>
351 * Effect.gen(function*() {
352 * const cache = yield* Cache
353 * assert.deepStrictEqual(yield* Ref.get(cache), [])
354 * }))
355 * })
356 * })
357 * ```
358 *
359 * @stability unstable
360 * @category testing
361 * @since 4.0.0
362 */
363 export const layer: <R, E>(
364 layer_: Layer.Layer<R, E>,
365 options?: {
366 readonly concurrent?: boolean
367 readonly memoMap?: Layer.MemoMap
368 readonly timeout?: Duration.Input
369 readonly excludeTestServices?: boolean
370 readonly buildPerTest?: boolean
371 }
372 ) => {
373 (f: (it: Vitest.MethodsNonLive<R>) => void): void
374 (name: string, f: (it: Vitest.MethodsNonLive<R>) => void): void
375 } = internal.layer
376
377 /**
378 * Retries a scoped Effect to tolerate intermittent test failures, dying on exhausted retries.
379 *
380 * @stability unstable
381 * @category testing
382 * @since 4.0.0
383 */
384 export const flakyTest: <A, E, R>(
385 self: Effect.Effect<A, E, R | Scope.Scope>,
386 timeout?: Duration.Input
387 ) => Effect.Effect<A, never, R> = internal.flakyTest
388
389 /**
390 * Runs a synchronous property test using schemas or arbitraries.
391 *
392 * @stability unstable
393 * @category testing
394 * @since 4.0.0
395 */
396 export const prop: Vitest.Methods["prop"] = internal.prop
397
398 /**
399 * Vitest test API extended with Effect test helpers.
400 *
401 * @stability unstable
402 * @category testing
403 * @since 4.0.0
404 */
405 export const it: Vitest.Methods = internal.it
406
407 /**
408 * Creates the Effect test helpers for a Vitest test API, such as one extended with fixtures.
409 *
410 * **Details**
411 *
412 * Tests receive the fixtures they destructure from their context. Vitest sets them up before the test and tears
413 * them down after the test's scope closes, as it does for its own tests. `it.effect.each` passes the context
414 * after the test case, and named and anonymous `it.layer` blocks keep the fixtures.
415 *
416 * **Gotchas**
417 *
418 * Vitest reads the destructured names to decide which fixtures to set up. Once any fixture is defined, a test that
419 * takes the whole context as a plain parameter, such as `(ctx) =>`, fails with a `FixtureParseError`. Property
420 * tests receive only the base test context and cannot request fixtures; auto fixtures still run.
421 *
422 * **Example** (Using a Vitest fixture in an Effect test)
423 *
424 * ```ts
425 * import { assert, makeMethods, test } from "@effect/vitest"
426 * import { Effect } from "effect"
427 *
428 * const it = makeMethods(
429 * test.extend("config", { scope: "file" }, () => ({ port: 3000 }))
430 * )
431 *
432 * it.effect("reads the config fixture", ({ config }) =>
433 * Effect.sync(() => {
434 * assert.strictEqual(config.port, 3000)
435 * }))
436 * ```
437 *
438 * @stability unstable
439 * @category constructors
440 * @since 4.0.0
441 */
442 export const makeMethods: <ExtraContext>(it: V.TestAPI<ExtraContext>) => Vitest.Methods<never, ExtraContext> =
443 internal.makeMethods
444
445 /**
446 * Creates a named Vitest suite whose callback receives Effect test helpers.
447 *
448 * @stability unstable
449 * @category testing
450 * @since 4.0.0
451 */
452 export const describeWrapped: (name: string, f: (it: Vitest.Methods) => void) => V.SuiteCollector =
453 internal.describeWrapped