# `CaptureLogger`
[🔗](https://github.com/halostatue/capture_logger/blob/v1.0.1/lib/capture_logger.ex#L6)

Functionality to capture logs for testing.

## Examples

```elixir
defmodule AssertionTest do
  use ExUnit.Case

  alias LoggerJSON.Formatters.Basic
  import CaptureLogger
  require Logger

  test "example" do
    {result, log} =
      with_log([formatter: Basic.new()], fn ->
        Logger.error("log msg")
        2 + 2
      end)

    assert result == 4
    assert Jason.decode!(log)["message"] == "log msg"
  end

  test "check multiple captures concurrently" do
    fun = fn ->
      for msg <- ["hello", "hi"] do
        log = assert capture_log(
          [formatter: Basic],
          fn -> Logger.error(msg) end
        )
        assert Jason.decode!(log)["message"] == msg
      end

      Logger.debug("testing")
    end

    assert capture_log([formatter: Basic],fun) =~ "hello"
    assert capture_log([formatter: Basic], fun) =~ "\"message\":\"testing\""
  end
end
```

# `capture_log_opts`

```elixir
@type capture_log_opts() :: [
  {:level, Logger.level() | nil}
  | {:formatter, {module(), term()} | module() | nil}
  | {atom(), term() | nil}
]
```

# `capture_log`

```elixir
@spec capture_log(capture_log_opts(), (-&gt; any())) :: String.t()
```

Captures Logger messages generated when evaluating `fun`.

Returns the binary which is the captured output.

This function mutes the default logger handler and captures any log messages sent to
Logger from the calling processes. It is possible to ensure explicit log messages from
other processes are captured by waiting for their exit or monitor signal.

Note that when the `async` is set to `true` on `use ExUnit.Case`, messages from other
tests might be captured. This is OK as long you consider such cases in your assertions,
typically by using the `=~/2` operator to perform partial matches.

To get the result of the evaluation along with the captured log, use `with_log/2`.

### Options

- `:level`: Configure the level to capture with `:level`, which will set the capturing
  level for the duration of the capture. For instance, if the log level is set to
  `:error`, then any message with a lower level will be ignored. The default level is
  `nil`, which will capture all messages.

  Note this setting does not override the overall `Logger.level/0` value. Therefore, if
  `Logger.level/0` is set to a higher level than the one configured in this function, no
  message will be captured. The behaviour is undetermined if async tests change Logger
  level.

- `:formatter`: The formatter to use for formatting log messages. May be provided either
  as `t:module/0` or as `{module, options}`. If provided as a module, it must respond to
  `new/1` and the remaining options will be provided as configuration to the formatter
  module.

  If not provided, defaults to `Logger.default_formatter/1` with any other options
  forwarded as a configuration to the default formatter.

  The default formatter may also be set with the `:formatter` configuration key for
  `:capture_logger`. When set in a compile-time configuration file (`config/test.exs`),
  it should be provided as a `{module, options}` tuple. When set in `config/runtime.exs`
  or `test/test_helper.exs`, it may be possible to call `module.new(options)`.

# `start`

Starts the CaptureLogger server under a supervisor. This should be called with
`ExUnit.start/1`.

# `with_log`

```elixir
@spec with_log(capture_log_opts(), (-&gt; result)) :: {result, log :: String.t()}
when result: any()
```

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

It accepts the same arguments and options as `capture_log/2`.

## Examples

```elixir
{result, log} =
  with_log(fn ->
    Logger.error("log msg")
    2 + 2
  end)

assert result == 4
assert log =~ "log msg"
```

---

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