TestConsole.ts

TestConsole.ts overview

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.

Since v4.0.0

---

Exports Grouped by Category

• constructors
  • make
• layers
  • layer
• models
  • TestConsole (interface)
• testing
  • errorLines
  • logLines
  • testConsoleWith
• utils
  • TestConsole (namespace)
    • Entry (interface)
    • Method (type alias)

---

constructors

make

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.

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

  console.log("Captured logs:", logs)
  console.log("Captured errors:", errors)
}).pipe(Effect.provide(TestConsole.layer))

See

• layer for providing a TestConsole as a Layer

Signature

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

Source

Since v4.0.0

layers

layer

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.

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

  console.log("Captured logs:", logs)
  console.log("Captured errors:", errors)
}).pipe(Effect.provide(TestConsole.layer))

See

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

Signature

declare const layer: Layer.Layer<TestConsole, never, never>

Source

Since v4.0.0

models

TestConsole (interface)

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.

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

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

See

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

Signature

export interface TestConsole extends Console.Console {
  /**
   * Returns an array of all items that have been logged by the program using
   * `Console.log` thus far.
   *
   * **When to use**
   *
   * Use to inspect captured `Console.log` calls through a `TestConsole`
   * instance.
   */
  readonly logLines: Effect.Effect<ReadonlyArray<unknown>>
  /**
   * Returns an array of all items that have been logged by the program using
   * `Console.error` thus far.
   *
   * **When to use**
   *
   * Use to inspect captured `Console.error` calls through a `TestConsole`
   * instance.
   */
  readonly errorLines: Effect.Effect<ReadonlyArray<unknown>>
}

Source

Since v4.0.0

testing

errorLines

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.

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

  console.log(errors)
  // [
  //   ["Error message"],
  //   ["Another error", Error: Something went wrong]
  // ]
}).pipe(Effect.provide(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>

Source

Since v4.0.0

logLines

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.

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

  console.log(logs)
  // [
  //   ["First message"],
  //   ["Second message", { key: "value" }],
  //   ["Third message", 42, true]
  // ]
}).pipe(Effect.provide(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>

Source

Since v4.0.0

testConsoleWith

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.

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

    console.log("Logs:", logs) // [["Test message"]]
    console.log("Errors:", errors) // [["Test error"]]
  })
).pipe(Effect.provide(TestConsole.layer))

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 const testConsoleWith: <A, E, R>(f: (console: TestConsole) => Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>

Source

Since v4.0.0

utils

TestConsole (namespace)

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.

Source

Since v4.0.0

Entry (interface)

Represents a single console method invocation captured by the TestConsole. Each entry contains the method name and the parameters passed to it.

When to use

Use to inspect or type one captured console invocation.

Example (Typing captured console entries)

import type { TestConsole } from "effect/testing"

const entry: TestConsole.TestConsole.Entry = {
  method: "error",
  parameters: ["not found"]
}

console.log(entry.method) // "error"
console.log(entry.parameters) // ["not found"]

Signature

export interface Entry {
  readonly method: Method
  readonly parameters: ReadonlyArray<unknown>
}

Source

Since v4.0.0

Method (type alias)

Represents a console method name that can be invoked on the TestConsole. This type includes all methods available on the Console interface.

When to use

Use to type the console method name recorded in a captured test console entry.

Example (Typing captured console methods)

import type { TestConsole } from "effect/testing"

const method: TestConsole.TestConsole.Method = "log"

console.log(method) // "log"

Signature

type Method = keyof Console.Console

Source

Since v4.0.0