檢視原始碼 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

案例、回呼和斷言

請參閱 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 繫結和 IO 繫結測試；
: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 終止前自動執行測試。

它接受一組 選項 來設定 ExUnit（與 configure/1 接受的選項相同）。

如果您想要手動執行測試，您可以將 :autorun 選項設定為 false，並使用 run/0 來執行測試。