# `ExUnit.CaptureIO`
[🔗](https://github.com/elixir-lang/elixir/blob/7ff272706afc522e74121493b7166719985cb099/lib/ex_unit/lib/ex_unit/capture_io.ex#L5)

Functionality to capture IO for testing.

## Examples

    defmodule AssertionTest do
      use ExUnit.Case

      import ExUnit.CaptureIO

      test "example" do
        assert capture_io(fn -> IO.puts("a") end) == "a\n"
      end

      test "another example" do
        assert with_io(fn ->
          IO.puts("a")
          IO.puts("b")
          2 + 2
        end) == {4, "a\nb\n"}
      end
    end

# `capture_io_opts`

```elixir
@type capture_io_opts() :: [
  input: String.t(),
  capture_prompt: boolean(),
  encoding: :unicode | :latin1
]
```

# `capture_io`

```elixir
@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`.

# `capture_io`

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

Captures IO generated when evaluating `fun`.

See `capture_io/1` for more information.

# `capture_io`

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

Captures IO generated when evaluating `fun`.

See `capture_io/1` for more information.

# `with_io`
*since 1.13.0* 

```elixir
@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"

# `with_io`
*since 1.13.0* 

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

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

See `with_io/1` for more information.

# `with_io`
*since 1.13.0* 

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

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

See `with_io/1` for more information.

---

*Consult [api-reference.md](api-reference.md) for complete listing*