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

main
md 393 lines 18 KB
Rendered Raw
1 # @effect/vitest
2
3 Helpers for testing Effect-based code with [Vitest](https://vitest.dev). Provides an enhanced `it` function with support for scoped tests, test services such as `TestClock`, shared layers, and property testing.
4
5 ## Installation
6
7 Install Vitest 5 (`>=5.0.0 <6.0.0`) with the package as a dev dependency:
8
9 ```sh
10 npm install -D vitest@^5 @effect/vitest
11 ```
12
13 Vitest 5 supports Node.js `^22.12.0 || ^24.0.0 || >=26.0.0` and Vite 6.4 or later within majors 6, 7, and 8.
14
15 ## Links
16
17 - [Website](https://effect.website): documentation, guides, and news.
18 - [Reference](https://effect.website/docs/v4/api/vitest): API documentation for this package.
19 - [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.
20 - [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.
21 - [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.
22
23 ## Let's talk
24
25 Whether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.
26
27 - **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.
28 - **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.
29 - **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.
30
31 ## Migrating to Vitest 5
32
33 The package re-exports Vitest's public API. Upgrading removes the same exports and helpers that Vitest 5 removes; it does not provide compatibility shims.
34
35 - Replace `test.sequential`, `it.sequential`, `describe.sequential`, and `{ sequential: true }` with `{ concurrent: false }`. Set this explicitly for suites that share mutable state or depend on test order when concurrency is enabled.
36 - Replace the top-level `bench` import with the test-context fixture:
37
38 ```ts
39 import { test } from "@effect/vitest"
40
41 test("sort", async ({ bench }) => {
42 await bench("sort", () => [3, 1, 2].sort()).run()
43 })
44 ```
45
46 Use `test.skip`, `test.only`, or `test.todo` on the enclosing test. The old `BenchFactory`, `BenchFunction`, `BenchTask`, `BenchTaskResult`, `Benchmark`, `BenchmarkAPI`, `BenchmarkResult`, and `BenchmarkRunner` exports are removed. Use the fixture's `Bench`, `BenchFn`, `BenchRegistration`, and `BenchResult` types as appropriate; custom benchmark engines use `BenchmarkProvider`.
47 - Change `Assertion<T>` to `Assertion<void, T>` for synchronous assertions or `Assertion<Promise<void>, T>` for asynchronous assertions. Augment `Matchers<R, T>` in `vitest` for custom matchers. Vitest's assertion state is no longer shared with `@vitest/expect`.
48 - The `ExpectPollOptions` export is removed. Derive the options type with `NonNullable<Parameters<typeof expect.poll>[1]>` when needed.
49 - Import reporter types from `vitest/node` and environment or snapshot APIs from `vitest/runtime`.
50
51 Vitest 5 clears mock call history before each test by default and requires asynchronous assertions to be awaited. JSON reporters write to a file by default; use an explicit `outputFile` when consuming their results. See the [Vitest migration guide](https://vitest.dev/guide/migration/) for the remaining upstream changes.
52
53 The Effect helpers retain their existing calling convention: `it.effect(name, effect, options)`, `it.live(name, effect, options)`, shared layers, and property tests.
54
55 Both `layer` and `it.layer` accept `{ concurrent: false }` to serialize a named shared-layer suite, or `{ concurrent: true }` to run its tests concurrently. Omitting the option inherits suite concurrency; nested named layers can override it. Anonymous layers always inherit the enclosing suite's concurrency, regardless of the option.
56
57 In concurrent tests, use the callback's `ctx.expect` so snapshots and assertion counts belong to the right test.
58
59 ## Overview
60
61 The main entry point is the following import:
62
63 ```ts
64 import { it } from "@effect/vitest"
65 ```
66
67 This import enhances the standard `it` function from `vitest` with several powerful features, including:
68
69 | Feature | Description |
70 | -------------- | --------------------------------------------------------------------------------------------------- |
71 | `it.effect` | Runs a scoped test with test services such as `TestClock` and `TestConsole`. |
72 | `it.live` | Runs a scoped test with the live Effect environment. |
73 | `it.layer` | Shares a `Layer` between multiple tests, or builds it for each test with `buildPerTest: true`. |
74 | `it.prop` | Runs property tests using Effect `Schema` and `Arbitrary` values. |
75 | `it.flakyTest` | Retries an Effect that might occasionally fail until it succeeds or reaches the configured timeout. |
76
77 Pass `{ buildPerTest: true }` to `it.layer` to build its layer once per test instead of once per block. Each test gets new services, released when it finishes, while services from an enclosing `layer` block stay shared. Blocks nested inside a per-test block are built per test as well.
78
79 Property tests shrink callbacks that return `false`, throw, or complete with a non-interruption Effect failure. This
80 includes failed assertions, typed failures, and defects. Effect interruption still interrupts the test.
81 Synchronous `it.prop` callbacks must return a boolean or `void`: `true` and `undefined` pass, while `false`
82 falsifies the property. Other return values, including Effects and Promises, are rejected. Use `it.effect.prop`
83 for Effect callbacks; their successful results pass unless the value is `false`.
84
85 The Vitest `timeout` interrupts the Effect fiber running property generation, evaluation, and shrinking. Effect
86 finalizers run during the interruption, which is reported as a test timeout rather than a property falsification. As
87 with other Effect programs, a timeout cannot preempt a synchronous JavaScript callback that does not return.
88
89 ## Writing Tests with `it.effect`
90
91 Here's how to use `it.effect` to write your tests:
92
93 **Syntax**
94
95 ```ts
96 import { it } from "@effect/vitest"
97
98 it.effect("test name", () => EffectContainingAssertions, timeout: number | TestOptions = 5_000)
99 ```
100
101 `it.effect` automatically provides the Effect test services, including [`TestClock`](#using-the-testclock) and `TestConsole`, and a fresh `Scope` for each test. The scope is closed when the test finishes. Logs are captured by `TestConsole`; use `it.live` for live console output, or see [Logging](#logging) to override the console explicitly.
102
103 ### Testing Successful Operations
104
105 To write a test, place your assertions directly within the main effect. This ensures that your assertions are evaluated as part of the test's execution.
106
107 **Example** (Testing a Successful Operation)
108
109 In the following example, we test a function that divides two numbers, but fails if the divisor is zero. The goal is to check that the function returns the correct result when given valid input.
110
111 ```ts
112 import { expect, it } from "@effect/vitest"
113 import { Effect } from "effect"
114
115 // A simple divide function that returns an Effect, failing when dividing by zero
116 function divide(a: number, b: number) {
117 if (b === 0) return Effect.fail("Cannot divide by zero")
118 return Effect.succeed(a / b)
119 }
120
121 // Testing a successful division
122 it.effect("test success", () =>
123 Effect.gen(function*() {
124 const result = yield* divide(4, 2) // Expect 4 divided by 2 to succeed
125 expect(result).toBe(2) // Assert that the result is 2
126 }))
127 ```
128
129 ### Testing Successes and Failures as `Exit`
130
131 When you need to handle both success and failure cases in a test, you can use `Effect.exit` to capture the outcome as an `Exit` object. This allows you to verify both successful and failed results within the same test structure.
132
133 **Example** (Testing Success and Failure with `Exit`)
134
135 ```ts
136 import { expect, it } from "@effect/vitest"
137 import { Effect, Exit } from "effect"
138
139 // A function that divides two numbers and returns an Effect.
140 // It fails if the divisor is zero.
141 function divide(a: number, b: number) {
142 if (b === 0) return Effect.fail("Cannot divide by zero")
143 return Effect.succeed(a / b)
144 }
145
146 // Test case for a successful division, using `Effect.exit` to capture the result
147 it.effect("test success as Exit", () =>
148 Effect.gen(function*() {
149 const result = yield* Effect.exit(divide(4, 2)) // Capture the result as an Exit
150 expect(result).toStrictEqual(Exit.succeed(2)) // Expect success with the value 2
151 }))
152
153 // Test case for a failure (division by zero), using `Effect.exit`
154 it.effect("test failure as Exit", () =>
155 Effect.gen(function*() {
156 const result = yield* Effect.exit(divide(4, 0)) // Capture the result as an Exit
157 expect(result).toStrictEqual(Exit.fail("Cannot divide by zero")) // Expect failure with the correct message
158 }))
159 ```
160
161 ### Using the TestClock
162
163 When writing tests with `it.effect`, Effect test services are automatically provided. These include the [`TestClock`](https://effect.website/docs/testing/testclock/), which allows you to simulate the passage of time in your tests.
164
165 **Note**: If you want to use the real-time clock (instead of the simulated one), you can switch to `it.live`.
166
167 **Example** (Using `TestClock` and `it.live`)
168
169 Here are examples that demonstrate how you can work with time in your tests using `it.effect` and `TestClock`:
170
171 1. **Using `it.live` to show the current time**: This will display the actual system time, since it runs in the live environment.
172
173 2. **Using `it.effect` without adjustments**: By default, the `TestClock` starts at `0`, simulating the beginning of time for your test without any time passing.
174
175 3. **Using `it.effect` and adjusting time**: In this test, we simulate the passage of time by advancing the clock by 1000 milliseconds (1 second).
176
177 ```ts
178 import { it } from "@effect/vitest"
179 import { Clock, Effect } from "effect"
180 import { TestClock } from "effect/testing"
181
182 // Effect to log the current time
183 const logNow = Effect.gen(function*() {
184 const now = yield* Clock.currentTimeMillis // Fetch the current time from the clock
185 console.log(now) // Log the current time
186 })
187
188 // Example of using the real system clock with `it.live`
189 it.live("runs the test with the live Effect environment", () =>
190 Effect.gen(function*() {
191 yield* logNow // Prints the actual current time
192 }))
193
194 // Example of using `it.effect` with the default test environment
195 it.effect("run the test with the test environment", () =>
196 Effect.gen(function*() {
197 yield* logNow // Prints 0, as the test clock starts at 0
198 }))
199
200 // Example of advancing the test clock by 1000 milliseconds
201 it.effect("run the test with the test environment and the time adjusted", () =>
202 Effect.gen(function*() {
203 yield* TestClock.adjust("1000 millis") // Move the clock forward by 1000 milliseconds
204 yield* logNow // Prints 1000, reflecting the adjusted time
205 }))
206 ```
207
208 ### Skipping Tests
209
210 If you need to temporarily disable a test but don't want to delete or comment out the code, you can use `it.effect.skip`. This is helpful when you're working on other parts of your test suite but want to keep the test for future execution.
211
212 **Example** (Skipping a Test)
213
214 ```ts
215 import { it } from "@effect/vitest"
216 import { expect } from "@effect/vitest"
217 import { Effect, Exit } from "effect"
218
219 function divide(a: number, b: number) {
220 if (b === 0) return Effect.fail("Cannot divide by zero")
221 return Effect.succeed(a / b)
222 }
223
224 // Temporarily skip the test for dividing numbers
225 it.effect.skip("test failure as Exit", () =>
226 Effect.gen(function*() {
227 const result = yield* Effect.exit(divide(4, 0))
228 expect(result).toStrictEqual(Exit.fail("Cannot divide by zero"))
229 }))
230 ```
231
232 ### Running a Single Test
233
234 When you're developing or debugging, it's often useful to run a specific test without executing the entire test suite. You can achieve this by using `it.effect.only`, which will run just the selected test and ignore the others.
235
236 **Example** (Running a Single Test)
237
238 ```ts
239 import { it } from "@effect/vitest"
240 import { expect } from "@effect/vitest"
241 import { Effect, Exit } from "effect"
242
243 function divide(a: number, b: number) {
244 if (b === 0) return Effect.fail("Cannot divide by zero")
245 return Effect.succeed(a / b)
246 }
247
248 // Run only this test, skipping all others
249 it.effect.only("test failure as Exit", () =>
250 Effect.gen(function*() {
251 const result = yield* Effect.exit(divide(4, 0))
252 expect(result).toStrictEqual(Exit.fail("Cannot divide by zero"))
253 }))
254 ```
255
256 ### Expecting Tests to Fail
257
258 When adding new failing tests, you might not be able to fix them right away. Instead of skipping them, you may want to assert it fails, so that when you fix them, you'll know and can re-enable them before it regresses.
259
260 **Example** (Asserting one test fails)
261
262 ```ts
263 import { it } from "@effect/vitest"
264 import { Effect, Exit } from "effect"
265
266 function divide(a: number, b: number) {
267 if (b === 0) return Effect.fail("Cannot divide by zero")
268 return Effect.succeed(a / b)
269 }
270
271 // Temporarily assert that the test for dividing by zero fails.
272 it.effect.fails("dividing by zero special cases", ({ expect }) =>
273 Effect.gen(function*() {
274 const result = yield* Effect.exit(divide(4, 0))
275 expect(result).toStrictEqual(0)
276 }))
277 ```
278
279 ### Logging
280
281 By default, `it.effect` captures log output in `TestConsole`; inspect it with `TestConsole.logLines`. A custom logger, including `Logger.consolePretty()`, still writes to that test console. To print to the live console, use `it.live` or explicitly provide `Console.Console` with `globalThis.console`.
282
283 **Example** (Controlling Logging in Tests)
284
285 ```ts
286 import { it } from "@effect/vitest"
287 import { Console, Effect, Logger } from "effect"
288
289 // This test captures the log in TestConsole rather than displaying it
290 it.effect("does not display a log", () =>
291 Effect.gen(function*() {
292 yield* Effect.log("it.effect") // Read it back with TestConsole.logLines
293 }))
294
295 // A pretty logger displays output when paired with the live console
296 it.effect("providing the live console displays a log", () =>
297 Effect.gen(function*() {
298 yield* Effect.log("it.effect with custom logger") // Log will be displayed
299 }).pipe(
300 Effect.provide(Logger.layer([Logger.consolePretty()])),
301 Effect.provideService(Console.Console, globalThis.console)
302 ))
303
304 // This test runs using `it.live`, which enables logging by default
305 it.live("it.live displays a log", () =>
306 Effect.gen(function*() {
307 yield* Effect.log("it.live") // Log will be displayed
308 }))
309 ```
310
311 ## Resource Safety and Scope
312
313 Both `it.effect` and `it.live` provide a fresh `Scope` and close it after each test. Test bodies can therefore use scoped resources directly. Do not wrap the test body in `Effect.scoped`, because the test runner already manages its scope.
314
315 **Example** (Managing a Resource Lifecycle)
316
317 ```ts
318 import { it } from "@effect/vitest"
319 import { Console, Effect } from "effect"
320
321 // Simulating the acquisition and release of a resource with console logging
322 const acquire = Console.log("acquire resource")
323 const release = Console.log("release resource")
324
325 // Defining a resource that requires proper management
326 const resource = Effect.acquireRelease(acquire, () => release)
327
328 it.effect("run with scope", () =>
329 Effect.gen(function*() {
330 yield* resource
331 }))
332 ```
333
334 ## Using Vitest Fixtures
335
336 To use [Vitest fixtures](https://vitest.dev/guide/test-context#extend-test-context) in Effect tests, pass a test extended with `test.extend` to `makeMethods`. It returns the same helpers as `it`, and each test receives the fixtures it destructures from its context.
337
338 **Example** (Sharing a Database Across a Test File)
339
340 ```ts
341 import { assert, makeMethods, test } from "@effect/vitest"
342 import { PGlite } from "@electric-sql/pglite"
343 import { Effect } from "effect"
344
345 const it = makeMethods(
346 test.extend("db", { scope: "file" }, async ({}, { onCleanup }) => {
347 const db = await PGlite.create()
348 onCleanup(() => db.close())
349 return db
350 })
351 )
352
353 it.effect("runs a query", ({ db }) =>
354 Effect.gen(function*() {
355 const result = yield* Effect.promise(() => db.query("select 1 as one"))
356 assert.deepStrictEqual(result.rows, [{ one: 1 }])
357 }))
358 ```
359
360 Destructure the fixtures a test uses: Vitest reads those names to decide what to set up, and rejects `(ctx) =>` once any fixture is defined. `it.effect.each` passes the context after the test case. Property tests cannot request fixtures, but auto fixtures still run. Build `makeMethods` from `test` or `test.extend(...)`, not from the test a `describe` callback receives: that API is bound to the outer suite, so tests in a named `it.layer` can end up outside their named suite and miss its hooks and concurrency setting.
361
362 ## Writing Tests with `it.flakyTest`
363
364 `it.flakyTest` is a utility designed to manage tests that may not succeed consistently on the first attempt. These tests, often referred to as "flaky," can fail due to factors like timing issues, external dependencies, or randomness. `it.flakyTest` allows for retrying these tests until they pass or a specified timeout is reached.
365
366 **Example** (Handling Flaky Tests with Retries)
367
368 Let's start by setting up a basic test scenario that has the potential to fail randomly:
369
370 ```ts
371 import { it } from "@effect/vitest"
372 import { Effect, Random } from "effect"
373
374 // Simulating a flaky effect
375 const flaky = Effect.gen(function*() {
376 const random = yield* Random.nextBoolean
377 if (random) {
378 return yield* Effect.fail("Failed due to randomness")
379 }
380 })
381
382 // Standard test that may fail intermittently
383 it.effect("possibly failing test", () => flaky)
384 ```
385
386 In this test, the outcome is random, so the test might fail depending on the result of `Random.nextBoolean`.
387
388 To handle this flakiness, we use `it.flakyTest` to retry the test until it passes, or until a defined timeout expires:
389
390 ```ts
391 // Retrying the flaky test with a 5-second timeout
392 it.effect("retrying until success or timeout", () => it.flakyTest(flaky, "5 seconds"))
393 ```