@spec assert_all_completed(
  LetItCrash.Async.Report.t(),
  keyword()
) :: :ok | {:error, term()}

Asserts that the observed block finished within within: milliseconds and that every spawned process either completed or crashed (no still-running work at block exit).

Options

• :within (required) — wall-clock budget in milliseconds; compared against report.duration_ms

Returns

• :ok — under budget and no in-flight work remains
• {:error, {:exceeded_within, %{duration_ms: n, budget_ms: w}}} — the block took longer than within
• {:error, {:incomplete, list}} — one or more spawned pids never reached either :completed or :crashed within the settle window. list is the unfinished {pid, kind, started_at} entries. Requires trace: true on the observe_async/2 call (without it the spawned list is empty and this branch never fires)

Examples

report = LetItCrash.Async.observe_async(fn ->
  Task.async(fn -> :timer.sleep(50) end) |> Task.await()
end)

assert :ok = LetItCrash.Async.assert_all_completed(report, within: 500)

@spec assert_idempotent(
  (-> any()),
  keyword()
) :: :ok | {:error, term()}

Asserts that calling fun twice in succession leaves the observed state unchanged between the two runs.

Idempotency requires re-execution by definition, so this assertion takes a 0-arity function (not a Report). The user supplies a :state 0-arity function that returns a snapshot of whatever state is relevant — e.g. the count of rows in a DB table, the contents of an ETS table, the value in an Agent. The snapshots must be comparable with ==.

The flow:

1. Run fun once.
2. Snapshot state — call this after_first.
3. Run fun again.
4. Snapshot state — call this after_second.
5. Assert after_first == after_second.

Only the snapshots after each run are compared; an initial pre-run snapshot would distinguish a no-op fn from a side-effecting one, but that's a different property (purity, not idempotency) and is left for the caller to assert separately if needed.

Options

• :state (required) — 0-arity function returning the state snapshot

Returns

• :ok — fun is idempotent
• {:error, {:state_changed, %{after_first: a, after_second: b}}} — running fun a second time changed the snapshot

Examples

:ok = LetItCrash.Async.assert_idempotent(
  fn -> Map.put(%{}, :a, 1) end,
  state: fn -> :no_persistent_state end
)

@spec assert_no_silent_swallow(
  LetItCrash.Async.Report.t(),
  keyword()
) :: :ok | {:error, term()}

Asserts that no exception was silently swallowed during the observed block.

A "silent swallow" is the presence of any exception-shaped telemetry event (:task.exception, :oban.job.exception, :phoenix.live_view.handle_async.exception) inside the block. If an exception had propagated to the test process, the test would have already failed — so the only way exceptions reach this Report is by being absorbed by a non-linked Task, a retried Oban job, or a swallowed LiveView async.

When the block was observed with trace: true, raw-Task crashes (which emit no telemetry) also count: they surface as synthesized {[:task, :exit], %{}, %{pid: pid, reason: reason}} entries, where reason is the exit reason — typically {exception, stacktrace} for a raised error.

Returns

• :ok — no exceptions seen
• {:error, {:silent_swallow, list}} — one or more exception events were captured; list is the list of {event, measurements, metadata} tuples

Examples

report = LetItCrash.Async.observe_async(fn ->
  Task.start(fn -> raise "boom" end)
  Process.sleep(50)
end)

{:error, {:silent_swallow, [{[:task, :exception], _, _}]}} =
  LetItCrash.Async.assert_no_silent_swallow(report)

@spec observe_async(
  (-> any()),
  keyword()
) :: LetItCrash.Async.Report.t()

Runs fun and returns a %LetItCrash.Async.Report{} describing the async work observed during the call.

Telemetry handlers are attached on entry and detached on exit, even when fun raises. If fun raises, the exception is re-raised after the observer cleans up — the Report is computed for cleanup purposes but is not returned in that path.

Options

• :observe — list of telemetry event names to subscribe to. Defaults to the standard Task/Oban/LiveView exception events.
• :trace — false (default) or true. When true, enables :erlang.trace-based process-exit observation of the block's spawn subtree. This populates report.spawned/completed/crashed and surfaces raw-Task crashes (which emit no telemetry) as {[:task, :exit], %{}, %{pid:, reason:}} entries in report.exceptions. Off by default — opt in per call. If the calling process is already traced by another tool, tracing is skipped and :trace_unavailable is added to report.warnings (the block still runs normally).
• :settle — non-negative integer (default 50). Milliseconds to wait at block exit for outstanding spawned pids to finish before classifying the remainder as still-running. Only meaningful with trace: true.
• :sandbox — :inherit (default) or :off. Documentation-only; does not change behavior.

Examples

# An Oban job that raises is caught by Oban's perform wrapper, which
# emits `[:oban, :job, :exception]`. `observe_async/1` captures it.
report = LetItCrash.Async.observe_async(fn ->
  :telemetry.execute(
    [:oban, :job, :exception],
    %{duration: 1},
    %{worker: "MyWorker", kind: :error, reason: %RuntimeError{message: "boom"}}
  )
end)

assert {:error, {:silent_swallow, _}} =
         LetItCrash.Async.assert_no_silent_swallow(report)

Pure Elixir Task.start/1 + raise does NOT emit any telemetry today, so it will NOT show up in the report on the telemetry path. Pass trace: true to catch it via process-exit tracing — the crash surfaces as a {[:task, :exit], _, _} entry in report.exceptions:

report =
  LetItCrash.Async.observe_async(
    fn -> Task.start(fn -> raise "boom" end) end,
    trace: true,
    settle: 100
  )

assert {:error, {:silent_swallow, _}} =
         LetItCrash.Async.assert_no_silent_swallow(report)