查看源代码 ExUnit (ExUnit v1.16.2)

Elixir 的单元测试框架。

示例

下面展示了 ExUnit 的基本设置

# File: assertion_test.exs

# 1) Start ExUnit.
ExUnit.start()

# 2) Create a new test module (test case) and use "ExUnit.Case".
defmodule AssertionTest do
  # 3) Note that we pass "async: true", this runs the test case
  #    concurrently with other test cases. The individual tests
  #    within each test case are still run serially.
  use ExUnit.Case, async: true

  # 4) Use the "test" macro instead of "def" for clarity.
  test "the truth" do
    assert true
  end
end

要运行上面的测试，请使用命令行中的 elixir 运行该文件。假设您将文件命名为 assertion_test.exs，您可以运行它为

$ elixir assertion_test.exs

Case、回调和断言

有关定义测试用例和设置回调的更多信息，请参见 ExUnit.Case 和 ExUnit.Callbacks。

ExUnit.Assertions 模块包含一组宏，用于生成带有适当错误消息的断言。

与 Mix 集成

Mix 是 Elixir 的项目管理和构建工具。从命令行调用 mix test 将运行项目 test 目录中与模式 *_test.exs 匹配的每个文件中的测试。

您必须在 test 目录中创建一个 test_helper.exs 文件，并将所有测试的通用代码放在那里。

test_helper.exs 文件的最小示例将是

# test/test_helper.exs
ExUnit.start()

Mix 将在执行测试之前加载 test_helper.exs 文件。在您的测试文件中，没有必要 require test_helper.exs 文件。运行 mix help test 以获取更多信息。

摘要

类型

failed()

由 ExUnit.Test 和 ExUnit.TestModule 返回的错误状态

state()

所有测试都从 nil 的状态开始。

suite_result()

表示运行测试套件结果的映射

test_id()

函数

after_suite(function)

设置在测试套件完成之后执行的回调。

async_run()

异步启动测试，而测试用例仍在加载中。

await_run(task)

等待使用 async_run/0 启动的测试套件。

configuration()

返回 ExUnit 配置。

configure(options)

配置 ExUnit。

fetch_test_supervisor()

获取当前测试的测试主管。

plural_rule(word)

返回 word 的复数形式。

plural_rule(word, pluralization)

为 word 注册一个 pluralization。

run(additional_modules \\ [])

运行测试。如果 ExUnit 通过 start/1 启动，则会自动调用它。

start(options \\ [])

启动 ExUnit，并在 VM 终止之前自动运行测试。

类型

failed()

@type failed() :: [{Exception.kind(), reason :: term(), Exception.stacktrace()}]

由 ExUnit.Test 和 ExUnit.TestModule 返回的错误状态

state()

@type state() ::
  nil
  | {:excluded, binary()}
  | {:failed, failed()}
  | {:invalid, module()}
  | {:skipped, binary()}

所有测试都从 nil 的状态开始。

完成的测试可以处于五种状态之一

通过（也由 nil 表示）
失败
跳过（通过 @tag :skip）
排除（通过 :exclude 过滤器）
无效（当 setup_all 失败时）

suite_result()

@type suite_result() :: %{
  excluded: non_neg_integer(),
  failures: non_neg_integer(),
  skipped: non_neg_integer(),
  total: non_neg_integer()
}

表示运行测试套件结果的映射

test_id()

@type test_id() :: {module(), name :: atom()}

函数

after_suite(function)

(自 1.8.0 起)

@spec after_suite((suite_result() -> any())) :: :ok

设置在测试套件完成之后执行的回调。

使用 after_suite/1 设置的回调必须接受一个参数，该参数是一个包含测试套件执行结果的映射。

如果 after_suite/1 被多次调用，则回调将以相反的顺序调用。换句话说，最后一个设置的回调将是第一个被调用的回调。

async_run()

(自 1.12.0 起)

@spec async_run() :: Task.t()

异步启动测试，而测试用例仍在加载中。

它返回一个任务，该任务必须在需要结果时传递给 await_run/0。

await_run(task)

(自 1.12.0 起)

@spec await_run(Task.t()) :: suite_result()

等待使用 async_run/0 启动的测试套件。

configuration()

@spec configuration() :: Keyword.t()

返回 ExUnit 配置。

有关可用的配置选项，请参见 configure/1。

configure(options)

@spec configure(Keyword.t()) :: :ok

配置 ExUnit。

选项

ExUnit 支持以下选项

