核心測試一切協議 (KTAP), 版本 1¶

TAP，或測試一切協議，是一種用於指定許多專案使用的測試結果的格式。它的網站和規範可以在此連結中找到。Linux 核心主要使用 TAP 輸出作為測試結果。但是，核心測試框架對測試結果有特殊需求，這與原始 TAP 規範不一致。因此，指定了“核心 TAP”(KTAP) 格式來擴充套件和更改 TAP 以支援這些用例。本規範描述了 KTAP 在核心中當前使用的普遍接受的格式。

KTAP 測試結果描述了一系列測試（可以是巢狀的：即，測試可以有子測試），每個測試都可以包含診斷資料（例如，日誌行）和最終結果。測試結構和結果是機器可讀的，而診斷資料是非結構化的，旨在幫助人工除錯。

KTAP 輸出由四種不同型別的行構建： - 版本行 - 計劃行 - 測試用例結果行 - 診斷行

一般來說，有效的 KTAP 輸出也應該形成有效的 TAP 輸出，但一些資訊，特別是巢狀的測試結果，可能會丟失。另請注意，TAP14 有一個停滯不前的草案規範，KTAP 在幾個地方與此不同（特別是“子測試”標題），這些將在本文件後面的相關位置進行描述。

版本行¶

所有 KTAP 格式的結果都以“版本行”開頭，該行指定結果符合哪個版本的 (K)TAP 標準。

例如： - “KTAP version 1” - “TAP version 13” - “TAP version 14”

請注意，在 KTAP 中，子測試也以版本行開頭，表示巢狀測試結果的開始。這與 TAP14 不同，後者使用單獨的“子測試”行。

雖然，展望未來，符合要求的測試應該使用“KTAP version 1”，但預計大多數解析器和其他工具將接受此處列出的其他版本，以便與現有測試和框架相容。

計劃行¶

測試計劃提供了 KTAP 輸出中的測試（或子測試）數量。

計劃行必須遵循“1..N”的格式，其中 N 是測試或子測試的數量。計劃行在版本行之後，指示巢狀測試的數量。

雖然在某些情況下測試數量是事先未知的（在這種情況下，可以省略測試計劃），但強烈建議在可能的情況下存在一個。

測試用例結果行¶

測試用例結果行指示測試的最終狀態。它們是必需的，並且必須具有以下格式

