ctest_test¶

以儀表板客戶端執行CTest 測試步驟。

ctest_test([BUILD <build-dir>] [APPEND]
           [START <start-number>]
           [END <end-number>]
           [STRIDE <stride-number>]
           [EXCLUDE <exclude-regex>]
           [INCLUDE <include-regex>]
           [EXCLUDE_LABEL <label-exclude-regex>]
           [INCLUDE_LABEL <label-include-regex>]
           [EXCLUDE_FROM_FILE <filename>]
           [INCLUDE_FROM_FILE <filename>]
           [EXCLUDE_FIXTURE <regex>]
           [EXCLUDE_FIXTURE_SETUP <regex>]
           [EXCLUDE_FIXTURE_CLEANUP <regex>]
           [PARALLEL_LEVEL [<level>]]
           [RESOURCE_SPEC_FILE <file>]
           [TEST_LOAD <threshold>]
           [SCHEDULE_RANDOM <ON|OFF>]
           [STOP_ON_FAILURE]
           [STOP_TIME <time-of-day>]
           [RETURN_VALUE <result-var>]
           [CAPTURE_CMAKE_ERROR <result-var>]
           [REPEAT <mode>:<n>]
           [OUTPUT_JUNIT <file>]
           [QUIET]
           )

在專案建置樹狀目錄中執行測試，並將結果儲存在 Test.xml 中，以供使用 ctest_submit() 命令提交。

選項如下：

BUILD <建置目錄>

指定最上層建置目錄。如果未指定，則會使用 CTEST_BINARY_DIRECTORY 變數。

APPEND

標記 Test.xml，以便附加到上次呼叫 ctest_start() 以來，先前提交到儀表板伺服器的結果。附加語義由使用的儀表板伺服器定義。這並不會導致結果附加到先前呼叫此命令產生的 .xml 檔案中。

START <起始編號>

指定測試編號範圍的開頭。

END <結束編號>

指定測試編號範圍的結尾。

STRIDE <間隔編號>

指定跨測試編號範圍的間隔。

EXCLUDE <排除正規表示式>

指定符合要排除的測試名稱的正規表示式。

INCLUDE <包含正規表示式>

指定符合要包含的測試名稱的正規表示式。不符合此表示式的測試將會被排除。

EXCLUDE_LABEL <標籤排除正規表示式>

指定符合要排除的測試標籤的正規表示式。

INCLUDE_LABEL <標籤包含正規表示式>

指定符合要包含的測試標籤的正規表示式。不符合此表示式的測試將會被排除。

EXCLUDE_FROM_FILE <檔案名稱>

在 3.29 版本中新增。

不要執行指定檔案中列出其確切名稱的測試。

INCLUDE_FROM_FILE <檔案名稱>

在 3.29 版本中新增。

只執行指定檔案中列出其確切名稱的測試。

EXCLUDE_FIXTURE <正規表示式>

在 3.7 版本中新增。

如果待執行的測試集合中的測試需要特定的夾具，則該夾具的設定和清理測試通常會自動新增到測試集合中。此選項會防止為符合 <正規表示式> 的夾具新增設定或清理測試。請注意，所有其他夾具行為都會保留，包括測試相依性和跳過具有失敗夾具設定測試的測試。

EXCLUDE_FIXTURE_SETUP <正規表示式>

在 3.7 版本中新增。

與 EXCLUDE_FIXTURE 相同，只是僅排除符合的設定測試。

EXCLUDE_FIXTURE_CLEANUP <正規表示式>

在 3.7 版本中新增。

與 EXCLUDE_FIXTURE 相同，只是僅排除符合的清理測試。

PARALLEL_LEVEL [<層級>]

平行執行測試，限制為給定的平行處理層級。

在 3.29 版本中新增: 可以省略 <層級> 或 0，以讓 ctest 使用預設的平行處理層級，或不限制的平行處理，如 ctest --parallel 選項的文件所述。

RESOURCE_SPEC_FILE <檔案>

在 3.16 版本中新增。

指定資源規格檔案。如需詳細資訊，請參閱資源配置。

TEST_LOAD <臨界值>

在 3.4 版本中新增。

平行執行測試時，嘗試不要在 CPU 負載可能超過給定臨界值時啟動測試。如果未指定，則會檢查 CTEST_TEST_LOAD 變數，然後檢查 ctest(1) 的 --test-load 命令列引數。另請參閱CTest 測試步驟中的 TestLoad 設定。

REPEAT <模式>:<次數>

在 3.17 版本中新增。

根據給定的 <模式> 重複執行測試，最多 <次數> 次。模式如下：

