Jump.CredoChecks.AssertReceiveTimeout (Jump.CredoChecks v0.7.1)

View Source

Basics

This check is disabled by default.

Learn how to enable it via .credo.exs.

This check has a base priority of normal and works with any version of Elixir.

Explanation

Tests should rely on the default :ex_unit :assert_receive_timeout rather than specifying their own. Custom timeouts inflate suite duration when the message never arrives and tend to drift higher over time as people paper over flaky tests.

# ❌ Bad — explicit timeout
assert_receive :foo, 1_000

# ✅ Good — rely on the configured default
assert_receive :foo

If you want to be able to specify a longer timeout than default, configure this check with a min_assert_receive_timeout to enforce a floor; any timeout at or above the minimum will be allowed, and omitting the timeout entirely (falling back to ExUnit's default) is always allowed.

A timeout held in a module attribute counts, as long as the attribute is assigned exactly once in the same module and holds an integer literal:

# ✅ Good — @timeout resolves to 5_000
defmodule MyTest do
  @timeout 5_000

  test "sms arrives" do
    assert_receive {:sms, _}, @timeout
  end
end

Any other timeout — a variable, a function call, or an attribute that is never assigned, assigned more than once, or holds something other than an integer literal — cannot be verified statically, so it is flagged.

Additionally, you can configure max_refute_receive_timeout to cap how long a refute_receive is allowed to block. Because refute_receive always waits its full timeout (including ExUnit's default when none is specified), the timeout sets a minimum bound on how long the test takes to run. When this param is set, every refute_receive must specify an explicit timeout the check can verify is at or below the configured maximum — bare refute_receive calls are flagged too, since they fall back to a default that also blocks the test.

The same cap applies to PhoenixTest.refute_has/3 when it is given an explicit :timeout option. Unlike refute_receive, PhoenixTest defaults timeout to 0 (no wait), so a refute_has with no timeout is allowed. A positive timeout, though, waits for async LiveView operations and therefore also sets a minimum bound on the test's runtime:

# ❌ Bad — waits up to 10s to confirm the text is absent
session
|> visit(~p"/")
|> refute_has("Negative text", timeout: 10_000)

# ✅ Good — omit timeout (defaults to 0) or keep it at or below the max
session
|> visit(~p"/")
|> refute_has("Negative text")

Check-Specific Parameters

Use the following parameters to configure this check:

:min_assert_receive_timeout

If set, allows explicit assert_receive timeouts that are an integer literal greater than or equal to this value (a module attribute assigned exactly once to an integer literal counts too). Defaults to nil (no explicit timeout allowed). As with the built-in timeout type, units are milliseconds.

This parameter defaults to nil.

:max_refute_receive_timeout

If set, flags refute_receive calls whose timeout is an integer literal greater than this value, whose timeout cannot be statically verified, or which omit an explicit timeout entirely. The same cap is applied to PhoenixTest refute_has calls that pass an explicit timeout: option (omitting it is allowed, since PhoenixTest defaults to 0). A module attribute assigned exactly once to an integer literal is verified like a literal. Defaults to nil (no refute_receive/refute_has timeout is flagged). As with the built-in timeout type, units are milliseconds.

This parameter defaults to nil.

General Parameters

Like with all checks, general params can be applied.

Parameters can be configured via the .credo.exs config file.