mirror of
https://github.com/Effect-TS/effect.git
synced 2026-11-16 11:10:48 +08:00
16 KiB
16 KiB
Testing Patterns - Effect Library
🎯 OVERVIEW
Comprehensive testing strategies for the Effect library using @effect/vitest, with emphasis on proper Effect patterns, TestClock usage, and type-safe testing approaches.
🚨 CRITICAL TESTING REQUIREMENTS
Testing Framework Selection
✅ Use @effect/vitest for Effect-based modules
import { assert, describe, it } from "@effect/vitest"
import { Effect } from "effect"
// MANDATORY: Use it.effect for Effect-based tests
it.effect("should work with Effects", () =>
Effect.gen(function*() {
const result = yield* someEffect
assert.strictEqual(result, expectedValue)
}))
✅ Use regular vitest for pure TypeScript functions
import { describe, expect, it } from "vitest"
// For pure functions that don't return Effects
it("should work with pure functions", () => {
const result = pureFunction(input)
expect(result).toBe(expectedValue)
})
❌ FORBIDDEN PATTERNS
Never use Effect.runSync in tests
// ❌ WRONG - Don't use Effect.runSync with regular it
import { describe, expect, it } from "vitest"
it("wrong pattern", () => {
const result = Effect.runSync(Effect.gen(function*() {
return yield* someEffect
}))
expect(result).toBe(value) // Wrong assertion method
})
// ✅ CORRECT - Use it.effect instead
import { assert, describe, it } from "@effect/vitest"
it.effect("correct pattern", () =>
Effect.gen(function*() {
const result = yield* someEffect
assert.strictEqual(result, value) // Correct assertion method
}))
Never use expect with it.effect
// ❌ WRONG - Don't mix expect with it.effect
it.effect("wrong assertions", () =>
Effect.gen(function*() {
const result = yield* someEffect
expect(result).toBe(value) // Wrong - should use assert
}))
// ✅ CORRECT - Use assert methods
it.effect("correct assertions", () =>
Effect.gen(function*() {
const result = yield* someEffect
assert.strictEqual(result, value)
}))
🕐 TIME-DEPENDENT TESTING WITH TESTCLOCK
⚠️ CRITICAL: Always use TestClock for time-dependent operations
Any code that involves timing must use TestClock to avoid flaky tests:
import { assert, describe, it } from "@effect/vitest"
import { Effect, TestClock } from "effect"
describe("time-dependent operations", () => {
it.effect("should handle delays with TestClock", () =>
Effect.gen(function*() {
// Start operation that takes 5 seconds
const fiber = yield* Effect.fork(
Effect.gen(function*() {
yield* Effect.sleep("5 seconds")
return "completed"
})
)
// Use TestClock.adjust with string duration (preferred pattern)
yield* TestClock.adjust("5 seconds")
const result = yield* Effect.join(fiber)
assert.strictEqual(result, "completed")
}))
it.effect("should test timeout behavior", () =>
Effect.gen(function*() {
const timeoutEffect = Effect.timeout(
Effect.sleep("10 seconds"),
"5 seconds"
)
const fiber = yield* Effect.fork(timeoutEffect)
// Advance time to trigger timeout
yield* TestClock.adjust("5 seconds")
const result = yield* Effect.exit(Effect.join(fiber))
assert.isTrue(result._tag === "Failure")
}))
it.effect("should set absolute time with setTime", () =>
Effect.gen(function*() {
// Set clock to specific timestamp
yield* TestClock.setTime(1000)
const fiber = yield* Effect.fork(
Effect.gen(function*() {
yield* Effect.sleep("2 seconds")
return yield* Effect.clockWith((clock) => clock.currentTimeMillis)
})
)
yield* TestClock.adjust("2 seconds")
const result = yield* Effect.join(fiber)
assert.strictEqual(result, 3000) // 1000 + 2000ms
}))
})
Operations requiring TestClock:
Effect.sleep()andEffect.delay()Effect.timeout()andEffect.race()with timeouts- Scheduled operations and retry logic
- Queue operations with time-based completion
- Any concurrent operations dependent on timing
🧪 COMPREHENSIVE TESTING PATTERNS
Basic Effect Testing Pattern
import { assert, describe, it } from "@effect/vitest"
import { Effect } from "effect"
import * as MyModule from "../src/MyModule.js"
describe("MyModule", () => {
describe("constructors", () => {
it.effect("create should initialize with default values", () =>
Effect.gen(function*() {
const instance = yield* MyModule.create()
assert.isTrue(MyModule.isInstance(instance))
assert.strictEqual(MyModule.getValue(instance), 0)
}))
it.effect("create should accept custom configuration", () =>
Effect.gen(function*() {
const config = { initialValue: 42 }
const instance = yield* MyModule.create(config)
assert.strictEqual(MyModule.getValue(instance), 42)
}))
})
describe("combinators", () => {
it.effect("map should transform values", () =>
Effect.gen(function*() {
const instance = yield* MyModule.create({ initialValue: 10 })
const transformed = yield* MyModule.map(instance, (x) => x * 2)
assert.strictEqual(MyModule.getValue(transformed), 20)
}))
})
})
Error Handling Testing Pattern
import { assert, describe, it } from "@effect/vitest"
import { Effect, Exit } from "effect"
import * as MyModule from "../src/MyModule.js"
describe("error handling", () => {
it.effect("should fail with validation error for negative values", () =>
Effect.gen(function*() {
const result = yield* Effect.exit(
MyModule.create({ initialValue: -1 })
)
if (result._tag === "Failure") {
assert.isTrue(MyModule.isValidationError(result.cause))
} else {
assert.fail("Expected operation to fail")
}
}))
it.effect("should handle network errors gracefully", () =>
Effect.gen(function*() {
const mockNetworkFailure = Effect.fail(
new MyModule.NetworkError({
message: "Connection timeout"
})
)
const result = yield* Effect.exit(
MyModule.fetchWithRetry("https://api.example.com")
.pipe(Effect.provide(Layer.succeed(NetworkService, {
fetch: () => mockNetworkFailure
})))
)
assert.isTrue(Exit.isFailure(result))
}))
})
Resource Management Testing Pattern
import { assert, describe, it } from "@effect/vitest"
import { Effect, Ref } from "effect"
import * as ResourceModule from "../src/ResourceModule.js"
describe("resource management", () => {
it.effect("should properly acquire and release resources", () =>
Effect.gen(function*() {
const acquired = yield* Ref.make(false)
const released = yield* Ref.make(false)
const mockResource = {
acquire: Effect.sync(() => Ref.set(acquired, true)),
use: (resource: unknown) => Effect.succeed("used"),
release: Effect.sync(() => Ref.set(released, true))
}
const result = yield* ResourceModule.withResource(
mockResource.acquire,
mockResource.use,
mockResource.release
)
assert.strictEqual(result, "used")
assert.isTrue(yield* Ref.get(acquired))
assert.isTrue(yield* Ref.get(released))
}))
it.effect("should release resources even on failure", () =>
Effect.gen(function*() {
const released = yield* Ref.make(false)
const result = yield* Effect.exit(
ResourceModule.withResource(
Effect.succeed("resource"),
() => Effect.fail("operation failed"),
() => Ref.set(released, true)
)
)
assert.isTrue(Exit.isFailure(result))
assert.isTrue(yield* Ref.get(released))
}))
})
Concurrent Operations Testing Pattern
import { assert, describe, it } from "@effect/vitest"
import { Duration, Effect, Fiber, TestClock } from "effect"
import * as ConcurrentModule from "../src/ConcurrentModule.js"
describe("concurrent operations", () => {
it.effect("should handle multiple concurrent operations", () =>
Effect.gen(function*() {
const operations = [
ConcurrentModule.operation("A"),
ConcurrentModule.operation("B"),
ConcurrentModule.operation("C")
]
const results = yield* Effect.all(operations, { concurrency: "unbounded" })
assert.strictEqual(results.length, 3)
assert.includeMembers(results, ["A", "B", "C"])
}))
it.effect("should respect concurrency limits", () =>
Effect.gen(function*() {
const startTimes = yield* Ref.make<string[]>([])
const timedOperation = (id: string) =>
Effect.gen(function*() {
yield* Ref.update(startTimes, (arr) => [...arr, id])
yield* Effect.sleep(Duration.seconds(1))
return id
})
const operations = ["A", "B", "C", "D"].map(timedOperation)
const fiber = yield* Effect.fork(
Effect.all(operations, { concurrency: 2 })
)
// Advance time and check concurrent execution
yield* TestClock.advance(Duration.millis(500))
const midResults = yield* Ref.get(startTimes)
assert.strictEqual(midResults.length, 2) // Only 2 should start
yield* TestClock.advance(Duration.seconds(1))
const finalResults = yield* Effect.join(fiber)
assert.strictEqual(finalResults.length, 4)
}))
})
Layer and Service Testing Pattern
Use Context.Service for defining services in the Effect codebase:
import { assert, describe, it } from "@effect/vitest"
import { Context, Effect, Layer } from "effect"
import * as ServiceModule from "../src/ServiceModule.js"
// Define services using Context.Service pattern
class DatabaseService extends Context.Service<DatabaseService, {
readonly query: (sql: string) => Effect.Effect<unknown[]>
}>()("DatabaseService") {
// Live implementation for production
static Live = Layer.succeed(DatabaseService)({
query: (sql) => Effect.succeed([])
})
}
// Test service with mock implementation
class TestDatabaseService extends Context.Service<TestDatabaseService, {
readonly query: (sql: string) => Effect.Effect<unknown[]>
}>()("TestDatabaseService") {
static Mock = (mockData: unknown[]) =>
Layer.succeed(TestDatabaseService)({
query: (_sql) => Effect.succeed(mockData)
})
static Failing = (error: string) =>
Layer.succeed(TestDatabaseService)({
query: () => Effect.fail(error)
})
}
describe("service integration", () => {
it.effect("should work with mock services", () =>
Effect.gen(function*() {
const mockData = [{ id: 1, name: "test" }]
const result = yield* ServiceModule.findUser("1")
.pipe(Effect.provide(TestDatabaseService.Mock(mockData)))
assert.deepStrictEqual(result, mockData[0])
}))
it.effect("should handle service failures", () =>
Effect.gen(function*() {
const result = yield* Effect.exit(
ServiceModule.findUser("1")
.pipe(Effect.provide(TestDatabaseService.Failing("Database connection failed")))
)
assert.isTrue(Exit.isFailure(result))
}))
it.effect("should use direct Layer.succeed for simple mocks", () =>
Effect.gen(function*() {
// For simple one-off mocks, use Layer.succeed directly
const result = yield* ServiceModule.getValue()
.pipe(
Effect.provide(
Layer.succeed(DatabaseService)({
query: () => Effect.succeed([{ value: 42 }])
})
)
)
assert.strictEqual(result, 42)
}))
})
🎯 ASSERTION PATTERNS
Effect-specific Assertions
// Equality assertions
assert.strictEqual(actual, expected) // Reference/primitive equality
assert.notStrictEqual(actual, expected) // Reference/primitive inequality
assert.deepStrictEqual(actualObject, expectedObject) // Deep structural equality
assert.deepEqual(actual, expected) // Uses Equal.equals trait for Effect types
// Boolean assertions
assert.isTrue(condition)
assert.isFalse(condition)
assert.ok(condition, "optional message") // Boolean with custom message
// Null/undefined assertions
assert.isNull(value)
assert.isNotNull(value)
assert.isUndefined(value)
assert.isDefined(value)
// Numeric comparisons
assert.isAtLeast(actual, expected) // actual >= expected
assert.isAtMost(actual, expected) // actual <= expected
// String/regex assertions
assert.match(string, regex) // String matches regex pattern
// Array assertions
assert.includeMembers(actualArray, expectedItems)
// For custom error types
assert.isTrue(MyModule.isCustomError(error))
// For Exit results
assert.isTrue(Exit.isSuccess(result))
assert.isTrue(Exit.isFailure(result))
Specialized Exit and Result Assertions
Import from @effect/vitest/utils for type-safe Exit and Result assertions:
import { assert, describe, it } from "@effect/vitest"
import { assertExitFailure, assertExitSuccess, assertFailure, assertSuccess } from "@effect/vitest/utils"
import { Effect, Exit } from "effect"
describe("specialized assertions", () => {
it.effect("should assert Exit success", () =>
Effect.gen(function*() {
const result = yield* Effect.exit(Effect.succeed(42))
// Type-safe assertion that narrows Exit type
assertExitSuccess(result, 42)
}))
it.effect("should assert Exit failure", () =>
Effect.gen(function*() {
const result = yield* Effect.exit(Effect.fail("error"))
// Asserts failure and validates cause
assertExitFailure(result, "error")
}))
it.effect("should assert Result success", () =>
Effect.gen(function*() {
const result = yield* Effect.result(Effect.succeed("value"))
// For Result types (success channel)
assertSuccess(result, "value")
}))
it.effect("should assert Result failure", () =>
Effect.gen(function*() {
const result = yield* Effect.result(Effect.fail("error"))
// For Result types (failure channel)
assertFailure(result, "error")
}))
})
Testing Complex Data Structures
it.effect("should handle complex data transformations", () =>
Effect.gen(function*() {
const input = {
users: [
{ id: "1", name: "Alice", age: 30 },
{ id: "2", name: "Bob", age: 25 }
]
}
const result = yield* MyModule.processUsers(input)
// Test structure
assert.isTrue(Array.isArray(result.processedUsers))
assert.strictEqual(result.processedUsers.length, 2)
// Test individual items
const alice = result.processedUsers.find((u) => u.id === "1")
assert.isDefined(alice)
assert.strictEqual(alice?.name, "Alice")
assert.strictEqual(alice?.processed, true)
}))
🔧 TEST ORGANIZATION PATTERNS
Group Related Tests
describe("ModuleName", () => {
describe("constructors", () => {
// Tests for creation functions
})
describe("combinators", () => {
// Tests for transformation functions
})
describe("predicates", () => {
// Tests for boolean-returning functions
})
describe("error handling", () => {
// Tests for error conditions
})
describe("integration", () => {
// Tests for service integration
})
})
Progressive Test Complexity
describe("feature progression", () => {
it.effect("basic functionality", () => /* simple test */)
it.effect("with configuration", () => /* configuration test */)
it.effect("with error handling", () => /* error test */)
it.effect("with concurrency", () => /* concurrent test */)
it.effect("full integration", () => /* comprehensive test */)
})
This comprehensive testing approach ensures reliable, maintainable test suites that properly validate Effect-based code while avoiding common pitfalls and anti-patterns.