UNTIL_FAIL: 要求每個測試執行 <次數> 次而沒有失敗才能通過。這有助於找出測試案例中的零星失敗。
UNTIL_PASS: 允許每個測試執行最多 <次數> 次才能通過。如果測試因任何原因失敗，則會重複測試。這有助於容忍測試案例中的零星失敗。
AFTER_TIMEOUT: 允許每個測試執行最多 <次數> 次才能通過。僅在測試逾時時重複測試。這有助於容忍繁忙機器上測試案例中的零星逾時。

SCHEDULE_RANDOM <ON|OFF>

以隨機順序啟動測試。這有助於偵測隱含的測試相依性。

STOP_ON_FAILURE

在 3.18 版本中新增。

一旦有測試失敗，就停止執行測試。

STOP_TIME <一天中的時間>

指定測試應停止執行的時間。

RETURN_VALUE <結果變數>

如果所有測試都通過，則在 <結果變數> 變數中儲存 0。如果發生任何錯誤，則儲存非零值。

CAPTURE_CMAKE_ERROR <結果變數>

在 3.7 版本中新增。

如果執行命令時發生任何錯誤，則在 <結果變數> 變數中儲存 -1，並防止 ctest 在發生錯誤時傳回非零值。

OUTPUT_JUNIT <檔案>

在 3.21 版本中新增。

以 JUnit XML 格式將測試結果寫入 <檔案>。如果 <檔案> 是相對路徑，則會將其放置在建置目錄中。如果 <檔案> 已經存在，則會覆寫它。請注意，產生的 JUnit XML 檔案不會上傳到 CDash，因為它會與 CTest 的 Test.xml 檔案重複。

QUIET

在 3.3 版本中新增。

隱藏原本會列印到主控台的任何 CTest 特定非錯誤訊息。基礎測試命令的輸出不受影響。詳細說明通過測試百分比的摘要資訊也不受 QUIET 選項的影響。

另請參閱 CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE、CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE 和 CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION 變數，以及它們對應的 ctest(1) 命令列選項 --test-output-size-passed、--test-output-size-failed 和 --test-output-truncation。

額外測試量測¶

CTest 可以剖析您的測試輸出，以取得要回報給 CDash 的額外量測。

當以儀表板客戶端執行時，CTest 會將這些自訂量測包含在上傳至 CDash 的 Test.xml 檔案中。

請查看CDash 測試量測文件，以取得關於 CDash 可識別的測試量測類型的詳細資訊。

以下範例示範如何輸出各種自訂測試量測。

std::cout <<
  "<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>"
  << std::endl;

std::cout <<
  "<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>"
  << std::endl;

std::cout <<
  "<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.dev.org.tw</CTestMeasurement>"
  << std::endl;

std::cout <<
  "<CTestMeasurement type=\"text/preformatted\" name=\"Console Output\">" <<
  "line 1.\n" <<
  "  \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" <<
  "line 3. Not bold or indented...\n" <<
  "</CTestMeasurement>" << std::endl;

影像量測¶

以下範例示範如何將測試影像上傳到 CDash。

std::cout <<
  "<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" <<
  "/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl;

std::cout <<
  "<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" <<
  "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl;

std::cout <<
  "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\">" <<
  "/dir/to/img.png</CTestMeasurementFile>"
  << std::endl;

如果提供具有以下兩個或多個名稱的影像，則影像將會一起顯示在 CDash 上的互動式比較模式中。

TestImage
ValidImage
BaselineImage
DifferenceImage2

依照慣例，TestImage 是由您的測試所產生的影像，而 ValidImage (或 BaselineImage) 是用來判斷測試是否通過或失敗的比較基準。

如果使用其他影像名稱，CDash 會將其顯示為靜態影像，與互動式比較 UI 分開。

附加檔案¶

在 3.21 版本中新增。

以下範例示範如何將非影像檔案上傳至 CDash。

std::cout <<
  "<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" <<
  "/dir/to/data1.csv</CTestMeasurementFile>\n"                   <<
  "<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" <<
  "/dir/to/data2.csv</CTestMeasurementFile>"                     << std::endl;

如果在組態時已知要上傳的檔案名稱，則可以使用 ATTACHED_FILES 或 ATTACHED_FILES_ON_FAIL 測試屬性來代替。

自訂詳細資料¶

在 3.21 版本中新增。

以下範例示範如何為 CDash 上顯示的 Test Details 欄位指定自訂值。

std::cout <<
  "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl;

額外標籤¶

於版本 3.22 中新增。

以下範例示範如何在執行時將額外標籤新增至測試。

std::cout <<
  "<CTestLabel>Custom Label 1</CTestLabel>\n" <<
  "<CTestLabel>Custom Label 2</CTestLabel>"   << std::endl;

對於可在組態時確定的標籤，請改用 LABELS 測試屬性。

ctest_test¶

額外測試量測¶

影像量測¶

附加檔案¶

自訂詳細資料¶

額外標籤¶

目錄

上一主題

下一主題

本頁