TestConsole

Provides a test implementation of the Effect Console service.

When the test layer is provided, calls made through the Effect console APIs are captured in memory instead of being written to the host console. Tests can then assert on logged values deterministically. This module includes the console layer, helpers for reading captured Console.log and Console.error arguments, and access to the provided test console service.

7 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

Creates a new TestConsole instance that captures all console output. The returned TestConsole implements the Console interface and provides additional methods to retrieve logged messages.

When to use

Use to construct a test console service value directly.

See

layer for providing a TestConsole as a Layer

Signature

declare const make: Effect<TestConsole, never, never>

Example

(Creating a test console)

import { Console, Effect } from "effect"
import { TestConsole } from "effect/testing"

const program = Effect.gen(function*() {
  yield* Console.log("Debug message")
  yield* Console.error("Error occurred")

  const logs = yield* TestConsole.logLines
  const errors = yield* TestConsole.errorLines

  logs // => ["Debug message"]
  errors // => ["Error occurred"]
}).pipe(Effect.provide(TestConsole.layer))

await Effect.runPromise(program)

Layers

layer

Added in v4.0.0 Source

Creates a Layer which constructs a TestConsole. This layer can be used to provide a TestConsole implementation for testing purposes.

When to use

Use to run an effect with console calls captured by TestConsole.

See

make for constructing the service value directly
testConsoleWith for accessing the provided test console service

Signature

declare const layer: Layer.Layer<TestConsole>

Example

(Providing a test console layer)

import { Console, Effect } from "effect"
import { TestConsole } from "effect/testing"

const program = Effect.gen(function*() {
  yield* Console.log("This will be captured")
  yield* Console.error("This error will be captured")

  const logs = yield* TestConsole.logLines
  const errors = yield* TestConsole.errorLines

  logs // => ["This will be captured"]
  errors // => ["This error will be captured"]
}).pipe(Effect.provide(TestConsole.layer))

await Effect.runPromise(program)

Models

TestConsole interface

Added in v4.0.0 Source

A TestConsole provides a testable implementation of the Console interface. It captures all console output for testing purposes while maintaining full compatibility with the standard Console API.

When to use

Use to provide a console implementation that records calls for assertions in tests.

Details

This interface extends the standard Console interface and adds methods to retrieve logged messages for verification in tests.

See

layer for providing TestConsole to an effect
logLines for reading captured Console.log calls
errorLines for reading captured Console.error calls

Signature

interface TestConsole extends Console {
  readonly errorLines: Effect<readonly Array<unknown>>;
  readonly logLines: Effect<readonly Array<unknown>>;
}

Example

(Capturing console output in tests)

import { Console, Effect } from "effect"
import { TestConsole } from "effect/testing"

const program = Effect.gen(function*() {
  yield* Console.log("Hello, World!")
  yield* Console.error("An error occurred")

  const logs = yield* TestConsole.logLines
  const errors = yield* TestConsole.errorLines

  logs // => ["Hello, World!"]
  errors // => ["An error occurred"]
}).pipe(Effect.provide(TestConsole.layer))

await Effect.runPromise(program)

Other

TestConsole

Added in v4.0.0 Source

The TestConsole namespace provides types and utilities for working with test console implementations.

When to use

Use when referring to types nested under the TestConsole namespace.

Testing

errorLines

Added in v4.0.0 Source

Returns an array of all items that have been logged by the program using Console.error thus far.

When to use

Use to assert on captured Console.error output from a program provided with TestConsole.layer.

See

logLines for reading captured Console.log output
layer for capturing console calls during a test

Signature

declare const errorLines: Effect.Effect<ReadonlyArray<unknown>, never, never>

Example

(Reading captured error lines)

import { Console, Effect } from "effect"
import { TestConsole } from "effect/testing"

const program = Effect.gen(function*() {
  yield* Console.error("Error message")
  yield* Console.error("Another error", new Error("Something went wrong"))

  const errors = yield* TestConsole.errorLines

  const messages = [errors[0], errors[1], errors[2] instanceof Error ? errors[2].message : undefined]
  messages // => ["Error message", "Another error", "Something went wrong"]
}).pipe(Effect.provide(TestConsole.layer))

await Effect.runPromise(program)

logLines

Added in v4.0.0 Source

Returns an array of all items that have been logged by the program using Console.log thus far.

When to use

Use to assert on captured Console.log output from a program provided with TestConsole.layer.

See

errorLines for reading captured Console.error output
layer for capturing console calls during a test

Signature

declare const logLines: Effect.Effect<ReadonlyArray<unknown>, never, never>

Example

(Reading captured log lines)

import { Console, Effect } from "effect"
import { TestConsole } from "effect/testing"

const program = Effect.gen(function*() {
  yield* Console.log("First message")
  yield* Console.log("Second message", { key: "value" })
  yield* Console.log("Third message", 42, true)

  const logs = yield* TestConsole.logLines

  logs // => ["First message", "Second message", { key: "value" }, "Third message", 42, true]
}).pipe(Effect.provide(TestConsole.layer))

await Effect.runPromise(program)

testConsoleWith

Added in v4.0.0 Source

Retrieves the TestConsole service for this test and uses it to run the specified workflow.

When to use

Use to access the provided test console service inside an effect.

See

layer for providing the test console service
logLines for reading captured Console.log calls directly
errorLines for reading captured Console.error calls directly

Signature

declare function testConsoleWith<A, E, R>(f: (console: TestConsole) => Effect<A, E, R>): Effect<A, E, R>

Example

(Accessing the test console service)

import { Effect } from "effect"
import { TestConsole } from "effect/testing"

const program = TestConsole.testConsoleWith((testConsole) =>
  Effect.gen(function*() {
    testConsole.log("Test message")
    testConsole.error("Test error")

    const logs = yield* testConsole.logLines
    const errors = yield* testConsole.errorLines

    logs // => ["Test message"]
    errors // => ["Test error"]
  })
).pipe(Effect.provide(TestConsole.layer))

await Effect.runPromise(program)