TestConsole unstable

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 Since v4.0.0 Source

Constructors

make

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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)