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 <build-dir>

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

APPEND

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

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>

在版本 3.29 中新增。

請勿執行指定檔案中列出的確切名稱之測試。

INCLUDE_FROM_FILE <filename>

在版本 3.29 中新增。

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

EXCLUDE_FIXTURE <regex>

在版本 3.7 中新增。

如果一組要執行的測試中的某個測試需要特定的 fixture，則該 fixture 的設定和清除測試通常會自動新增到測試集中。此選項可防止為符合 <regex> 的 fixture 新增設定或清除測試。請注意，所有其他 fixture 行為都會保留，包括測試相依性以及略過 fixture 設定測試失敗的測試。

EXCLUDE_FIXTURE_SETUP <regex>

在版本 3.7 中新增。

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

EXCLUDE_FIXTURE_CLEANUP <regex>

在版本 3.7 中新增。

與 EXCLUDE_FIXTURE 相同，但僅排除符合的清除測試。

PARALLEL_LEVEL [<level>]

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

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

RESOURCE_SPEC_FILE <file>

在版本 3.16 中新增。

指定資源規格檔案。如需更多資訊，請參閱資源分配。

TEST_LOAD <threshold>

在版本 3.4 中新增。

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

REPEAT <mode>:<n>

在版本 3.17 中新增。

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

UNTIL_FAIL: 要求每個測試執行 <n> 次且不失敗才能通過。這對於尋找測試案例中零星的失敗很有用。
UNTIL_PASS: 允許每個測試執行最多 <n> 次才能通過。如果測試因任何原因失敗，則重複測試。這對於容忍測試案例中零星的失敗很有用。
AFTER_TIMEOUT: 允許每個測試執行最多 <n> 次才能通過。僅在測試逾時時重複測試。這對於容忍忙碌機器上零星的逾時很有用。

SCHEDULE_RANDOM <ON|OFF>

以隨機順序啟動測試。這對於偵測隱含的測試相依性可能很有用。

STOP_ON_FAILURE

在版本 3.18 中新增。

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

STOP_TIME <time-of-day>

指定一天中的時間，屆時所有測試都應停止執行。

RETURN_VALUE <result-var>

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

CAPTURE_CMAKE_ERROR <result-var>

在版本 3.7 中新增。

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

OUTPUT_JUNIT <file>

在版本 3.21 中新增。

以 JUnit XML 格式將測試結果寫入 <file>。如果 <file> 是相對路徑，則會將其放置在建置目錄中。如果 <file> 已存在，則會覆寫它。請注意，產生的 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 會將這些自訂量測包含在 Test.xml 檔案中，該檔案會上傳到 CDash。

查看 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 上顯示的 測試詳細資訊 欄位指定自訂值。

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¶

其他測試量測¶

影像量測¶

附加檔案¶

自訂詳細資訊¶

其他標籤¶

目錄

上一主題

下一主題

本頁