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>]
           [PRESET <preset>]
           [PRESETS_FILE <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.

Если для теста из набора выполняемых тестов требуется определенная фикстура, тесты настройки и очистки этой фикстуры обычно автоматически добавляются в набор тестов. Этот параметр запрещает добавлять тесты настройки или очистки для фикстур, соответствующих <regex>. Обратите внимание, что сохраняется все остальное поведение фикстур, включая зависимости тестов и пропуск тестов, для которых не удалось выполнить тесты настройки фикстур.

EXCLUDE_FIXTURE_SETUP <regex>

Добавлено в версии 3.7.

То же, что и EXCLUDE_FIXTURE, за исключением того, что исключаются только соответствующие тесты настройки.

EXCLUDE_FIXTURE_CLEANUP <regex>

Добавлено в версии 3.7.

То же, что и EXCLUDE_FIXTURE, за исключением того, что исключаются только соответствующие тесты очистки.

PARALLEL_LEVEL [<level>]

Запускает тесты параллельно с заданным уровнем параллелизма.

Добавлено в версии 3.29: Значение <level> можно опустить или задать как 0, чтобы ctest(1) использовал уровень параллелизма по умолчанию или неограниченный уровень параллелизма соответственно, как описано в параметре ctest --parallel.

RESOURCE_SPEC_FILE <file>

Добавлено в версии 3.16.

Указывает файл спецификации ресурсов. Дополнительные сведения см. в разделе Выделение ресурсов.

TEST_LOAD <threshold>

Добавлено в версии 3.4.

При параллельном запуске тестов старайтесь не запускать тесты, если они могут привести к превышению заданного порога загрузки ЦП. Если значение не указано, будет проверена переменная CTEST_TEST_LOAD, а затем аргумент командной строки --test-load команды ctest(1). См. также параметр TestLoad в разделе Шаг тестирования CTest.

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(1) возвращать ненулевой код завершения при возникновении ошибки.

OUTPUT_JUNIT <file>

Добавлено в версии 3.21.

Записывает результаты тестов в <file> в формате JUnit XML. Если <file> — относительный путь, файл будет размещен в каталоге сборки. Если <file> уже существует, он будет перезаписан. Обратите внимание, что полученный файл JUnit XML не отправляется в CDash, поскольку он дублировал бы файл Test.xml CTest.

COVERAGE_TOOL <tool>

Добавлено в версии 4.4.

Указывает <tool>, используемый для сбора данных о покрытии во время выполнения тестов. Подробности см. в параметре CoverageTool CTest.

PRESET <preset>

Добавлено в версии 4.4.

Указывает preset, используемый при запуске тестов. Любое значение, заданное в скрипте CTest, имеет приоритет над соответствующим параметром пресета. Например, аргумент INCLUDE переопределит параметр filter.include.name выбранного пресета.

Этот параметр также применяется к команде ctest_memcheck(). См. также переменные CTEST_TEST_PRESET и CTEST_PRESET.

PRESETS_FILE <file>

Добавлено в версии 4.4.

Указывает файл presets, используемый вместо файла CMakePresets.json по умолчанию в каталоге исходного кода. Относительный путь интерпретируется относительно каталога исходного кода. Не действует, если пресет не выбран с помощью аргумента PRESET или переменных CTEST_TEST_PRESET или CTEST_PRESET.

Этот параметр также применяется к команде ctest_memcheck(). См. также переменную CTEST_PRESETS_FILE.

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.org</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 как статическое изображение отдельно от интерактивного интерфейса сравнения.

Прикрепленные файлы

В следующем примере показано, как загружать файлы, не являющиеся изображениями, в 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.

Пользовательские сведения

В следующем примере показано, как указать пользовательское значение для поля Test Details, отображаемого в CDash.

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

Дополнительные метки

В следующем примере показано, как добавлять дополнительные метки к тесту во время выполнения.

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

Для меток, которые можно определить на этапе конфигурирования, используйте вместо этого свойство теста LABELS.