:assert_receive_timeout - assert_receive 调用中使用的超时时间（以毫秒为单位），默认值为 100；
:autorun - ExUnit 是否应在退出时默认运行。默认为 true；
:capture_log - ExUnit 是否应默认跟踪日志消息并在测试失败时打印它们。可以通过 @tag capture_log: false 为单个测试覆盖它。这也可以配置为使用特定级别的 capture_log: [level: LEVEL]，例如：capture_log: [level: :emergency] 以防止测试失败时出现任何输出。默认为 false；
:colors - 一组关键字列表，表示某些格式化程序将使用的颜色选项
- :enabled - 启用颜色的布尔值选项，默认为 IO.ANSI.enabled?/0；
- :success - 成功消息（默认为 :green）
- :invalid - 无效测试消息（默认为 :yellow）
- :skipped - 跳过测试消息（默认为 :yellow）
- :failure - 失败测试消息（默认为 :red）
- :error_info - 实际错误的显示（默认为 :red）
- :extra_info - 附加信息（默认为 :cyan）
- :location_info - 文件名和标签（默认为 [:bright, :black]）
- :diff_insert - diff 中插入的颜色，默认为 :green；
- :diff_insert_whitespace - diff 中空格插入的颜色，默认为 IO.ANSI.color_background(2, 0, 0)；
- :diff_delete - diff 中删除的颜色，默认为 :red；
- :diff_delete_whitespace - diff 中空格删除的颜色，默认为 IO.ANSI.color_background(0, 2, 0)；
:exclude - 指定通过跳过与过滤器匹配的测试来运行哪些测试。有关 ExUnit.Case 的文档中的“过滤器”部分，请参见；
:exit_status - 指定测试套件失败时使用的备用退出状态。默认为 2；
:failures_manifest_file - 指定用于存储运行之间失败的文件的路径；
:formatters - 将打印结果的格式化程序，默认为 [ExUnit.CLIFormatter]；
:include - 指定通过跳过不匹配过滤器的测试来运行哪些测试。请记住，默认情况下所有测试都包含在内，因此除非首先排除它们，否则 :include 选项将不起作用。要仅运行与 :include 过滤器匹配的测试，请首先排除 :test 标签（有关标签和过滤器的更多信息，请参见 ExUnit.Case 的文档）；
:max_cases - 并行运行的测试数量上限。只有来自不同模块的测试才能并行运行。它默认为 System.schedulers_online * 2 以优化 CPU 密集型和 I/O 密集型测试；
:max_failures - 当测试失败达到此数量时，套件将停止评估测试。使用 setup_all/1,2 回调时失败的模块内的所有测试都被计为失败。默认为 :infinity；
:only_test_ids - 一个 {module_name, test_name} 元组列表，它限制了哪些测试被运行。这通常由 Mix 用于过滤哪些测试应该运行；
:rand_algorithm - 生成测试种子时使用的算法。可在 Erlang 的 :rand 文档中找到可用算法（参见 :rand.builting_arg/0）。自 v1.16.0 起可用。在 v1.16.0 之前，算法被硬编码为 :exs1024。在 Elixir v1.16.0 及之后，默认值更改为 :exsss；
:refute_receive_timeout - refute_receive 调用中使用的超时时间（以毫秒为单位），默认值为 100；
:seed - 一个整数值种子，用于随机化测试套件。此种子还与测试模块和名称混合以在每次测试时创建一个新的唯一种子，该种子会自动馈送到 :rand 模块中。这在测试之间提供了随机性，但提供了可预测且可重复的结果。:seed 为 0 将禁用随机化，并且每个文件中的测试将始终按它们定义的顺序运行；
:slowest - 打印 N 个最慢测试的计时信息。使用慢速测试报告运行 ExUnit 会自动以 trace 模式运行。默认情况下它被禁用；
:stacktrace_depth - 配置用于格式化和报告程序的堆栈跟踪深度，默认为 20；
:timeout - 设置测试的超时时间（以毫秒为单位），默认为 60_000；
:trace - 将 ExUnit 设置为跟踪模式，这将 :max_cases 设置为 1 并打印每个测试用例和测试，同时运行。请注意，在跟踪模式下，测试超时将被忽略，因为超时被设置为 :infinity；
:test_location_relative_path - 测试位置是测试打印的文件：行信息，作为运行给定测试的快捷方式。当此值被设置时，该值被用作测试本身的前缀。这通常由 Mix 用于正确设置伞形项目；

任何任意配置也可以传递给 configure/1 或 start/1，并且这些选项随后可以在自定义格式化程序等地方使用。ExUnit 本身将忽略这些其他选项。

fetch_test_supervisor()

(自 1.11.0 起)

@spec fetch_test_supervisor() :: {:ok, pid()} | :error

获取当前测试的测试主管。

如果不在测试进程中调用，则返回 {:ok, supervisor_pid} 或 :error。

此监督器与 ExUnit.Callbacks.start_supervised/2 中使用的相同，详情请参阅 ExUnit.Callbacks 模块文档。

plural_rule(word)

@spec plural_rule(binary()) :: binary()

返回 word 的复数形式。

如果未注册，则返回该词加上“s”。

plural_rule(word, pluralization)

@spec plural_rule(binary(), binary()) :: :ok

为 word 注册一个 pluralization。

如果已注册，则替换。

run(additional_modules \\ [])

@spec run([module()]) :: suite_result()

运行测试。如果 ExUnit 通过 start/1 启动，则会自动调用它。

从 Elixir v1.14 开始，它接受一个可选的模块列表，作为套件的一部分运行。这通常用于重新运行已加载到内存中的模块。

返回一个包含测试总数、失败数、排除测试数和跳过测试数的映射。

start(options \\ [])

@spec start(Keyword.t()) :: :ok

启动 ExUnit，并在 VM 终止之前自动运行测试。

它接受一组 options 来配置 ExUnit（与 configure/1 接受的选项相同）。

如果您想手动运行测试，可以将 :autorun 选项设置为 false，并使用 run/0 运行测试。