mix excessibility.debug (Excessibility v0.20.0)

Run tests and generate a comprehensive debug report with all snapshots.

All arguments are passed through to mix test, so you can use any test filtering options.

This command automatically enables telemetry capture by setting EXCESSIBILITY_TELEMETRY_CAPTURE=true, which captures:

Mount events
handle_event calls (clicks, submits)
handle_params calls (navigation)
All render cycles (form updates, state changes)

Render event capture dramatically increases timeline visibility (often 10-20x more events), enabling powerful analyzer insights like memory leak detection, performance bottlenecks, and event pattern analysis.

Usage

# Run a test file
mix excessibility.debug test/my_test.exs

# Run a specific test by line number
mix excessibility.debug test/my_test.exs:42

# Run tests with a tag
mix excessibility.debug --only live_view

# Run a describe block
mix excessibility.debug test/my_test.exs:10

# With debug options
mix excessibility.debug test/my_test.exs --format=json
mix excessibility.debug test/my_test.exs --full
mix excessibility.debug test/my_test.exs --minimal
mix excessibility.debug test/my_test.exs --highlight=current_user,cart_items

Flags

--format=markdown|json|package|digest - Output format (default: markdown)
--full - Disable all filtering, show complete assigns
--minimal - Timeline only, no detailed snapshots
--no-filter-ecto - Keep Ecto metadata (meta, NotLoaded)
--no-filter-phoenix - Keep Phoenix internals (flash, changed)
--highlight=field1,field2 - Custom fields to highlight in timeline

Analysis Options

--analyze=NAMES - Run specific analyzers (comma-separated). Available: memory, performance, data_growth, event_pattern, ecto_query_analysis, state_machine
--analyze=all - Run all available analyzers
--profile=NAME - Use a predefined profile (quick, memory, performance, full)
--no-analyze - Skip analysis, show timeline only
--verbose - Show detailed stats even when no issues found

Query Plan Evidence (opt-in, Postgres-only)

--plan - Boolean flag. Capture value-free EXPLAIN plan evidence for each SELECT and attach it to the digest's query shapes. Runs EXPLAIN (FORMAT JSON) <query> — it plans but never executes the query, so it touches no data. SELECT-only.
--plan-analyze - Boolean flag. Capture EXPLAIN ANALYZE plan evidence, which includes actual row counts. This executes the query, so it is double-gated: it additionally requires config :excessibility, query_plan_allow_analyze: true. Only run inside a DB sandbox / read-only environment.

Both are bare boolean flags and can be combined with a test path in any order, e.g. mix excessibility.debug --plan test/foo.exs or mix excessibility.debug test/foo.exs --plan.

Safety notes:

SELECT-only. Only SELECT queries are ever run through EXPLAIN; non-SELECT statements are never re-executed.
EXPLAIN does not ANALYZE by default. Plain --plan runs EXPLAIN (FORMAT JSON) <query>, which plans but never executes the query, so it touches no data.
ANALYZE is double-gated. --plan-analyze executes the query to gather real row counts, so it additionally requires config :excessibility, query_plan_allow_analyze: true. Without that config it downgrades to plain EXPLAIN with a warning. Only run ANALYZE inside a DB sandbox.

Benchmark Mode (opt-in)

--benchmark=N - Run the test N times and write a value-free benchmark.json with robust cold/warm timing stats (median + MAD) per (view, callback) and per query-fingerprint. Sample 1 is treated as cold (compilation, connection warmup, cold caches); samples 2..N are warm, and the two are reported separately so a cold first run cannot poison the median.
Timing is diagnostic ONLY and never enters the digest. An advisory outlier (a warm sample beyond median + k*mad) means "green = no relative outlier in these samples, not 'fast'." It is never a pass/fail gate.
```
mix excessibility.debug --benchmark=20 test/my_live_view_test.exs
```