docs: add when/exceptions to smells

2026-04-30 05:26:03 -07:00
parent 1a934eb2e3
commit 29b91bead6
2 changed files with 1462 additions and 0 deletions
@@ -27,6 +27,47 @@ end

 **Source:** Elixir's test suite has 39 `assert_receive`/`refute_receive` calls in `task_test.exs` alone, vs 0 `Process.sleep(N)` for synchronization.

+### When to Apply This Rule
+
+**Triggers:**
+- `Process.sleep` followed by `assert_received` (note: `assert_received` checks mailbox NOW, doesn't wait)
+- Tests with "magic number" sleeps (50, 100, 200ms)
+- CI failures on tests that always pass locally
+
+**Example — the smell:**
+```elixir
+test "worker processes job" do
+  Worker.submit(job)
+  Process.sleep(200)
+  assert_received {:job_complete, ^job}
+end
+```
+
+**Example — fixed:**
+```elixir
+test "worker processes job" do
+  Worker.submit(job)
+  assert_receive {:job_complete, ^job}, 5000
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- You're testing that something does NOT happen within a time window (use `refute_receive` with explicit timeout instead)
+- The test requires a minimum elapsed time as part of the assertion (e.g., testing a cooldown)
+
+**Example of acceptable use:**
+```elixir
+test "debouncer doesn't fire before window" do
+  Debouncer.trigger(:action, 100)
+  refute_receive :action, 50  # Verify it HASN'T fired after 50ms
+  assert_receive :action, 200  # Then verify it DOES fire
+end
+```
+
+**Why it's OK here:** The `refute_receive` with a timeout IS the assertion — we're verifying that the message hasn't arrived yet. The timing is the behavior under test.
+
 ---

 ## 2. Not Using `start_supervised` in Tests
@@ -52,6 +93,54 @@ end

 **Source:** `lib/ex_unit/lib/ex_unit/callbacks.ex:277-340` — `start_supervised` is designed specifically for this: guaranteed shutdown in reverse order, no leaked processes, no race conditions.

+### When to Apply This Rule
+
+**Triggers:**
+- `GenServer.start_link` or `Supervisor.start_link` in test setup blocks
+- Manual `on_exit` cleanup for processes
+- Test failures that leave zombie processes (ports exhausted, name conflicts)
+
+**Example — the smell:**
+```elixir
+setup do
+  {:ok, cache} = MyApp.Cache.start_link(name: :test_cache)
+  {:ok, db} = MyApp.DB.start_link(pool_size: 1)
+  on_exit(fn ->
+    GenServer.stop(cache)
+    GenServer.stop(db)
+  end)
+  %{cache: cache, db: db}
+end
+```
+
+**Example — fixed:**
+```elixir
+setup do
+  cache = start_supervised!({MyApp.Cache, name: :test_cache})
+  db = start_supervised!({MyApp.DB, pool_size: 1})
+  %{cache: cache, db: db}
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- Testing supervision tree behavior itself (restart strategies, shutdown order)
+- The process must be linked to the test process to test crash propagation
+- You need a process started OUTSIDE ExUnit's supervisor (e.g., testing distributed node behavior)
+
+**Example of acceptable use:**
+```elixir
+test "crash propagates to caller" do
+  Process.flag(:trap_exit, true)
+  {:ok, pid} = CrashableWorker.start_link(self())
+  send(pid, :crash)
+  assert_receive {:EXIT, ^pid, :boom}
+end
+```
+
+**Why it's OK here:** The test is verifying link/exit behavior. Using `start_supervised!` would put the process under ExUnit's supervisor, which would intercept the crash and defeat the purpose of the test.
+
 ---

 ## 3. Asserting Exact Equality on Concurrent/Shared Output
@@ -75,6 +164,52 @@ end

 **Source:** `lib/ex_unit/lib/ex_unit/capture_io.ex` docs explicitly warn: "use `=~` instead of `==` for assertions on `:stderr` if your tests are async"

+### When to Apply This Rule
+
+**Triggers:**
+- `== "..."` assertions on `capture_io(:stderr, ...)` in async tests
+- Tests that fail intermittently with "extra" output in the captured string
+- Assertions on Logger output that include timestamps or metadata
+
+**Example — the smell:**
+```elixir
+use ExUnit.Case, async: true
+
+test "warns on deprecation" do
+  output = capture_io(:stderr, fn -> MyModule.deprecated_func() end)
+  assert output == "[warning] deprecated_func/0 is deprecated\n"
+end
+```
+
+**Example — fixed:**
+```elixir
+use ExUnit.Case, async: true
+
+test "warns on deprecation" do
+  output = capture_io(:stderr, fn -> MyModule.deprecated_func() end)
+  assert output =~ "deprecated_func/0 is deprecated"
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- Capturing `:stdio` (group leader), which is per-process and safe for async tests
+- Running with `async: false` where no concurrent output interference is possible
+- Testing exact formatted output in a synchronous, isolated context
+
+**Example of acceptable use:**
+```elixir
+use ExUnit.Case, async: true
+
+test "prints exact format to stdout" do
+  # :stdio uses group leader — per-process, no interference
+  assert capture_io(fn -> IO.puts("hello") end) == "hello\n"
+end
+```
+
+**Why it's OK here:** Capturing `:stdio` (the default) uses the process group leader, which is isolated per test process. No other test can pollute it, even in async mode.
+
 ---

 ## 4. Registering Global Names in Async Tests
@@ -103,6 +238,58 @@ end

 **Source:** `lib/elixir/test/elixir/registry_test.exs:28` — `name = :"#{config.test}_#{partitions}_#{inspect(keys)}"` — always derives unique names from test context.

+### When to Apply This Rule
+
+**Triggers:**
+- Hardcoded atom names in `GenServer.start_link` inside async test modules
+- `{:error, {:already_started, _}}` errors in test output
+- Tests that pass alone but fail when the full suite runs
+
+**Example — the smell:**
+```elixir
+use ExUnit.Case, async: true
+
+test "cache stores and retrieves" do
+  {:ok, _} = Cachex.start_link(name: :test_cache)
+  Cachex.put(:test_cache, :key, "value")
+  assert Cachex.get!(:test_cache, :key) == "value"
+end
+```
+
+**Example — fixed:**
+```elixir
+use ExUnit.Case, async: true
+
+test "cache stores and retrieves", %{test: test_name} do
+  {:ok, _} = Cachex.start_link(name: test_name)
+  Cachex.put(test_name, :key, "value")
+  assert Cachex.get!(test_name, :key) == "value"
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- The test module uses `async: false` and properly cleans up the named process
+- You're testing the name registration behavior itself
+- Using `start_supervised!` which handles cleanup automatically (though names still can't collide across concurrent modules)
+
+**Example of acceptable use:**
+```elixir
+use ExUnit.Case, async: false  # Explicitly synchronous
+
+setup do
+  pid = start_supervised!({MyServer, name: :singleton_server})
+  %{pid: pid}
+end
+
+test "singleton server responds" do
+  assert MyServer.ping(:singleton_server) == :pong
+end
+```
+
+**Why it's OK here:** `async: false` guarantees no other test module runs concurrently. The named process won't collide, and `start_supervised!` ensures cleanup between tests.
+
 ---

 ## 5. Testing Private Functions Directly
@@ -125,6 +312,65 @@ end

 **Source:** The Elixir test suite tests public APIs exclusively. `gen_server_test.exs` tests `GenServer.call/cast/stop` — never the internal `handle_*` callbacks directly.

+### When to Apply This Rule
+
+**Triggers:**
+- Functions prefixed with `__` or marked `@doc false` being called in tests
+- Test file imports or aliases internal modules not part of the public API
+- Tests that break after internal refactoring even though external behavior is unchanged
+
+**Example — the smell:**
+```elixir
+defmodule MyApp.Parser do
+  def parse(input), do: input |> tokenize() |> build_ast()
+
+  # Made public just for testing!
+  @doc false
+  def tokenize(input), do: ...
+  @doc false
+  def build_ast(tokens), do: ...
+end
+
+# Test:
+test "tokenizer splits on commas" do
+  assert MyApp.Parser.tokenize("a,b,c") == ["a", "b", "c"]
+end
+```
+
+**Example — fixed:**
+```elixir
+# Test through the public API
+test "parser handles comma-separated input" do
+  assert MyApp.Parser.parse("a,b,c") == %AST{nodes: ["a", "b", "c"]}
+end
+
+# OR extract into its own module if tokenizing is genuinely reusable:
+defmodule MyApp.Tokenizer do
+  def tokenize(input), do: ...
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- The "private" function is actually a public utility that other modules depend on (it should be `@doc`'d)
+- Property-based testing where you need to verify invariants on intermediate transformations
+- Testing a complex algorithm step-by-step during development (remove these tests before merging)
+
+**Example of acceptable use:**
+```elixir
+# Pure algorithmic module where each step has documented guarantees
+defmodule MyApp.Compiler.Optimizer do
+  @doc "Remove dead code branches. Used by Compiler pipeline."
+  def eliminate_dead_code(ast), do: ...
+
+  @doc "Inline constant expressions. Used by Compiler pipeline."
+  def inline_constants(ast), do: ...
+end
+```
+
+**Why it's OK here:** These aren't private functions exposed for testing — they're public steps in a compilation pipeline. Each has its own documented contract and is used by other modules.
+
 ---

 ## 6. Not Cleaning Up After Global State Changes
@@ -157,6 +403,53 @@ end

 **Source:** `lib/logger/test/logger_test.exs:12-17` — Every Logger config change has a corresponding `on_exit` restoration. `lib/logger/test/test_helper.exs:57-62` — `capture_log` uses `after` to always restore level.

+### When to Apply This Rule
+
+**Triggers:**
+- `Application.put_env`, `System.put_env`, `Logger.configure` in tests without corresponding restoration
+- Tests that pass in isolation but fail in the full suite
+- "Works on my machine" but fails in CI (different test ordering)
+
+**Example — the smell:**
+```elixir
+test "respects timezone setting" do
+  System.put_env("TZ", "UTC")
+  assert MyApp.current_time().zone == "UTC"
+  # System env is now polluted for all remaining tests!
+end
+```
+
+**Example — fixed:**
+```elixir
+test "respects timezone setting" do
+  original = System.get_env("TZ")
+  System.put_env("TZ", "UTC")
+  on_exit(fn ->
+    if original, do: System.put_env("TZ", original), else: System.delete_env("TZ")
+  end)
+
+  assert MyApp.current_time().zone == "UTC"
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- The state change is idempotent and matches the test suite's baseline (setting it to what it already is)
+- You're in an integration test with a completely isolated environment (Docker container, separate VM)
+
+**Example of acceptable use:**
+```elixir
+# Test helper that always restores to known baseline
+setup do
+  # This IS the baseline — safe to set without storing original
+  Logger.configure(level: :warning)
+  on_exit(fn -> Logger.configure(level: :warning) end)
+end
+```
+
+**Why it's OK here:** The level being set IS the test suite's standard baseline. Even if cleanup "fails," the state is already correct. The `on_exit` is belt-and-suspenders.
+
 ---

 ## 7. Nested `describe` Blocks
@@ -183,6 +476,61 @@ end

 **Source:** `lib/ex_unit/lib/ex_unit/callbacks.ex:423-425` — `no_describe!` check prevents nesting.

+### When to Apply This Rule
+
+**Triggers:**
+- Compile error: "cannot call describe inside another describe"
+- Desire to organize tests hierarchically (coming from RSpec/Jest habits)
+- Test file with many describe blocks that feel like they should be nested
+
+**Example — the smell:**
+```elixir
+describe "API" do
+  describe "v1" do      # Won't compile!
+    describe "users" do  # Won't compile!
+      test "list" do ... end
+    end
+  end
+end
+```
+
+**Example — fixed:**
+```elixir
+describe "API v1 users - list" do
+  test "returns paginated results" do ... end
+  test "filters by role" do ... end
+end
+
+describe "API v1 users - create" do
+  test "validates email" do ... end
+  test "hashes password" do ... end
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- You're using a testing library that extends ExUnit with nested contexts (though this is rare and usually discouraged in Elixir culture)
+
+**Example of acceptable use:**
+```elixir
+# Flat describes with shared setup via module attributes or helper functions
+describe "admin users" do
+  setup [:create_admin]
+
+  test "can delete other users", %{admin: admin} do ... end
+  test "can promote users", %{admin: admin} do ... end
+end
+
+describe "regular users" do
+  setup [:create_user]
+
+  test "cannot delete others", %{user: user} do ... end
+end
+```
+
+**Why it's OK here:** Flat describe blocks with named setup functions achieve the same organization as nesting, while staying within ExUnit's design philosophy.
+
 ---

 ## 8. Using `assert` Where `assert_receive` Belongs
@@ -207,6 +555,55 @@ end

 **Source:** ExUnit provides specialized assertion macros for messages precisely because generic `assert` is inadequate for mailbox testing.

+### When to Apply This Rule
+
+**Triggers:**
+- `Process.info(self(), :messages)` in test code
+- `:erlang.process_info` for mailbox inspection
+- Manual mailbox polling loops in tests
+
+**Example — the smell:**
+```elixir
+test "broadcast reaches subscriber" do
+  PubSub.subscribe(:events)
+  PubSub.broadcast(:events, :hello)
+  Process.sleep(50)
+  {_, messages} = Process.info(self(), :messages)
+  assert Enum.any?(messages, fn msg -> msg == :hello end)
+end
+```
+
+**Example — fixed:**
+```elixir
+test "broadcast reaches subscriber" do
+  PubSub.subscribe(:events)
+  PubSub.broadcast(:events, :hello)
+  assert_receive :hello
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- Testing mailbox ordering (need to inspect all messages at once)
+- Asserting on message count rather than content
+- Building test utilities that need raw mailbox access
+
+**Example of acceptable use:**
+```elixir
+test "exactly 3 events are received" do
+  trigger_events(3)
+  # Wait for all to arrive
+  assert_receive :event, 1000
+  assert_receive :event, 100
+  assert_receive :event, 100
+  # Verify no extras
+  refute_receive :event, 100
+end
+```
+
+**Why it's OK here:** We need to assert both presence AND absence of messages, with ordering guarantees. The sequence of `assert_receive` + `refute_receive` is the idiomatic way to verify "exactly N messages."
+
 ---

 ## 9. Forgetting `Process.flag(:trap_exit, true)` When Testing Linked Processes
@@ -233,6 +630,65 @@ end

 **Source:** `lib/elixir/test/elixir/task_test.exs:297,305,315,330` — Every test that expects a linked process to crash sets `:trap_exit` first.

+### When to Apply This Rule
+
+**Triggers:**
+- Tests using `Task.async` where the task might crash
+- Tests that verify process crash behavior
+- Unexplained test crashes with no assertion failure message
+- `** (EXIT from #PID<...>)` in test output
+
+**Example — the smell:**
+```elixir
+test "supervisor restarts crashed child" do
+  {:ok, sup} = Supervisor.start_link([{Worker, []}], strategy: :one_for_one)
+  [{_, pid, _, _}] = Supervisor.which_children(sup)
+  Process.exit(pid, :kill)
+  # Test might crash here if linked!
+  Process.sleep(100)
+  [{_, new_pid, _, _}] = Supervisor.which_children(sup)
+  assert new_pid != pid
+end
+```
+
+**Example — fixed:**
+```elixir
+test "supervisor restarts crashed child" do
+  Process.flag(:trap_exit, true)
+  {:ok, sup} = Supervisor.start_link([{Worker, []}], strategy: :one_for_one)
+  [{_, pid, _, _}] = Supervisor.which_children(sup)
+  ref = Process.monitor(pid)
+  Process.exit(pid, :kill)
+  assert_receive {:DOWN, ^ref, :process, ^pid, :killed}
+
+  [{_, new_pid, _, _}] = Supervisor.which_children(sup)
+  assert new_pid != pid
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- Using `start_supervised!` (ExUnit's test supervisor handles the linking)
+- Testing that a crash DOES propagate (the test crashing IS the assertion — use `catch_exit` at the call site)
+- The process is started with `start_link` under ExUnit's supervisor
+
+**Example of acceptable use:**
+```elixir
+test "unlinked task doesn't crash caller" do
+  # Task.async_stream with ordered: false doesn't link
+  results = Task.async_stream([1, 2, 3], fn
+    2 -> raise "boom"
+    n -> n * 2
+  end, on_timeout: :kill_task)
+  |> Enum.to_list()
+
+  assert {:exit, _} = Enum.find(results, &match?({:exit, _}, &1))
+end
+```
+
+**Why it's OK here:** `Task.async_stream` handles the linking internally and converts crashes to tagged results. The test process isn't directly linked to the failing task.
+
 ---

 ## 10. Writing Flaky Tests with Timing Assumptions
@@ -266,6 +722,60 @@ end

 **Source:** Elixir's own `ExUnit.configure` allows setting `assert_receive_timeout` globally (default 100ms, CI uses 300ms via env var `ELIXIR_ASSERT_TIMEOUT`).

+### When to Apply This Rule
+
+**Triggers:**
+- `Process.sleep(N)` where N is close to the expected delay (sleep 110ms for a 100ms timer)
+- Tests tagged `@tag :flaky` or skipped in CI
+- Tests with "TODO: increase timeout" comments
+
+**Example — the smell:**
+```elixir
+test "rate limiter allows after window" do
+  RateLimiter.hit(:endpoint)
+  RateLimiter.hit(:endpoint)  # Should be rejected
+  assert RateLimiter.hit(:endpoint) == {:error, :rate_limited}
+
+  Process.sleep(1010)  # Wait for 1s window to expire
+  assert RateLimiter.hit(:endpoint) == :ok
+end
+```
+
+**Example — fixed:**
+```elixir
+test "rate limiter allows after window" do
+  RateLimiter.hit(:endpoint)
+  RateLimiter.hit(:endpoint)
+  assert RateLimiter.hit(:endpoint) == {:error, :rate_limited}
+
+  # Use the rate limiter's own notification mechanism
+  assert_receive {:window_reset, :endpoint}, 5000
+  assert RateLimiter.hit(:endpoint) == :ok
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- Testing actual wall-clock behavior with very generous margins (10x the expected time)
+- Performance benchmarks where timing IS the measurement
+- The system under test has no notification mechanism and can't be modified
+
+**Example of acceptable use:**
+```elixir
+test "connection timeout fires within expected range" do
+  {time_us, {:error, :timeout}} = :timer.tc(fn ->
+    HttpClient.get("http://10.255.255.1", timeout: 1000)
+  end)
+
+  # Generous bounds: should be 1000ms, accept 800-3000ms
+  assert time_us > 800_000
+  assert time_us < 3_000_000
+end
+```
+
+**Why it's OK here:** The timing IS the assertion — we're verifying the timeout mechanism works correctly. The bounds are generous enough to handle system load without being so wide as to be meaningless.
+
 ---

 ## 11. Not Using `=~` for Regex/Partial Matching
@@ -292,6 +802,47 @@ end

 **Source:** `lib/elixir/test/elixir/gen_server_test.exs:70-82` uses `~r"expected :name option to be one of the following:"` in `assert_raise` — testing the stable part, ignoring the dynamic rest.

+### When to Apply This Rule
+
+**Triggers:**
+- `assert msg == "..."` where the string contains dynamic parts (PIDs, timestamps, paths)
+- Tests that break after minor wording changes in error messages
+- Assertions on formatted output from Logger or IO
+
+**Example — the smell:**
+```elixir
+test "reports compile error" do
+  assert_raise CompileError, "nofile:1: undefined function foo/0 (there is no such import)", fn ->
+    Code.compile_string("foo()")
+  end
+end
+```
+
+**Example — fixed:**
+```elixir
+test "reports compile error" do
+  assert_raise CompileError, ~r/undefined function foo\/0/, fn ->
+    Code.compile_string("foo()")
+  end
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- The exact output IS the contract (e.g., a formatter that must produce deterministic output)
+- Testing serialization where byte-exact output matters
+- The string is fully under your control with no dynamic parts
+
+**Example of acceptable use:**
+```elixir
+test "JSON encoder produces exact output" do
+  assert Jason.encode!(%{a: 1, b: 2}) == ~s({"a":1,"b":2})
+end
+```
+
+**Why it's OK here:** The JSON encoder's exact output format IS the contract. Users depend on the precise serialization. A partial match would miss regressions in formatting.
+
 ---

 ## 12. Relying on Process.alive? Without Synchronization
@@ -317,6 +868,49 @@ end

 **Source:** `lib/elixir/test/elixir/supervisor_test.exs:278-285` — `assert_kill` helper always uses monitor + assert_receive, never `Process.alive?` polling.

+### When to Apply This Rule
+
+**Triggers:**
+- `Process.alive?/1` in test assertions
+- `refute Process.alive?(pid)` after killing/stopping a process
+- Polling loops checking if a process has died
+
+**Example — the smell:**
+```elixir
+test "worker shuts down gracefully" do
+  pid = start_supervised!(Worker)
+  Worker.shutdown(pid)
+  Process.sleep(50)
+  refute Process.alive?(pid)
+end
+```
+
+**Example — fixed:**
+```elixir
+test "worker shuts down gracefully" do
+  pid = start_supervised!(Worker)
+  ref = Process.monitor(pid)
+  Worker.shutdown(pid)
+  assert_receive {:DOWN, ^ref, :process, ^pid, :normal}, 5000
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- Checking that a process IS alive (existence check, not death check) — no race condition there
+- In production code (not tests) where you need a non-blocking liveness check and can handle the race
+
+**Example of acceptable use:**
+```elixir
+test "start_link creates a running process" do
+  {:ok, pid} = MyServer.start_link([])
+  assert Process.alive?(pid)  # Just started — guaranteed alive
+end
+```
+
+**Why it's OK here:** We just created the process synchronously. It's guaranteed to be alive. There's no race condition when checking for liveness immediately after creation.
+
 ---

 ## 13. Using `== ""` for Empty Capture Assertions in Async Tests
@@ -341,6 +935,55 @@ end

 **Source:** `lib/ex_unit/lib/ex_unit/capture_io.ex` docs: "avoid empty captures on `:stderr` with async tests"

+### When to Apply This Rule
+
+**Triggers:**
+- `capture_io(:stderr, ...)` combined with `== ""` in async tests
+- Flaky assertion failures showing unexpected stderr content
+- Tests that pass alone but fail in the full async suite
+
+**Example — the smell:**
+```elixir
+use ExUnit.Case, async: true
+
+test "no warnings on valid input" do
+  assert capture_io(:stderr, fn -> MyApp.process("valid") end) == ""
+end
+```
+
+**Example — fixed:**
+```elixir
+use ExUnit.Case, async: true
+
+test "no warnings on valid input" do
+  # Option 1: Use capture_log instead (isolated per process)
+  assert capture_log(fn -> MyApp.process("valid") end) == ""
+
+  # Option 2: Use :stdio which is per-process
+  assert capture_io(fn -> MyApp.process("valid") end) == ""
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- The test uses `async: false` (no concurrent interference)
+- Capturing `:stdio` (default) which uses the per-process group leader
+- The function being tested explicitly writes to a named IO device you control
+
+**Example of acceptable use:**
+```elixir
+use ExUnit.Case, async: false
+
+test "no stderr output in production mode" do
+  Application.put_env(:my_app, :env, :prod)
+  on_exit(fn -> Application.put_env(:my_app, :env, :test) end)
+  assert capture_io(:stderr, fn -> MyApp.start() end) == ""
+end
+```
+
+**Why it's OK here:** `async: false` means no other test is running concurrently. The stderr capture is isolated by test scheduling, not by the IO mechanism.
+
 ---

 ## 14. Overriding ExUnit Reserved Tags
@@ -359,6 +1002,56 @@ end

 **Source:** `lib/ex_unit/lib/ex_unit/callbacks.ex` — ExUnit raises if you try to set reserved keys to different values in setup.

+### When to Apply This Rule
+
+**Triggers:**
+- Runtime error: "ExUnit reserved field ... was set to a different value"
+- Tags named `:test`, `:case`, `:file`, `:line`, `:async`, `:registered`, `:describe`
+- Mysterious test failures after adding tags
+
+**Example — the smell:**
+```elixir
+@tag async: false          # Doesn't actually change async behavior!
+@tag file: "custom.exs"   # Breaks file reporting
+@tag describe: "my group"  # Conflicts with describe blocks
+
+test "my test" do
+  # ...
+end
+```
+
+**Example — fixed:**
+```elixir
+# Use the actual ExUnit mechanisms:
+use ExUnit.Case, async: false  # This is how you control async
+
+# For custom categorization, use non-reserved names:
+@tag category: :integration
+@tag speed: :slow
+@tag feature: "auth"
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- You're writing ExUnit extensions or custom formatters that intentionally read/write these fields (rare, advanced use)
+
+**Example of acceptable use:**
+```elixir
+# Custom ExUnit formatter that adds metadata
+defmodule MyFormatter do
+  use GenServer
+
+  def handle_cast({:test_finished, %{tags: tags}}, state) do
+    # Reading reserved tags in a formatter is fine
+    IO.puts("#{tags.file}:#{tags.line} - #{tags.test}")
+    {:noreply, state}
+  end
+end
+```
+
+**Why it's OK here:** The formatter is reading reserved tags (their intended purpose), not overriding them. ExUnit populates these fields for formatters and reporters to consume.
+
 ---

 ## 15. Complex Conditional Logic in Tests
@@ -407,3 +1100,61 @@ end
 ```

 **Source:** ExUnit case.ex docs: "If you use parameterized tests and then find yourself adding conditionals in your tests to deal with different parameters, then parameterized tests may be the wrong solution."
+
+### When to Apply This Rule
+
+**Triggers:**
+- `if`/`case`/`cond` inside test bodies
+- `for` loops with assertions inside (unless trivially mapping input→output)
+- Tests that assert different things based on runtime values
+
+**Example — the smell:**
+```elixir
+test "validates all field types" do
+  for {field, value, expected_error} <- [
+    {:email, "bad", "invalid email"},
+    {:age, -1, "must be positive"},
+    {:name, "", "can't be blank"}
+  ] do
+    changeset = User.changeset(%User{}, %{field => value})
+    if expected_error do
+      assert errors_on(changeset)[field] == [expected_error]
+    else
+      assert changeset.valid?
+    end
+  end
+end
+```
+
+**Example — fixed:**
+```elixir
+# Elixir 1.18+ parameterize
+use ExUnit.Case, parameterize: [
+  %{field: :email, value: "bad", error: "invalid email"},
+  %{field: :age, value: -1, error: "must be positive"},
+  %{field: :name, value: "", error: "can't be blank"}
+]
+
+test "validates #{inspect(field)}", %{field: field, value: value, error: error} do
+  changeset = User.changeset(%User{}, %{field => value})
+  assert errors_on(changeset)[field] == [error]
+end
+```
+
+### Exceptions (When This Rule Doesn't Apply)
+
+**It's OK when:**
+- Testing a pure function over many inputs where the mapping is trivial and the loop is just convenience
+- Property-based tests (StreamData) that generate inputs — conditionals in generators are fine
+- The loop tests identical behavior, not different behaviors
+
+**Example of acceptable use:**
+```elixir
+test "all ASCII digits parse to integers" do
+  for char <- ?0..?9 do
+    assert Integer.parse(<<char>>) == {char - ?0, ""}
+  end
+end
+```
+
+**Why it's OK here:** There's no conditional logic — every iteration tests the exact same behavior with a trivially predictable result. If one fails, the assertion message includes the specific value. The loop is purely for conciseness.