Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Introduction
Welcome to your guide on testing Effect applications using vitest and the @effect/vitest package! @effect/vitest is designed to help simplify running Effect-based tests through vitest.
In the guide below, we will first start by setting up the required dependencies. Then, we will dive into a few examples of how to use @effect/vitest to create some Effect-based test cases.
Requirements
First, install vitest (version 1.6.0 or newer)
pnpm add -D vitest
Next, install the @effect/vitest package which facilitates running Effect-based tests through vitest.
pnpm add -D @effect/vitest
Overview
The main entry point is the following import:
import { it } from "@effect/vitest"
This import enhances the standard it function from vitest with several powerful features, including:
| Feature | Description |
|---|---|
it.effect |
Automatically injects a TestContext (e.g., TestClock) when running a test. |
it.live |
Runs the test with the live Effect environment. |
it.scoped |
Allows running an Effect program that requires a Scope. |
it.scopedLive |
Combines the features of scoped and live, using a live Effect environment that requires a Scope. |
it.flakyTest |
Facilitates the execution of tests that might occasionally fail. |
Writing Tests with it.effect
Here's how to use it.effect to write your tests:
import { it } from "@effect/vitest"
it.effect("test name", () => EffectContainingAssertions, timeout: number | TestOptions = 5_000)
When using it.effect, the TestContext is automatically injected, which allows tests to have access to services designed to facilitate testing (such as the TestClock).
Testing Successful Operations
Let's create a test for a function that divides two numbers but fails if the divisor is zero:
import { it } from "@effect/vitest"
import { Effect } from "effect"
import { expect } from "vitest"
function divide(a: number, b: number) {
if (b === 0) return Effect.fail("Cannot divide by zero")
return Effect.succeed(a / b)
}
it.effect("test success", () =>
Effect.gen(function* () {
const result = yield* divide(4, 2)
expect(result).toBe(2)
})
)
Testing Successes and Failures as Exit
To test both success and failure scenarios, convert the outcomes into an Exit object using Effect.exit:
import { it } from "@effect/vitest"
import { Effect, Exit } from "effect"
import { expect } from "vitest"
function divide(a: number, b: number) {
if (b === 0) return Effect.fail("Cannot divide by zero")
return Effect.succeed(a / b)
}
it.effect("test success as Exit", () =>
Effect.gen(function* () {
const result = yield* divide(4, 2).pipe(Effect.exit)
expect(result).toStrictEqual(Exit.succeed(2))
})
)
it.effect("test failure as Exit", () =>
Effect.gen(function* () {
const result = yield* divide(4, 0).pipe(Effect.exit)
expect(result).toStrictEqual(Exit.fail("Cannot divide by zero"))
})
)
Using the TestClock
When using it.effect, a TestContext is provided to your program which provides access to several services designed to facilitate testing. One such service is the [TestClock](https://effect.website/docs/guides/testing/testclock) which is designed to simulate the passage of time.
Note: To utilize the default, non-testing services in your tests you can use it.live.
Below, you'll find examples illustrating different ways to use time in your tests:
-
Using
it.liveto show the current time: This mode uses the real-time clock of your system, reflecting the actual current time. -
Using
it.effectwith no adjustments: By default, this test starts the clock at a time of0, effectively simulating a starting point without any elapsed time. -
Using
it.effectand adjusting time forward: Here, we advance the clock by 1000 milliseconds to test scenarios that depend on the passing of time.
import { it } from "@effect/vitest"
import { Clock, Effect, TestClock } from "effect"
const logNow = Effect.gen(function* () {
const now = yield* Clock.currentTimeMillis
console.log(now)
})
it.live("runs the test with the live Effect environment", () =>
Effect.gen(function* () {
yield* logNow // prints the actual time
})
)
it.effect("run the test with the test environment", () =>
Effect.gen(function* () {
yield* logNow // prints 0
})
)
it.effect("run the test with the test environment and the time adjusted", () =>
Effect.gen(function* () {
yield* TestClock.adjust("1000 millis")
yield* logNow // prints 1000
})
)
Skipping Tests
You can skip a test using it.effect.skip, which is useful when you want to temporarily disable a test without deleting any code.
it.effect.skip("test failure as Exit", () =>
Effect.gen(function* () {
const result = yield* divide(4, 0).pipe(Effect.exit)
expect(result).toStrictEqual(Exit.fail("Cannot divide by zero"))
})
)
Running a Single Test
To run only a specific test and ignore all others, use it.effect.only. This is helpful during development to focus on a single test case.
it.effect.only("test failure as Exit", () =>
Effect.gen(function* () {
const result = yield* divide(4, 0).pipe(Effect.exit)
expect(result).toStrictEqual(Exit.fail("Cannot divide by zero"))
})
)
Writing Tests with it.scoped
The it.scoped method allows you to run tests that involve Effect programs requiring a Scope. A Scope is essential when your Effect needs to manage resources that must be acquired before the test and released after it completes. This ensures that all resources are properly cleaned up, preventing leaks and ensuring test isolation.
Here’s a simple example to demonstrate how it.scoped can be used in your tests:
import { it } from "@effect/vitest"
import { Console, Effect } from "effect"
// Simulate acquiring and releasing a resource with console logging
const acquire = Console.log("acquire resource")
const release = Console.log("release resource")
// Define a resource that needs to be managed
const resource = Effect.acquireRelease(acquire, () => release)
// Incorrect usage: This will result in a type error because it lacks a scope
it.effect("run with scope", () =>
Effect.gen(function* () {
yield* resource
})
)
// Correct usage: Using 'it.scoped' to properly manage the scope
it.scoped("run with scope", () =>
Effect.gen(function* () {
yield* resource
})
)
Writing Tests with it.flakyTest
it.flakyTest is a function from the @effect/vitest package designed to handle tests that might not succeed on the first try. These tests are often called "flaky" tests because their outcome can vary (e.g., due to timing issues, external dependencies, or randomness). it.flakyTest allows these tests to be retried until they succeed or until a specified timeout period expires.
Here's how you can use it.flakyTest in your test suite:
First, let’s set up a basic test scenario that could potentially fail randomly:
import { it } from "@effect/vitest"
import { Effect, Random } from "effect"
// Define a flaky test effect
const flaky = Effect.gen(function* () {
const random = yield* Random.nextBoolean
if (random) {
return yield* Effect.fail("Failed due to randomness")
}
})
// Standard test, which may fail intermittently
it.effect("possibly failing test", () => flaky)
To address the flakiness, we apply it.flakyTest which will retry the test until it succeeds or the specified timeout is reached:
// Retrying the flaky test with a timeout
it.effect("retrying until success or timeout", () =>
it.flakyTest(flaky, "5 seconds")
)