<result> <number> [<description>][ # [<directive>] [<diagnostic data>]]

結果可以是“ok”，表示測試用例透過，也可以是“not ok”，表示測試用例失敗。

<number> 表示正在執行的測試的編號。第一個測試必須具有編號 1，然後對於同一測試中相同巢狀級別的每個附加子測試，編號必須增加 1。

描述是對測試的描述，通常是測試的名稱，可以是除 # 或換行符之外的任何字串。描述是可選的，但建議使用。

指令和任何診斷資料是可選的。如果存在任何一個，它們必須遵循井號“#”。

指令是一個關鍵字，指示測試的結果與透過和失敗不同。指令是可選的，由診斷資料之前的單個關鍵字組成。如果解析器遇到它不支援的指令，它應該回退到“ok”/“not ok”結果。

當前接受的指令是

“SKIP”，表示測試已跳過（請注意，如果使用 SKIP 指令，測試用例結果行的結果可以是“ok”或“not ok”）
“TODO”，表示當前不希望測試透過，例如，因為它正在測試的功能已知已損壞。雖然此指令是從 TAP 繼承的，但不鼓勵在核心中使用它。
“XFAIL”，表示預期測試會失敗。這與上面的“TODO”類似，並被一些 kselftest 測試使用。
“TIMEOUT”，表示測試已超時（請注意，如果使用 TIMEOUT 指令，測試用例結果行應為“not ok”）
“ERROR”，表示測試的執行由於診斷資料中包含的特定錯誤而失敗。（請注意，如果使用 ERROR 指令，測試用例結果行應為“not ok”）

診斷資料是一個純文字欄位，其中包含有關為什麼產生此結果的任何其他詳細資訊。這通常是 ERROR 或失敗測試的錯誤訊息，或者是 SKIP 結果缺少依賴項的描述。

診斷資料欄位是可選的，並且沒有指令或任何診斷資料的結果不需要包含“#”欄位分隔符。

示例結果行包括

ok 1 test_case_name

測試“test_case_name”透過。

not ok 1 test_case_name

測試“test_case_name”失敗。

ok 1 test # SKIP necessary dependency unavailable

測試“test”已跳過，診斷訊息為“必要的依賴項不可用”。

not ok 1 test # TIMEOUT 30 seconds

測試“test”超時，診斷資料為“30 seconds”。

ok 5 check return code # rcode=0

測試“check return code”透過，附加診斷資料為“rcode=0”

診斷行¶

如果測試希望輸出任何其他資訊，他們應該使用“診斷行”來完成。診斷行是可選的、自由格式的文字，通常用於比最終結果和診斷資料行提供的更詳細地描述正在測試的內容和任何中間結果。

診斷行的格式為“# <diagnostic_description>”，其中描述可以是任何字串。診斷行可以位於測試輸出中的任何位置。通常，關於測試的診斷行直接位於該測試的測試結果行之前。

請注意，大多數工具會將未知行（見下文）視為診斷行，即使它們不是以“#”開頭：這是為了捕獲任何其他有用的核心輸出，這可能有助於除錯測試。儘管如此，建議測試始終為其擁有的任何診斷輸出新增“#”字元作為字首。

未知行¶

KTAP 輸出中可能存在不遵循上述四種行格式之一的行。這是允許的，但是，它們不會影響測試的狀態。

這是 TAP 的一個重要區別。核心測試可能會將訊息列印到系統控制檯或日誌檔案中。這兩個目標可能包含來自不相關的核心或使用者空間活動的訊息，或者來自測試呼叫的非測試程式碼的核心訊息。測試呼叫的核心程式碼可能不知道測試正在進行中，因此無法將訊息列印為診斷訊息。

巢狀測試¶

在 KTAP 中，測試可以巢狀。這是透過讓測試在其輸出中包含一整套 KTAP 格式的結果來完成的。這可以用於對相關測試進行分類和分組，或者從同一測試中分離出不同的結果。

“父”測試的結果應包含其所有子測試的結果，從另一個 KTAP 版本行和測試計劃開始，並以整體結果結束。例如，如果其中一個子測試失敗，則父測試也應失敗。

此外，子測試中的所有行都應縮排。一個級別的縮排是兩個空格：“ ”。縮排應從版本行開始，並應在父測試的結果行之前結束。

“未知行”不被認為是子測試中的行，因此允許縮排或不縮排。

具有兩個巢狀子測試的測試示例

KTAP version 1
1..1
  KTAP version 1
  1..2
  ok 1 test_1
  not ok 2 test_2
# example failed
not ok 1 example

具有多層巢狀測試的示例格式

KTAP version 1
1..2
  KTAP version 1
  1..2
    KTAP version 1
    1..2
    not ok 1 test_1
    ok 2 test_2
  not ok 1 test_3
  ok 2 test_4 # SKIP
not ok 1 example_test_1
ok 2 example_test_2

TAP 和 KTAP 之間的主要區別¶

特徵	TAP	KTAP
診斷訊息中的 yaml 和 json	可以	不推薦
TODO 指令	可以	無法識別
允許巢狀任意數量的測試	否	是
“未知行”屬於“其他任何內容”類別	是	否
“未知行”是	不正確	允許

TAP14 規範允許巢狀測試，但不是使用另一個巢狀版本行，而是使用“Subtest: <name>”形式的行，其中 <name> 是父測試的名稱。

KTAP 輸出示例¶

KTAP version 1
1..1
  KTAP version 1
  1..3
    KTAP version 1
    1..1
    # test_1: initializing test_1
    ok 1 test_1
  ok 1 example_test_1
    KTAP version 1
    1..2
    ok 1 test_1 # SKIP test_1 skipped
    ok 2 test_2
  ok 2 example_test_2
    KTAP version 1
    1..3
    ok 1 test_1
    # test_2: FAIL
    not ok 2 test_2
    ok 3 test_3 # SKIP test_3 skipped
  not ok 3 example_test_3
not ok 1 main_test

此輸出定義了以下層次結構

一個名為“main_test”的單個測試，它失敗，並且有三個子測試： - “example_test_1”，它透過，並且有一個子測試

“test_1”，它透過，並輸出診斷訊息“test_1: initializing test_1”

“example_test_2”，它透過，並且有兩個子測試
- “test_1”，它被跳過，解釋為“test_1 skipped”
- “test_2”，它透過
“example_test_3”，它失敗，並且有三個子測試
- “test_1”，它透過
- “test_2”，它輸出診斷行“test_2: FAIL”，並且失敗。
- “test_3”，它被跳過，解釋為“test_3 skipped”

請注意，具有相同名稱的單個子測試不會衝突，因為它們位於不同的父測試中。此輸出還展示了一些用於“冒泡”測試結果的明智規則：如果任何子測試失敗，則測試失敗。跳過的測試不影響父測試的結果（儘管如果_所有_子測試都已跳過，則將測試標記為跳過通常是有意義的）。

參見:¶

TAP 規範：https://testanything.org/tap-version-13-specification.html
（停滯不前的）TAP 版本 14 規範：https://github.com/TestAnything/Specification/blob/tap-14-specification/specification.md
kselftest 文件：Linux 核心自測試
KUnit 文件：KUnit - Linux 核心單元測試

Linux 核心

目錄

本頁