chore(docs): update Sentry.Test docs to reflect changes

Author: solnic

lib/sentry/test.ex

@@ -230,8 +230,7 @@ defmodule Sentry.Test do
 
   > #### Deprecated {: .warning}
   >
-  > This function is deprecated and will be removed in v13.0.0.
-  > Use `setup_sentry/1` or `start_collecting_sentry_reports/0` instead.
+  > This function is deprecated and will be removed in v14.0.0. Use `setup_sentry/1` instead.
 
   The `:owner`, `:cleanup`, and `:key` options are no longer supported and are ignored.
   """
@@ -252,11 +251,11 @@ defmodule Sentry.Test do
 
   > #### Deprecated {: .warning}
   >
-  > This function is deprecated and will be removed in v13.0.0.
-  > Cleanup is now handled automatically via `on_exit` callbacks.
+  > This function is deprecated and will be removed in v14.0.0.
+  > Cleanup is now handled automatically when the owning test process exits.
   """
   @doc since: "10.2.0"
-  @doc deprecated: "Cleanup is now automatic via on_exit callbacks"
+  @doc deprecated: "Cleanup is now automatic when the owning test process exits"
   @spec cleanup(pid()) :: :ok
   def cleanup(owner_pid) when is_pid(owner_pid) do
     :ok

lib/sentry/test/registry.ex

@@ -163,6 +163,16 @@ defmodule Sentry.Test.Registry do
     {:ok, %{owner_monitors: %{}}}
   end
 
+  # Serialization note: every claim funnels through this single named
+  # GenServer and holds it across TWO blocking round-trips to the
+  # ownership server — `ensure_scope_owner/1`'s
+  # `NimbleOwnership.get_and_update/4` and `NimbleOwnership.allow/4`.
+  # This is the deliberate price of atomicity (no two concurrent async
+  # tests can both pass a check-then-write race for the same
+  # `allowed_pid`). It is acceptable because claims happen at test
+  # setup, not per event, and the hot config/buffer read paths
+  # (`lookup_allow_owner/1`, `lookup_processor_for/1`) bypass this
+  # GenServer with lock-free direct ETS reads.
   @impl true
   def handle_call({:claim_allow, owner_pid, allowed_pid, mode}, _from, state) do
     state = ensure_owner_monitored(state, owner_pid)
@@ -232,14 +242,25 @@ defmodule Sentry.Test.Registry do
   # `Sentry.Test.setup_collector/1` (e.g. a test that uses
   # `Sentry.Test.Config.put/1` standalone). When the owner already
   # owns the key, the existing metadata is preserved.
+  #
+  # INVARIANT: the `:sentry_test_scope` key's metadata is overloaded —
+  # `Sentry.Test.setup_collector/1` stores the per-test collector ETS
+  # table name (an atom) under it, while this function stores a bare
+  # `%{}` marker for collector-less scopes. `Sentry.Test`'s
+  # `owner_collecting?/1` distinguishes the two purely by value type
+  # (atom = collecting, map = not). Therefore the update fun below MUST
+  # preserve an existing value (`current -> {:ok, current}`) and MUST
+  # NOT overwrite it with `%{}`; doing so would silently turn a
+  # collecting scope into a non-collecting one with no type error.
   defp ensure_scope_owner(owner_pid) do
     case NimbleOwnership.get_and_update(
            @ownership_server,
            owner_pid,
            @scope_key,
            # Metadata MUST be non-nil so that NimbleOwnership treats
            # `owner_pid` as a key owner (its `cond` in `allow/4` checks
-           # truthiness of the metadata). Preserve any existing value.
+           # truthiness of the metadata). Preserve any existing value
+           # (see the INVARIANT above — never clobber a collector atom).
            fn
              nil -> {:ok, %{}}
              current -> {:ok, current}

lib/sentry/test/scope/registry.ex

@@ -7,12 +7,19 @@ defmodule Sentry.Test.Scope.Registry do
   #
   #   * `{:sentry_test_scope, owner_pid} -> %Scope{}` in `:persistent_term` —
   #     one entry per active test scope, owns its overrides.
-  #   * `:sentry_test_scope_allows` ETS table (named, public, set) —
-  #     reverse index `{allowed_pid, owner_pid}` mapping each
-  #     explicitly-routed pid back to the scope that claimed it.
-  #     Owned by `Sentry.Test.Registry`. Direct ETS reads on the config
+  #   * `:sentry_test_pid_routing` ETS table (named, public, set) —
+  #     single merged routing table owned by `Sentry.Test.Registry`.
+  #     Rows are 3-tuples
+  #     `{allowed_pid, owner_pid_or_nil, processor_name_or_nil}`: the
+  #     owner field is the reverse index mapping each explicitly-routed
+  #     pid back to the scope that claimed it (read here via
+  #     `lookup_allow_owner/1`); the processor field routes buffered
+  #     events (logs, metrics) from that pid to a per-test
+  #     `Sentry.TelemetryProcessor`. Direct ETS reads on the config
   #     read path; conflict-checked writes serialize through that
-  #     GenServer for atomic check-and-insert.
+  #     GenServer for atomic check-and-insert. Owner exit is handled by
+  #     that GenServer's `:DOWN` monitor (routing-row prune +
+  #     `handle_owner_down/1`), not `ExUnit.Callbacks.on_exit/1`.
   #   * `@counter_key -> :counters.t()` — atomic counter for cheap
   #     "any active scopes?" short-circuits, so config reads in
   #     production cost essentially nothing.
@@ -29,8 +36,11 @@ defmodule Sentry.Test.Scope.Registry do
   #                     GenServers started via `start_supervised/1`).
   #   3. by_allow     — walk `[pid | ancestors]`; reverse-allow lookup
   #                     for each candidate (the pid was explicitly
-  #                     routed onto a scope via `allow/2` or
-  #                     auto-allowed in `Config.put/1`).
+  #                     routed onto a scope via
+  #                     `Sentry.Test.allow_sentry_reports/2` /
+  #                     `Sentry.Test.Config.allow/2`, or auto-allowed in
+  #                     `Sentry.Test.Config.put/1` — all of which claim
+  #                     through `Sentry.Test.Registry.claim_allow/3`).
   #
   # Globally-supervised processes (`:logger`, `:logger_sup`,
   # `Sentry.Supervisor`) have no caller/ancestor link to any test and