View Source Sentry.Test (Sentry v10.5.0)
Utilities for testing Sentry reports.
usage
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_modeistrue, the:dsnoption behaves differently. When:dsnis not set orniland you're collecting events, you'll still be able to collect events—even if under normal circumstances a missing:dsnmeans events don't get reported. If:dsnisniland 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
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...>
endNow, 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 :doneNow, 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"Link to this section Summary
Functions
Allows pid_to_allow to collect events back to the root process via owner_pid.
Cleans up test resources associated with owner_pid.
Pops all the collected events from the current process.
Starts collecting events.
Starts collecting events from the current process.
Link to this section Functions
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)@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.
@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
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"@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
Options
:owner- the PID of the owner process that will collect the events. Defaults toself/0.:cleanup- a boolean that controls whether collected resources around the owner process should be cleaned up when the owner process exits. Defaults totrue. Iffalse, you'll need to manually callcleanup/1to clean up the resources.
examples
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@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_reportsFor a more flexible way to start collecting events, see start_collecting/1.