@spec capture_io((-> any())) :: String.t()

Captures IO generated when evaluating fun.

Returns the binary which is the captured output.

By default, capture_io replaces the Process.group_leader/0 of the current process, which is the process used by default for all IO operations. Capturing the group leader of the current process is safe to run concurrently, under async: true tests. You may also explicitly capture the group leader of another process, however that is not safe to do concurrently.

You may also capture any other named IO device, such as :stderr. This is also safe to run concurrently but, if several tests are writing to the same device at once, captured output may include output from a different test.

A developer can set a string as an input. The default input is an empty string. If capturing a named device asynchronously, an input can only be given to the first capture. Any further capture that is given to a capture on that device will raise an exception and would indicate that the test should be run synchronously.

Similarly, once a capture on a named device has begun, the encoding on that device cannot be changed in a subsequent concurrent capture. An error will be raised in this case.

IO devices

You may capture the IO of the group leader of any process, by passing a pid as argument, or from any registered IO device given as an atom. Here are some example values:

• :stdio, :standard_io - a shortcut for capturing the group leader of the current process. It is equivalent to passing self() as the first argument. This is safe to run concurrently and captures only the of the current process or any child process spawned inside the given function

• :stderr, :standard_error - captures all IO to standard error (represented internally by an Erlang process named :standard_error). This is safe to run concurrently but it will capture the output of any other test writing to the same named device

• any other atom - captures all IO to the given device given by the atom. This is safe to run concurrently but it will capture the output of any other test writing to the same named device

• any other pid (since v1.17.0) - captures all IO to the group leader of the given process. This option is not safe to run concurrently if the pid is not self(). Tests using this value must set async: true

Options

• :input - An input to the IO device, defaults to "".

• :capture_prompt - Define if prompts (specified as arguments to IO.get* functions) should be captured. Defaults to true. For IO devices other than :stdio, the option is ignored.

• :encoding (since v1.10.0) - encoding of the IO device. Allowed values are :unicode (default) and :latin1.

Examples

To capture the standard io:

iex> capture_io(fn -> IO.write("john") end) == "john"
true

iex> capture_io("this is input", fn ->
...>   input = IO.gets("> ")
...>   IO.write(input)
...> end) == "> this is input"
true

iex> capture_io([input: "this is input", capture_prompt: false], fn ->
...>   input = IO.gets("> ")
...>   IO.write(input)
...> end) == "this is input"
true

Note it is fine to use == with :stdio (the default IO device), because the content is captured per test process. However, :stderr is shared across all tests, so you will want to use =~ instead of == for assertions on :stderr if your tests are async:

iex> capture_io(:stderr, fn -> IO.write(:stderr, "john") end) =~ "john"
true

iex> capture_io(:standard_error, fn -> IO.write(:stderr, "john") end) =~ "john"
true

In particular, avoid empty captures on :stderr with async tests:

iex> capture_io(:stderr, fn -> :nothing end) == ""
true

Otherwise, if the standard error of any other test is captured, the test will fail.

To capture the IO from another process, you can pass a pid:

capture_io(GenServer.whereis(MyServer), fn ->
  GenServer.call(MyServer, :do_something)
end)

Tests that directly capture a PID cannot run concurrently.

Returning values

As seen in the examples above, capture_io returns the captured output. If you want to also capture the result of the function executed, use with_io/2.

@spec capture_io(atom() | pid() | String.t() | keyword(), (-> any())) :: String.t()

Captures IO generated when evaluating fun.

See capture_io/1 for more information.

@spec capture_io(atom() | pid(), String.t() | keyword(), (-> any())) :: String.t()

Captures IO generated when evaluating fun.

See capture_io/1 for more information.

@spec with_io((-> any())) :: {any(), String.t()}

Invokes the given fun and returns the result and captured output.

It accepts the same arguments and options as capture_io/1.

Examples

{result, output} =
  with_io(fn ->
    IO.puts("a")
    IO.puts("b")
    2 + 2
  end)

assert result == 4
assert output == "a\nb\n"

@spec with_io(atom() | pid() | String.t() | keyword(), (-> any())) ::
  {any(), String.t()}

Invokes the given fun and returns the result and captured output.

See with_io/1 for more information.

@spec with_io(atom() | pid(), String.t() | keyword(), (-> any())) ::
  {any(), String.t()}

Invokes the given fun and returns the result and captured output.

See with_io/1 for more information.