effect-testing

Effect Testing Skill

This skill provides comprehensive guidance for testing Effect-based applications using @effect/vitest and standard vitest.

Effect Source Reference

The Effect v4 source is available at ~/.cache/effect-v4/. Browse and read files there directly to look up APIs, types, and implementations.

Reference this for:

• Testing utilities: packages/effect/src/Testing.ts
• @effect/vitest source: packages/vitest/
• Migration guide: MIGRATION.md
• Effect source: packages/effect/src/

Framework Selection

CRITICAL: Choose the correct testing framework based on the code being tested.

Use @effect/vitest for Effect Code

Use @effect/vitest when testing:

• Functions that return Effect<A, E, R>
• Code that uses services and layers
• Time-dependent operations with TestClock
• Asynchronous operations coordinated with Effect
• STM (Software Transactional Memory) operations

import { it, expect } from '@effect/vitest';
import { Effect } from 'effect';

declare const fetchUser: (id: string) => Effect.Effect<{ id: string }, Error>;

it.effect('should fetch user', () =>
	Effect.gen(function* () {
		const user = yield* fetchUser('123');
		expect(user.id).toBe('123');
	})
);

Use Regular vitest for Pure Functions

Use standard vitest for:

• Pure functions with no Effect wrapper
• Simple data transformations
• Helper utilities
• Type constructors (brands, newtypes)

import { describe, expect, it } from 'vitest';

declare const Cents: {
	make: (value: bigint) => bigint;
	add: (a: bigint, b: bigint) => bigint;
};

describe('Cents', () => {
	it('should add cents correctly', () => {
		const result = Cents.add(Cents.make(100n), Cents.make(50n));
		expect(result).toBe(150n);
	});
});

Test Variants

it.effect - Default Test Environment

Provides TestContext including TestClock, TestRandom, etc.

import { it, expect } from '@effect/vitest';
import { Effect } from 'effect';

declare const someEffect: Effect.Effect<number>;
declare const expected: number;

it.effect('test name', () =>
	Effect.gen(function* () {
		// Test implementation with TestContext available
		const result = yield* someEffect;
		expect(result).toBe(expected);
	})
);