View Source Sentry.Test (Sentry v10.8.0)

Utilities for testing Sentry reports.

Usage

This module is based on collecting reported events and then retrieving them to perform assertions. The functionality here is only available if the :test_mode configuration option is set to true—see Sentry's configuration section. You can start collecting events from a process by calling start_collecting_sentry_reports/0. Then, you can use Sentry as normal and report events (through functions such as Sentry.capture_message/1 or Sentry.capture_exception/1). Finally, you can retrieve the collected events by calling pop_sentry_reports/0.

Test Mode and DSN
If :test_mode is true, the :dsn option behaves differently. When :dsn is not set or nil and you're collecting events, you'll still be able to collect events—even if under normal circumstances a missing :dsn means events don't get reported. If :dsn is nil and you're not collecting events, the event is simply ignored. See the table below for a summary for this behavior.

`:test_mode`	`:dsn`	Collecting events?	Behavior
`true`	`nil`	yes	Event is collected
`true`	`nil`	no	Event is ignored (silently)
`true`	set	yes	Event is collected
`true`	set	no	Makes HTTP request to configured DSN (could be Bypass)
`false`	`nil`	irrelevant	Ignores event
`false`	set	irrelevant	Makes HTTP request to configured DSN (could be Bypass)

Examples

Let's imagine writing a test using the functions in this module. First, we need to start collecting events:

test "reporting from child processes" do
  parent_pid = self()

  # Collect reports from self().
  assert :ok = Test.start_collecting_sentry_reports()

  # <we'll fill this in below...>
end

Now, we can report events as normal. For example, we can report an event from the parent process:

assert {:ok, ""} = Sentry.capture_message("Oops from parent process")

We can also report events from "child" processes.

# Spawn a child that waits for the :go message and then reports an event.
{:ok, child_pid} =
  Task.start_link(fn ->
    receive do
      :go ->
        assert {:ok, ""} = Sentry.capture_message("Oops from child process")
        send(parent_pid, :done)
    end
  end)

# Start the child and wait for it to finish.
send(child_pid, :go)
assert_receive :done

Now, we can retrieve the collected events and perform assertions on them:

assert [%Event{} = event1, %Event{} = event2] = Test.pop_sentry_reports()
assert event1.message.formatted == "Oops from parent process"
assert event2.message.formatted == "Oops from child process"

Summary

Functions

allow_sentry_reports(owner_pid, pid_to_allow)

Allows pid_to_allow to collect events back to the root process via owner_pid.

cleanup(owner_pid)

Cleans up test resources associated with owner_pid.

pop_sentry_reports(owner_pid \\ self())

Pops all the collected events from the current process.

start_collecting(options \\ [])

Starts collecting events.

start_collecting_sentry_reports(context \\ %{})

Starts collecting events from the current process.

Functions

allow_sentry_reports(owner_pid, pid_to_allow)

(since 10.2.0)

@spec allow_sentry_reports(pid(), pid() | (() -> pid())) :: :ok

Allows pid_to_allow to collect events back to the root process via owner_pid.

owner_pid must be a PID that is currently collecting events or has been allowed to collect events. If that's not the case, this function raises an error.

pid_to_allow can also be a function that returns a PID. This is useful when you want to allow a registered process that is not yet started to collect events. For example:

Sentry.Test.allow_sentry_reports(self(), fn -> Process.whereis(:my_process) end)

cleanup(owner_pid)

(since 10.2.0)

@spec cleanup(pid()) :: :ok

Cleans up test resources associated with owner_pid.

See the :cleanup option in start_collecting/1 and the corresponding example for more information.

pop_sentry_reports(owner_pid \\ self())

(since 10.2.0)

@spec pop_sentry_reports(pid()) :: [Sentry.Event.t()]

Pops all the collected events from the current process.

This function returns a list of all the events that have been collected from the current process and all the processes that were allowed through it. If the current process is not collecting events, this function raises an error.

After this function returns, the current process will still be collecting events, but the collected events will be reset to [].

Examples

iex> Sentry.Test.start_collecting_sentry_reports()
:ok
iex> Sentry.capture_message("Oops")
{:ok, ""}
iex> [%Sentry.Event{} = event] = Sentry.Test.pop_sentry_reports()
iex> event.message.formatted
"Oops"

start_collecting(options \\ [])

(since 10.2.0)

@spec start_collecting(keyword()) :: :ok

Starts collecting events.

This function starts collecting events reported from the given (owner) process. If you want to allow other processes to report events, you need to allow them to report events back to the owner process. See allow/2 for more information on allowances. If the owner process is already allowed by another process, this function raises an error.

Options

:owner - the PID of the owner process that will collect the events. Defaults to self/0.
:cleanup - a boolean that controls whether collected resources around the owner process should be cleaned up when the owner process exits. Defaults to true. If false, you'll need to manually call cleanup/1 to clean up the resources.

Examples

The :cleanup option can be used to implement expectation-based tests, akin to something like Mox.expect/4.

test "implementing an expectation-based test workflow" do
  test_pid = self()

  Test.start_collecting(owner: test_pid, cleanup: false)

  on_exit(fn ->
    assert [%Event{} = event] = Test.pop_sentry_reports(test_pid)
    assert event.message.formatted == "Oops"
    assert :ok = Test.cleanup(test_pid)
  end)

  assert {:ok, ""} = Sentry.capture_message("Oops")
end

start_collecting_sentry_reports(context \\ %{})

(since 10.2.0)

@spec start_collecting_sentry_reports(map()) :: :ok

Starts collecting events from the current process.

This function starts collecting events reported from the current process. If you want to allow other processes to report events, you need to allow them to report events back to the current process. See allow/2 for more information on allowances. If the current process is already allowed by another process, this function raises an error.

The context parameter is ignored. It's there so that this function can be used as an ExUnit setup callback. For example:

import Sentry.Test

setup :start_collecting_sentry_reports

For a more flexible way to start collecting events, see start_collecting/1.