The best way to control Claude Code, Codex and more from any computer or phone
| 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 |