ctest(1)

Краткое описание
Описание
Опции
Резюме метки и подпроектов
Режим сборки и тестирования
Клиент панели мониторинга
Настройка клиента панели мониторинга
Показать как JSON объект модели
Распределение ресурсов
См. также

Краткое описание

ctest [<options>]
ctest --build-and-test <path-to-source> <path-to-build>
      --build-generator <generator> [<options>...]
      [--build-options <opts>...] [--test-command <command> [<args>...]]
ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>}
      [-- <dashboard-options>...]

Описание

Исполняемый файл ctest — это программа-драйвер тестов CMake. Деревья сборки, сгенерированные CMake для проектов, использующих команды enable_testing() и add_test(), имеют поддержку тестирования. Эта программа выполнит тесты и представит результаты.

Опции

--preset <preset>, --preset=<preset>

Используйте предопределенный набор тестов для указания параметров тестов. Директория двоичных файлов проекта определяется по ключу configurePreset. Текущая рабочая директория должна содержать файлы предопределений CMake. Для получения более подробной информации см. preset.

--list-presets

Список доступных наборов тестов. Текущая рабочая директория должна содержать файлы предопределений CMake.

-C <cfg>, --build-config <cfg>

Выбор конфигурации для тестирования.

Некоторые сгенерированные CMake деревья сборки могут содержать несколько конфигураций сборки в одном дереве. Этот параметр позволяет указать, какая из них должна быть протестирована. Примеры конфигураций: Debug и Release.

--progress

Включить краткий вывод прогресса тестов.

Когда вывод ctest направляется непосредственно в терминал, прогресс выполнения набора тестов отображается обновлением той же строки, а не выводом сообщений начала и конца каждого теста в новых строках. Это значительно уменьшает объем вывода тестов. Сообщения о завершении теста все равно выводятся в отдельной строке для неудачных тестов, а также будет выведен итоговый отчет о результатах тестов.

Этот параметр также можно включить, задав переменную среды CTEST_PROGRESS_OUTPUT.

-V,--verbose

Включить подробный вывод тестов.

Вывод тестов обычно подавляется, и отображается только сводная информация. Этот параметр покажет весь вывод тестов.

-VV,--extra-verbose

Включить более подробный вывод тестов.

Вывод тестов обычно подавляется, и отображается только сводная информация. Этот параметр покажет ещё больше вывода тестов.

--debug

Отображение более подробной внутренней информации CTest.

Эта функция приводит к большому объёму вывода, который в основном полезен для отладки проблем с панелью инструментов.

--output-on-failure

Вывести всё, что вывело тестовое приложение, если тест не пройден. Этот параметр также можно включить, задав переменную среды CTEST_OUTPUT_ON_FAILURE.

--stop-on-failure

Остановьте выполнение тестов при первом обнаружении ошибки.

-F

Включить возврат (failover).

Этот параметр позволяет CTest возобновить выполнение набора тестов, которое было прервано ранее. Если прерывания не было, параметр -F не повлияет.

-j <jobs>, --parallel <jobs>

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

Этот параметр указывает CTest на запуск тестов параллельно с заданным числом процессов. Этот параметр также можно задать, установив переменную среды CTEST_PARALLEL_LEVEL.

Этот параметр может быть использован с тестовой характеристикой PROCESSORS.

См. Краткое описание меток и подпроектов.

--resource-spec-file <file>

Запуск CTest с включённым распределением ресурсов, используя файл описания ресурсов, указанный в <file>.

Когда ctest запущен как Клиент панели инструментов, это устанавливает параметр ResourceSpecFile шага тестирования CTest.

--test-load <level>

При одновременном выполнении тестов (например, с -j), старайтесь не запускать тесты, которые могут привести к превышению заданного порога загрузки процессора.

Когда ctest запущен как Клиент панели инструментов, это устанавливает параметр TestLoad шага тестирования CTest.

-Q,--quiet

Сделать CTest тихим.

Этот параметр подавит весь вывод. Файл журнала вывода всё равно будет сгенерирован, если указан --output-log. Параметры, такие как --verbose, --extra-verbose, и --debug, игнорируются, если указан --quiet.

-O <file>, --output-log <file>

Вывод в файл журнала.

Этот параметр указывает CTest записывать весь вывод в файл журнала <file>.

-N,--show-only[=<format>]

Отключить фактическое выполнение тестов.

Этот параметр указывает CTest перечислить тесты, которые должны были бы быть запущены, но не запускать их. Полезно в сочетании с параметрами -R и -E.

<format> может принимать следующие значения.

human: Вывод в удобочитаемом формате. Не гарантируется стабильность. По умолчанию.
json-v1: Вывести информацию о тесте в формате JSON. См. Показать в виде JSON-объекта.

-L <regex>, --label-regex <regex>

Запустить тесты с метками, соответствующими регулярному выражению.

Этот параметр указывает CTest запускать только тесты, метки которых соответствуют заданному регулярному выражению.

-R <regex>, --tests-regex <regex>

Запустить тесты, соответствующие регулярному выражению.

Этот параметр указывает CTest запускать только тесты, имена которых соответствуют заданному регулярному выражению.

-E <regex>, --exclude-regex <regex>

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

Этот параметр указывает CTest НЕ запускать тесты, имена которых соответствуют заданному регулярному выражению.

-LE <regex>, --label-exclude <regex>

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

Этот параметр указывает CTest НЕ запускать тесты, метки которых соответствуют заданному регулярному выражению.

-FA <regex>, --fixture-exclude-any <regex>

Исключить фикстуры, соответствующие <regex>, из автоматического добавления тестов в набор тестов.

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

-FS <regex>, --fixture-exclude-setup <regex>

Аналогично -FA, но исключаются только соответствующие тесты настройки.

-FC <regex>, --fixture-exclude-cleanup <regex>

Аналогично -FA, но исключаются только соответствующие тесты очистки.

-D <dashboard>, --dashboard <dashboard>

Выполнить тестовый сценарий панели инструментов.

Этот параметр указывает CTest действовать как клиент CDash и выполнить тестовый сценарий панели инструментов. Все тесты <Mode><Test>, где <Mode> может быть Experimental, Nightly, и Continuous, и <Test> может быть Start, Update, Configure, Build, Test, Coverage, и Submit.

См. Клиент панели инструментов.

-D <var>:<type>=<value>

Определить переменную для сценария скрипта.

Передать значения переменных через командную строку. Используйте в сочетании с -S для передачи значений переменных в скрипт панели инструментов. Парсинг аргументов -D как значений переменных производится только если значение, следующее за -D, не соответствует ни одному из известных типов панели инструментов.

-M <model>, --test-model <model>

Устанавливает модель для панели инструментов.

Этот параметр указывает CTest действовать как клиент CDash, где <model> может быть Experimental, Nightly, и Continuous. Сочетание -M и -T аналогично -D.

См. Клиент панели инструментов.

-T <action>, --test-action <action>

Устанавливает действие панели инструментов.

Этот параметр указывает CTest действовать как клиент CDash и выполнить действие, такое как start, build, test и т. д. См. Шаги клиента панели инструментов для полного списка действий. Сочетание -M и -T аналогично -D.

См. Клиент панели инструментов.

-S <script>, --script <script>

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

Этот параметр указывает CTest загрузить скрипт конфигурации, который устанавливает ряд параметров, таких как двоичные и исходные каталоги. Затем CTest выполнит необходимые действия для создания и запуска панели инструментов. Этот параметр в основном настраивает панель инструментов и затем запускает ctest -D с соответствующими параметрами.

См. Клиент панели инструментов.

-SP <script>, --script-new-process <script>

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

Этот параметр выполняет те же операции, что и -S, но в отдельном процессе. Это в первую очередь полезно в случаях, когда скрипт может изменять среду, и вы не хотите, чтобы изменённая среда влияла на другие -S скрипты.

См. Клиент панели инструментов.

-I [Start,End,Stride,test#,test#|Test file], --tests-information

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

Этот параметр заставляет CTest запускать тесты, начиная с номера Start, заканчивая номером End, и увеличивая на Stride. Любые дополнительные числа после Stride рассматриваются как отдельные номера тестов. Start, End, или Stride могут быть пустыми. Дополнительно можно указать файл, содержащий ту же синтаксическую структуру, что и командная строка.

-U, --union

Взять Объединение -I и -R.

Когда оба -R и -I указаны, по умолчанию выполняется пересечение тестов. Указав -U, вместо этого выполняется объединение тестов.

--rerun-failed

Выполнять только тесты, которые ранее завершились неудачно.

Этот параметр указывает CTest выполнить только те тесты, которые завершились неудачно во время предыдущего запуска. При указании этого параметра CTest игнорирует все другие параметры, предназначенные для изменения списка запускаемых тестов (-L, -R, -E, -LE, -I, и т. д.). В случае, если CTest запустится и ни один тест не завершится неудачно, последующие вызовы CTest с параметром --rerun-failed будут запускать набор тестов, которые в последний раз завершились неудачно (если таковые имеются).

--repeat <mode>:<n>

Повторять тесты в соответствии с заданным <mode> до <n> раз. Режимы:

until-fail: Требуется, чтобы каждый тест запускался <n> раз без ошибок, чтобы пройти. Это полезно для обнаружения спорадических ошибок в тестовых случаях.
until-pass: Разрешает каждому тесту запускаться до <n> раз, чтобы пройти. Повторяет тесты, если они завершаются неудачно по любой причине. Это полезно для переносимости спорадических ошибок в тестовых случаях.
after-timeout: Разрешает каждому тесту запускаться до <n> раз, чтобы пройти. Повторяет тесты только в случае таймаута. Это полезно для переносимости спорадических таймаутов в тестовых случаях на загруженных машинах.

--repeat-until-fail <n>

Эквивалентно --repeat until-fail:<n>.

--max-width <width>

Установить максимальную ширину имени теста для вывода.

Установить максимальную ширину для каждого имени теста, отображаемого в выводе. Это позволяет пользователю расширить вывод, чтобы избежать обрезания имени теста, что может быть очень раздражающим.

--interactive-debug-mode [0|1]

Установить интерактивный режим на 0 или 1.

Этот параметр заставляет CTest запускать тесты в интерактивном или неинтерактивном режиме. В Windows это означает, что в неинтерактивном режиме все всплывающие окна отладки системы блокируются. В режиме панели мониторинга (Experimental, Nightly, Continuous ), по умолчанию используется неинтерактивный режим. При простом запуске тестов, не предназначенных для панели мониторинга, по умолчанию разрешаются всплывающие окна и интерактивная отладка.

--no-label-summary

Отключить информацию о времени выполнения для меток.

Этот параметр указывает CTest не отображать сводную информацию для каждой метки, связанной с запущенными тестами. Если тесты не имеют меток, дополнительная информация не выводится.

См. Сводка по меткам и подпроектам.

--no-subproject-summary

Отключить сводную информацию о времени выполнения для подпроектов.

Этот параметр указывает CTest не отображать сводную информацию для каждого подпроекта, связанного с запущенными тестами. Если тесты не имеют подпроектов, дополнительная информация не выводится.

См. Сводка по меткам и подпроектам.

--build-and-test См. Режим сборки и тестирования.

--test-dir <dir> Укажите каталог, в котором следует искать тесты.

--test-output-size-passed <size>

Ограничить вывод для пройденных тестов до <size> байт.

--test-output-size-failed <size>

Ограничить вывод для завершившихся неудачно тестов до <size> байт.

--overwrite

Перезапись параметра конфигурации CTest.

По умолчанию CTest использует параметры конфигурации из файла конфигурации. Этот параметр перезапишет параметр конфигурации.

--force-new-ctest-process

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

По умолчанию CTest запускает дочерние экземпляры CTest в рамках одного процесса. Если это поведение нежелательно, этот аргумент заставит использовать новые процессы для дочерних процессов CTest.

--schedule-random

Использовать случайный порядок планирования тестов.

Этот параметр запустит тесты в случайном порядке. Он часто используется для обнаружения неявных зависимостей в наборе тестов.

--submit-index

Устаревший параметр для старой функции сервера панели мониторинга Dart2. Не использовать.

--timeout <seconds>

Установить значение таймаута по умолчанию для тестов.

Этот параметр устанавливает таймаут для всех тестов, которые не имеют таймаута, установленного с помощью свойства TIMEOUT.

--stop-time <time>

Установить время, по которому все тесты должны прекратить выполнение.

Установите фактическое время, в которое все тесты должны завершиться с таймаутом. Пример: 7:00:00 -0400. Любой формат времени, распознаваемый парсером даты curl, принимается. Если часовой пояс не указан, предполагается местное время.

--print-labels

Вывести все доступные метки тестов.

Этот параметр не будет запускать тесты, он просто выведет список всех меток, связанных с набором тестов.

--no-tests=<[error|ignore]>

Рассматривать отсутствие тестов либо как ошибку, либо игнорировать.

Если тесты не были найдены, по умолчанию CTest всегда записывает сообщение об ошибке, но возвращает код ошибки только в режиме сценария. Этот параметр унифицирует поведение CTest, возвращая код ошибки, если тесты не найдены, или игнорируя это.

--help,-help,-usage,-h,-H,/?

Вывести информацию об использовании и выйти.

Использование описывает базовый интерфейс командной строки и его опции.

--version,-version,/V [<f>]

Показать баннер с именем/версией программы и выйти.

Если указан файл, версия записывается в него. Справка выводится в указанный файл <f> если он предоставлен.

--help-full [<f>]

Вывести все руководства по справке и выйти.

Все руководства выводятся в удобочитаемом текстовом формате. Справка выводится в указанный файл <f> если он предоставлен.

--help-manual <man> [<f>]

Вывести одно руководство по справке и выйти.

Указанное руководство выводится в удобочитаемом текстовом формате. Справка выводится в указанный файл <f> если он предоставлен.

--help-manual-list [<f>]

Вывести список доступных руководств по справке и выйти.

Список содержит все руководства, справка по которым может быть получена с помощью опции --help-manual и имени руководства. Справка выводится в указанный файл <f> если он предоставлен.

--help-command <cmd> [<f>]

Вывести справку по одной команде и выйти.

Запись справки cmake-commands(7) для <cmd> выводится в удобочитаемом текстовом формате. Справка выводится в указанный файл <f> если он предоставлен.

--help-command-list [<f>]

Вывести список команд со справочной информацией и выйти.

Список содержит все команды, справка по которым может быть получена с помощью опции --help-command и имени команды. Справка выводится в указанный файл <f> если он предоставлен.

--help-commands [<f>]

Вывести руководство cmake-commands и выйти.

Руководство cmake-commands(7) выводится в удобочитаемом текстовом формате. Справка выводится в указанный файл <f> если он предоставлен.

--help-module <mod> [<f>]

Вывести справку по одному модулю и выйти.

Запись справки cmake-modules(7) для <mod> выводится в удобочитаемом текстовом формате. Справка выводится в указанный файл <f> если он предоставлен.

--help-module-list [<f>]

Вывести список модулей со справочной информацией и выйти.

Список содержит все модули, справка по которым может быть получена с помощью опции --help-module и имени модуля. Справка выводится в указанный файл <f> если он предоставлен.

--help-modules [<f>]

Вывести руководство cmake-modules и выйти.

Руководство cmake-modules(7) выводится в удобочитаемом текстовом формате. Справка выводится в указанный файл <f> если он предоставлен.

--help-policy <cmp> [<f>]

Вывести справку по одной политике и выйти.

Запись справки cmake-policies(7) для <cmp> выводится в удобочитаемом текстовом формате. Справка выводится в указанный файл <f> если он предоставлен.

--help-policy-list [<f>]

Вывести список политик со справочной информацией и выйти.

Список содержит все политики, справка по которым может быть получена с помощью опции --help-policy и имени политики. Справка выводится в указанный файл <f> если он предоставлен.

--help-policies [<f>]

Вывести руководство cmake-policies и выйти.

Руководство cmake-policies(7) выводится в удобочитаемом текстовом формате. Справка выводится в указанный файл <f> если он предоставлен.

--help-property <prop> [<f>]

Вывести справку по одному свойству и выйти.

Записи справки cmake-properties(7) для <prop> выводятся в удобочитаемом текстовом формате. Справка выводится в указанный файл <f> если он предоставлен.

--help-property-list [<f>]

Вывести список свойств со справочной информацией и выйти.

Список содержит все свойства, справка по которым может быть получена с помощью опции --help-property и имени свойства. Справка выводится в указанный файл <f> если он предоставлен.

--help-properties [<f>]

Вывести руководство cmake-properties и выйти.

Руководство cmake-properties(7) выводится в удобочитаемом текстовом формате. Справка выводится в указанный файл <f> если он предоставлен.

--help-variable <var> [<f>]

Вывести справку по одной переменной и выйти.

Запись справки cmake-variables(7) для <var> выводится в удобочитаемом текстовом формате. Справка выводится в указанный файл <f> если он предоставлен.

--help-variable-list [<f>]

Вывести список переменных со справочной информацией и выйти.

Список содержит все переменные, справка по которым может быть получена с помощью опции --help-variable и имени переменной. Справка выводится в указанный файл <f> если он предоставлен.

--help-variables [<f>]

Вывести руководство cmake-variables и выйти.

Руководство cmake-variables(7) выводится в удобочитаемом текстовом формате. Справка выводится в указанный файл <f> если он предоставлен.

Краткое описание меток и подпроектов

CTest выводит сводку временных характеристик для каждой LABEL и подпроекта, связанного с выполненными тестами. Сводка времени по меткам не будет включать метки, которые сопоставлены с подпроектами.

Когда свойство теста PROCESSORS задано, CTest отобразит взвешенный результат времени выполнения теста в сводках меток и подпроектов. Время указывается с sec*proc вместо просто sec.

Взвешенная сводка времени, сообщаемая для каждой метки или подпроекта j вычисляется следующим образом:

Weighted Time Summary for Label/Subproject j =
    sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j])

for labels/subprojects j=1...total

где:

raw_test_time[j,i]: Время настенных часов для теста i для метки j или подпроекта
num_processors[j,i]: Значение свойства CTest PROCESSORS для теста i для метки j или подпроекта
num_tests[j]: Количество тестов, связанных с меткой j или подпроектом
total: Общее количество меток или подпроектов, имеющих хотя бы один запущенный тест

Таким образом, взвешенная сводка времени для каждой метки или подпроекта представляет собой время, которое CTest потратил на выполнение тестов для каждой метки или подпроекта, и дает хорошее представление о общих затратах тестов для каждой метки или подпроекта по сравнению с другими метками или подпроектами.

Например, если SubprojectA показал 100 sec*proc и SubprojectB показал 10 sec*proc, то CTest выделил примерно в 10 раз больше времени процессора/ядра для выполнения тестов для SubprojectA по сравнению с SubprojectB (например, если будут затрачены усилия для сокращения стоимости набора тестов для всего проекта, то сокращение стоимости набора тестов для SubprojectA будет, вероятно, иметь больший эффект, чем усилия по сокращению стоимости набора тестов для SubprojectB).

Режим сборки и тестирования

CTest предоставляет подпись командной строки для конфигурирования (т.е. запуска cmake), сборки и/или выполнения теста:

ctest --build-and-test <path-to-source> <path-to-build>
      --build-generator <generator>
      [<options>...]
      [--build-options <opts>...]
      [--test-command <command> [<args>...]]

Шаги конфигурирования и тестирования являются необязательными. Аргументы этой командной строки — это каталоги исходных и двоичных файлов. Опция --build-generator обязательна для использования --build-and-test. Если --test-command указано, то оно будет выполнено после завершения сборки. Другие параметры, влияющие на этот режим, включают:

--build-target

Укажите конкретную цель сборки.

Если она не указана, собирается цель all.

--build-nocmake

Запустить сборку без предварительного выполнения cmake.

Пропустить шаг cmake.

--build-run-dir

Укажите каталог для запуска программ.

Каталог, в котором программы будут находиться после компиляции.

--build-two-config

Выполнить CMake дважды.

--build-exe-dir

Укажите каталог для исполняемого файла.

--build-generator

Укажите используемый генератор. См. руководство cmake-generators(7).

--build-generator-platform

Укажите платформу, специфичную для генератора.

--build-generator-toolset

Укажите набор инструментов, специфичный для генератора.

--build-project

Укажите имя проекта для сборки.

--build-makeprogram

Укажите явную программу make, которую CMake должен использовать для конфигурирования и сборки проекта. Применимо только для генераторов, основанных на Make и Ninja.

--build-noclean

Пропустить шаг make clean.

--build-config-sample

Образец исполняемого файла для определения конфигурации, которая должна быть использована. Например, Debug, Release и т. д.

--build-options

Дополнительные параметры для конфигурирования сборки (т.е. для CMake, а не для инструмента сборки). Обратите внимание, что если этот параметр указан, ключевое слово --build-options и его аргументы должны быть последними параметрами, заданными в командной строке, за исключением --test-command.

--test-command

Команда для выполнения на шаге тестирования с опцией --build-and-test. Все аргументы после этого ключевого слова будут считаться частью командной строки теста, поэтому это должен быть последний параметр.

--test-timeout

Предельное время в секундах

Клиент панели мониторинга

CTest может работать как клиент приложения панели мониторинга качества программного обеспечения CDash. В качестве клиента панели мониторинга CTest выполняет последовательность шагов по конфигурированию, сборке и тестированию программного обеспечения, а затем отправляет результаты на сервер CDash. Сигнатура командной строки для отправки в CDash:

ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
      [-- <dashboard-options>...]

Параметры для клиента панели мониторинга включают:

--group <group>

Укажите группу, в которую вы хотите отправить результаты

Отправить панель мониторинга в указанную группу вместо стандартной. По умолчанию панель мониторинга отправляется в группу "Ежедневная", "Экспериментальная" или "Непрерывная", но с помощью этого параметра группа может быть любой.

Заменяет устаревший параметр --track. Несмотря на изменение названия, его поведение не изменяется.

-A <file>, --add-notes <file>

Добавить файл заметок при отправке.

Этот параметр сообщает CTest включить файл заметок при отправке в панель мониторинга.

--tomorrow-tag

Nightly или Experimental начинается с метки следующего дня.

Это полезно, если сборка не завершится в один день.

--extra-submit <file>[;<file>]

Отправить дополнительные файлы в панель мониторинга.

Этот параметр отправит дополнительные файлы в панель мониторинга.

--http1.0

Отправить используя HTTP 1.0.

Этот параметр принудительно заставит CTest использовать HTTP 1.0 для отправки файлов в панель мониторинга вместо HTTP 1.1.

--no-compress-output

Не сжимать выходные данные тестов при отправке.

Этот флаг отключит автоматическое сжатие выходных данных тестов. Используйте его для сохранения совместимости со старой версией CDash, которая не поддерживает сжатые выходные данные тестов.

Шаги клиента панели мониторинга

CTest определяет упорядоченный список шагов тестирования, некоторые или все из которых могут быть запущены как клиент панели мониторинга:

Start: Начать новую отправку в панель мониторинга, которая будет состоять из результатов, записанных последующими шагами. См. раздел Шаг запуска CTest ниже.
Update: Обновить дерево исходных файлов из системы управления версиями. Записать старые и новые версии, а также список обновлённых исходных файлов. См. раздел Шаг обновления CTest ниже.
Configure: Настроить программное обеспечение, выполнив команду в дереве сборки. Записать лог конфигурации. См. раздел Шаг конфигурирования CTest ниже.
Build: Собрать программное обеспечение, выполнив команду в дереве сборки. Записать лог сборки и выявить предупреждения и ошибки. См. раздел Шаг сборки CTest ниже.
Test: Протестировать программное обеспечение, загрузив CTestTestfile.cmake из дерева сборки и выполнив определённые тесты. Записать выходные данные и результаты каждого теста. См. раздел Шаг тестирования CTest ниже.
Coverage: Вычислить покрытие исходного кода, запустив инструмент анализа покрытия и записав его выходные данные. См. раздел Шаг покрытия CTest ниже.
MemCheck: Запустить программный набор тестов через инструмент проверки памяти. Записать выходные данные тестов, результаты и проблемы, обнаруженные инструментом. См. раздел Шаг проверки памяти CTest ниже.
Submit: Отправить результаты, записанные другими шагами тестирования, на сервер панели мониторинга качества программного обеспечения. См. раздел Шаг отправки CTest ниже.

Режимы работы клиента панели мониторинга

CTest определяет три режима работы в качестве клиента панели мониторинга:

Nightly: Этот режим предназначен для вызова один раз в день, обычно ночью. Он включает шаги Start, Update, Configure, Build, Test, Coverage, и Submit по умолчанию. Выбранные шаги выполняются, даже если шаг Update не обнаруживает изменений в дереве исходных файлов.
Continuous: Этот режим предназначен для многократного вызова в течение дня. Он включает шаги Start, Update, Configure, Build, Test, Coverage, и Submit по умолчанию, но завершается после шага Update если он не обнаруживает изменений в дереве исходных файлов.
Experimental: Этот режим предназначен для вызова разработчиком для тестирования локальных изменений. Он включает шаги Start, Configure, Build, Test, Coverage, и Submit по умолчанию.

Клиент панели мониторинга через командную строку CTest

CTest может выполнять тестирование на уже сгенерированном дереве сборки. Запустите команду ctest с текущим рабочим каталогом, установленным в дереве сборки, и используйте одну из этих сигнатур:

ctest -D <mode>[<step>]
ctest -M <mode> [ -T <step> ]...

<mode> должен быть одним из вышеперечисленных режимов работы клиента панели мониторинга, а каждый <step> должен быть одним из вышеперечисленных шагов клиента панели мониторинга.

CTest считывает параметры настройки клиента панели мониторинга из файла в дереве сборки, названного либо CTestConfiguration.ini, либо DartConfiguration.tcl (названия имеют историческую подоплёку). Формат файла:

# Lines starting in '#' are comments.
# Other non-blank lines are key-value pairs.
<setting>: <value>

где <setting> - имя параметра, а <value> - значение параметра.

В деревьях сборки, сгенерированных CMake, этот файл конфигурации генерируется модулем CTest, если он включён проектом. Модуль использует переменные для получения значения каждого параметра, как документировано в разделах ниже.

Клиент панели мониторинга через скрипт CTest

CTest может выполнять тестирование, управляемое скриптом cmake-language(7), который создаёт и поддерживает дерево исходных и сборки, а также выполняет шаги тестирования. Запустите команду ctest с текущим рабочим каталогом вне любого дерева сборки и используйте одну из этих сигнатур:

ctest -S <script>
ctest -SP <script>

Файл <script> должен вызывать команды Команды CTest для явного запуска шагов тестирования, как описано ниже. Команды получают настройки настроек клиента панели мониторинга из их аргументов или из переменных, установленных в скрипте.

Настройки клиента панели мониторинга

Шаги клиента панели мониторинга можно настроить с помощью именованных параметров, как описано в следующих разделах.

Шаг запуска CTest

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

В скрипте CTest команда ctest_start() выполняет этот шаг. Аргументы команды могут указать некоторые параметры шага. Команда сначала выполняет команду, указанную в переменной CTEST_CHECKOUT_COMMAND, если она задана, для инициализации каталога исходных файлов.

Параметры конфигурации включают:

BuildDirectory

Полный путь к дереву построения проекта.

Сценарий CTest переменная: CTEST_BINARY_DIRECTORY
CTest модуль переменная: PROJECT_BINARY_DIR

SourceDirectory

Полный путь к дереву исходного кода проекта.

Сценарий CTest переменная: CTEST_SOURCE_DIRECTORY
CTest модуль переменная: PROJECT_SOURCE_DIR

Шаг обновления CTest

В Сценарии CTest команда ctest_update() выполняет этот шаг. Аргументы команды могут указать некоторые настройки шага.

Настройки конфигурации для указания инструмента контроля версий включают:

BZRCommand

bzr инструмент командной строки для использования, если дерево исходных файлов управляется Bazaar.

Сценарий CTest переменная: CTEST_BZR_COMMAND
CTest переменная модуля: нет

BZRUpdateOptions

Параметры командной строки для BZRCommand при обновлении исходных файлов.

Сценарий CTest переменная: CTEST_BZR_UPDATE_OPTIONS
CTest переменная модуля: нет

CVSCommand

cvs инструмент командной строки для использования, если дерево исходных файлов управляется CVS.

Сценарий CTest переменная: CTEST_CVS_COMMAND
CTest переменная модуля: CVSCOMMAND

CVSUpdateOptions

Параметры командной строки для CVSCommand при обновлении исходных файлов.

Сценарий CTest переменная: CTEST_CVS_UPDATE_OPTIONS
CTest переменная модуля: CVS_UPDATE_OPTIONS

GITCommand

git инструмент командной строки для использования, если дерево исходных файлов управляется Git.

Сценарий CTest переменная: CTEST_GIT_COMMAND
CTest переменная модуля: GITCOMMAND

Обновление дерева исходных файлов выполняется с помощью git fetch и git reset --hard в FETCH_HEAD. Результат аналогичен git pull, за исключением того, что все локальные изменения перезаписываются. Используйте GITUpdateCustom для указания другого подхода.

GITInitSubmodules

Если установлено, CTest обновит подмодули репозитория перед обновлением.

Сценарий CTest переменная: CTEST_GIT_INIT_SUBMODULES
CTest переменная модуля: CTEST_GIT_INIT_SUBMODULES

GITUpdateCustom

Укажите пользовательскую командную строку (в виде списка, разделенного точкой с запятой) для выполнения в дереве исходных файлов (рабочей области Git), чтобы обновить его вместо запуска GITCommand.

Сценарий CTest переменная: CTEST_GIT_UPDATE_CUSTOM
CTest переменная модуля: CTEST_GIT_UPDATE_CUSTOM

GITUpdateOptions

Параметры командной строки для GITCommand при обновлении исходных файлов.

Сценарий CTest переменная: CTEST_GIT_UPDATE_OPTIONS
CTest переменная модуля: GIT_UPDATE_OPTIONS

HGCommand

hg инструмент командной строки для использования, если дерево исходных файлов управляется Mercurial.

Сценарий CTest переменная: CTEST_HG_COMMAND
CTest переменная модуля: нет

HGUpdateOptions

Параметры командной строки для HGCommand при обновлении исходных файлов.

Сценарий CTest переменная: CTEST_HG_UPDATE_OPTIONS
CTest переменная модуля: нет

P4Client

Значение параметра -c для P4Command.

Сценарий CTest переменная: CTEST_P4_CLIENT
CTest переменная модуля: CTEST_P4_CLIENT

P4Command

p4 инструмент командной строки для использования, если дерево исходных файлов управляется Perforce.

Сценарий CTest переменная: CTEST_P4_COMMAND
CTest переменная модуля: P4COMMAND

P4Options

Параметры командной строки для P4Command для всех вызовов.

Сценарий CTest переменная: CTEST_P4_OPTIONS
CTest переменная модуля: CTEST_P4_OPTIONS

P4UpdateCustom

Укажите пользовательскую командную строку (в виде списка, разделенного точкой с запятой) для выполнения в дереве исходных файлов (дереве Perforce), чтобы обновить его вместо запуска P4Command.

Сценарий CTest переменная: нет
CTest переменная модуля: CTEST_P4_UPDATE_CUSTOM

P4UpdateOptions

Параметры командной строки для P4Command при обновлении исходных файлов.

Сценарий CTest переменная: CTEST_P4_UPDATE_OPTIONS
CTest переменная модуля: CTEST_P4_UPDATE_OPTIONS

SVNCommand

svn инструмент командной строки для использования, если дерево исходных файлов управляется Subversion.

Сценарий CTest переменная: CTEST_SVN_COMMAND
CTest переменная модуля: SVNCOMMAND

SVNOptions

Параметры командной строки для SVNCommand для всех вызовов.

Сценарий CTest переменная: CTEST_SVN_OPTIONS
CTest переменная модуля: CTEST_SVN_OPTIONS

SVNUpdateOptions

Параметры командной строки для SVNCommand при обновлении исходных файлов.

Сценарий CTest переменная: CTEST_SVN_UPDATE_OPTIONS
CTest переменная модуля: SVN_UPDATE_OPTIONS

UpdateCommand

Укажите инструмент командной строки для управления системами контроля версий, не определяя систему управления VCS, которая управляет деревом исходного кода.

Сценарий CTest переменная: CTEST_UPDATE_COMMAND
CTest модульная переменная: <VCS>COMMAND когда UPDATE_TYPE равно <vcs>, иначе UPDATE_COMMAND

UpdateOptions

Параметры командной строки для UpdateCommand.

Сценарий CTest переменная: CTEST_UPDATE_OPTIONS
CTest модульная переменная: <VCS>_UPDATE_OPTIONS когда UPDATE_TYPE равно <vcs>, иначе UPDATE_OPTIONS

UpdateType

Укажите систему управления версиями, которая управляет деревом исходного кода, если ее нельзя автоматически определить. Значение может быть bzr, cvs, git, hg, p4, или svn.

Сценарий CTest переменная: ничего, определено из дерева исходного кода
CTest модульная переменная: UPDATE_TYPE если установлено, иначе CTEST_UPDATE_TYPE

UpdateVersionOnly

Укажите, что вы хотите, чтобы команда обновления контроля версий обнаруживала только текущую версию, которая находится в рабочей области, а не обновлялась до другой версии.

Сценарий CTest переменная: CTEST_UPDATE_VERSION_ONLY

UpdateVersionOverride

Укажите текущую версию вашего дерева исходного кода.

Когда эта переменная имеет ненулевое значение, CTest сообщит указанное вами значение, а не будет использовать команду обновления для обнаружения текущей версии, находящейся в рабочей области. Использование этой переменной имеет приоритет над UpdateVersionOnly. Как и UpdateVersionOnly, использование этой переменной сообщает CTest не обновлять дерево исходного кода до другой версии.

Сценарий CTest переменная: CTEST_UPDATE_VERSION_OVERRIDE

Дополнительные параметры настройки включают:

NightlyStartTime

В режиме панели Nightly укажите "время начала ночных тестов". В системах централизованного контроля версий (cvs и svn) шаг Update извлекает версию программного обеспечения на эту дату и время, чтобы множество клиентов выбрали общую версию для тестирования. В системах распределенного контроля версий это не определено, поэтому параметр игнорируется.

Сценарий CTest переменная: CTEST_NIGHTLY_START_TIME
CTest модульная переменная: NIGHTLY_START_TIME если установлено, иначе CTEST_NIGHTLY_START_TIME

Шаг CTest Configure

В сценарии CTest команда ctest_configure() выполняет этот шаг. Аргументы команды могут указать некоторые параметры шага.

Параметры настройки включают:

ConfigureCommand

Командная строка для запуска процесса конфигурации программного обеспечения. Она будет выполнена в расположении, указанном параметром BuildDirectory.

Сценарий CTest переменная: CTEST_CONFIGURE_COMMAND
CTest модульная переменная: CMAKE_COMMAND за которым следует PROJECT_SOURCE_DIR

LabelsForSubprojects

Укажите список меток, разделенных точкой с запятой, которые будут обрабатываться как подпроекты. Это отображение будет передано в CDash при отправке результатов конфигурации, тестирования или сборки.

Сценарий CTest переменная: CTEST_LABELS_FOR_SUBPROJECTS
CTest модульная переменная: CTEST_LABELS_FOR_SUBPROJECTS

См. Список меток и подпроектов.

Шаг CTest Build

В сценарии CTest команда ctest_build() выполняет этот шаг. Аргументы команды могут указать некоторые параметры шага.

Параметры настройки включают:

DefaultCTestConfigurationType

Когда система сборки, которая будет запущена, позволяет выбрать конфигурацию во время сборки (например, Debug, Release), это задаёт конфигурацию по умолчанию, которая будет собираться, если опция -C не задана для команды ctest. Значение будет подставлено в значение MakeCommand, заменив литеральную строку ${CTEST_CONFIGURATION_TYPE}, если она встречается.

Скрипт CTest переменная: CTEST_CONFIGURATION_TYPE
CTest модульная переменная: DEFAULT_CTEST_CONFIGURATION_TYPE, инициализируется переменной среды CMAKE_CONFIG_TYPE

LabelsForSubprojects

Укажите список меток, разделённых точкой с запятой, которые будут обрабатываться как подпроекты. Это отображение будет передано в CDash при отправке результатов конфигурации, тестирования или сборки.

Скрипт CTest переменная: CTEST_LABELS_FOR_SUBPROJECTS
CTest модульная переменная: CTEST_LABELS_FOR_SUBPROJECTS

См. Резюме меток и подпроектов.

MakeCommand

Команда для запуска процесса сборки программного обеспечения. Она будет выполнена в расположении, указанном настройкой BuildDirectory.

Скрипт CTest переменная: CTEST_BUILD_COMMAND
CTest модульная переменная: MAKECOMMAND, инициализируется командой build_command()

UseLaunchers

Для деревьев сборки, сгенерированных CMake с помощью одного из Генераторов Makefile или генератора Ninja, укажите, включена ли функция CTEST_USE_LAUNCHERS модулем CTestUseLaunchers (также включён модулем CTest). При включении сгенерированная система сборки оборачивает каждый вызов компилятора, компоновщика или пользовательской командной строки «загрузчиком», который взаимодействует с CTest через переменные среды и файлы для отчёта о детальных предупреждениях и ошибках сборки. В противном случае, CTest должен «извлекать» журнал вывода сборки для диагностики.

Скрипт CTest переменная: CTEST_USE_LAUNCHERS
CTest модульная переменная: CTEST_USE_LAUNCHERS

Шаг тестирования CTest

В скрипте CTest команда ctest_test() выполняет этот шаг. Аргументы команды могут задать некоторые параметры шага.

Параметры конфигурации включают:

ResourceSpecFile

Укажите файл спецификации ресурсов.

Скрипт CTest переменная: CTEST_RESOURCE_SPEC_FILE
CTest модульная переменная: CTEST_RESOURCE_SPEC_FILE

См. Распределение ресурсов для получения дополнительной информации.

LabelsForSubprojects

Скрипт CTest переменная: CTEST_LABELS_FOR_SUBPROJECTS
CTest модульная переменная: CTEST_LABELS_FOR_SUBPROJECTS

См. Резюме меток и подпроектов.

TestLoad

При одновременном запуске тестов (например, с помощью -j) старайтесь не запускать тесты, которые могут привести к превышению заданного порога загрузки процессора.

Скрипт CTest переменная: CTEST_TEST_LOAD
CTest модульная переменная: CTEST_TEST_LOAD

TimeOut

Тайм-аут по умолчанию для каждого теста, если он не указан свойством теста TIMEOUT.

Скрипт CTest переменная: CTEST_TEST_TIMEOUT
CTest модульная переменная: DART_TESTING_TIMEOUT

Шаг покрытия кода CTest

В скрипте CTest команда ctest_coverage() выполняет этот шаг. Аргументы команды могут задать некоторые параметры шага.

Параметры конфигурации включают:

CoverageCommand

Инструмент командной строки для выполнения анализа покрытия программного обеспечения. Он будет запущен в расположении, указанном настройкой BuildDirectory.

Скрипт CTest переменная: CTEST_COVERAGE_COMMAND
CTest модульная переменная: COVERAGE_COMMAND

CoverageExtraFlags

Укажите параметры командной строки для инструмента CoverageCommand.

Скрипт CTest переменная: CTEST_COVERAGE_EXTRA_FLAGS
CTest модульная переменная: COVERAGE_EXTRA_FLAGS

Эти параметры являются первыми аргументами, переданными инструменту CoverageCommand.

Шаг проверки памяти CTest

В скрипте CTest команда ctest_memcheck() выполняет этот шаг. Аргументы команды могут задать некоторые параметры шага.

Параметры конфигурации включают:

MemoryCheckCommand

Инструмент командной строки для выполнения динамического анализа. Команды тестирования будут запускаться через этот инструмент.

Сценарий CTest переменная: CTEST_MEMORYCHECK_COMMAND
CTest переменная модуля: MEMORYCHECK_COMMAND

MemoryCheckCommandOptions

Укажите параметры командной строки для инструмента MemoryCheckCommand. Они будут размещены перед командой запуска теста.

Сценарий CTest переменная: CTEST_MEMORYCHECK_COMMAND_OPTIONS
CTest переменная модуля: MEMORYCHECK_COMMAND_OPTIONS

MemoryCheckType

Укажите тип проверки памяти для выполнения.

Сценарий CTest переменная: CTEST_MEMORYCHECK_TYPE
CTest переменная модуля: MEMORYCHECK_TYPE

MemoryCheckSanitizerOptions

Укажите параметры санитайзеров при запуске сборки с поддержкой санитайзеров.

Сценарий CTest переменная: CTEST_MEMORYCHECK_SANITIZER_OPTIONS
CTest переменная модуля: MEMORYCHECK_SANITIZER_OPTIONS

MemoryCheckSuppressionFile

Укажите файл, содержащий правила подавления для инструмента MemoryCheckCommand. Он будет передан с параметрами, соответствующими инструменту.

Сценарий CTest переменная: CTEST_MEMORYCHECK_SUPPRESSIONS_FILE
CTest переменная модуля: MEMORYCHECK_SUPPRESSIONS_FILE

Дополнительные параметры конфигурации включают:

BoundsCheckerCommand

Укажите MemoryCheckCommand, известный своей совместимостью с командной строкой Bounds Checker.

Сценарий CTest переменная: none
CTest переменная модуля: none

PurifyCommand

Укажите MemoryCheckCommand, известный своей совместимостью с командной строкой Purify.

Сценарий CTest переменная: none
CTest переменная модуля: PURIFYCOMMAND

ValgrindCommand

Укажите MemoryCheckCommand, известный своей совместимостью с командной строкой Valgrind.

Сценарий CTest переменная: none
CTest переменная модуля: VALGRIND_COMMAND

ValgrindCommandOptions

Укажите параметры командной строки для инструмента ValgrindCommand. Они будут размещены перед командой запуска теста.

Сценарий CTest переменная: none
CTest переменная модуля: VALGRIND_COMMAND_OPTIONS

DrMemoryCommand

Укажите MemoryCheckCommand, известный своей совместимостью с командной строкой DrMemory.

Сценарий CTest переменная: none
CTest переменная модуля: DRMEMORY_COMMAND

DrMemoryCommandOptions

Укажите параметры командной строки для инструмента DrMemoryCommand. Они будут размещены перед командой запуска теста.

Сценарий CTest переменная: none
CTest переменная модуля: DRMEMORY_COMMAND_OPTIONS

CudaSanitizerCommand

Укажите MemoryCheckCommand, известный своей совместимостью с командной строкой cuda-memcheck или compute-sanitizer.

Сценарий CTest переменная: none
CTest переменная модуля: CUDA_SANITIZER_COMMAND

CudaSanitizerCommandOptions

Укажите параметры командной строки для инструмента CudaSanitizerCommand. Они будут размещены перед командой запуска теста.

Сценарий CTest переменная: none
CTest переменная модуля: CUDA_SANITIZER_COMMAND_OPTIONS

Шаг CTest Submit

В Сценарии CTest команда ctest_submit() выполняет этот шаг. Аргументы команды могут указать некоторые настройки шага.

Настройки конфигурации включают:

BuildName

Опишите платформу клиента панели мониторинга коротким текстом. (Операционная система, компилятор и т. д.)

Сценарий CTest переменная: CTEST_BUILD_NAME
CTest модуль переменная: BUILDNAME

CDashVersion

Запись устаревшего параметра. Не используется.

Сценарий CTest переменная: none, определено из сервера
CTest модуль переменная: CTEST_CDASH_VERSION

CTestSubmitRetryCount

Укажите количество попыток повторной отправки при ошибке сети.

Сценарий CTest переменная: none, используйте опцию ctest_submit() RETRY_COUNT.
CTest модуль переменная: CTEST_SUBMIT_RETRY_COUNT

CTestSubmitRetryDelay

Укажите задержку перед повторной отправкой при ошибке сети.

Сценарий CTest переменная: none, используйте опцию ctest_submit() RETRY_DELAY.
CTest модуль переменная: CTEST_SUBMIT_RETRY_DELAY

CurlOptions

Укажите список параметров, разделенных точкой с запятой, для управления библиотекой Curl, которую CTest использует для подключения к серверу. Возможные параметры — CURLOPT_SSL_VERIFYPEER_OFF и CURLOPT_SSL_VERIFYHOST_OFF.

Сценарий CTest переменная: CTEST_CURL_OPTIONS
CTest модуль переменная: CTEST_CURL_OPTIONS

DropLocation

Запись устаревшего параметра. Если SubmitURL не задан, он формируется из DropMethod, DropSiteUser, DropSitePassword, DropSite, и DropLocation.

Сценарий CTest переменная: CTEST_DROP_LOCATION
CTest модуль переменная: DROP_LOCATION если задано, иначе CTEST_DROP_LOCATION

DropMethod

Сценарий CTest переменная: CTEST_DROP_METHOD
CTest модуль переменная: DROP_METHOD если задано, иначе CTEST_DROP_METHOD

DropSite

Сценарий CTest переменная: CTEST_DROP_SITE
CTest модуль переменная: DROP_SITE если задано, иначе CTEST_DROP_SITE

DropSitePassword

Сценарий CTest переменная: CTEST_DROP_SITE_PASSWORD
CTest модуль переменная: DROP_SITE_PASSWORD если задано, иначе CTEST_DROP_SITE_PASWORD

DropSiteUser

Сценарий CTest переменная: CTEST_DROP_SITE_USER
CTest модуль переменная: DROP_SITE_USER если задано, иначе CTEST_DROP_SITE_USER

IsCDash

Запись устаревшего параметра. Не используется.

Сценарий CTest переменная: CTEST_DROP_SITE_CDASH
CTest модуль переменная: CTEST_DROP_SITE_CDASH

ScpCommand

Запись устаревшего параметра. Не используется.

Сценарий CTest переменная: CTEST_SCP_COMMAND
CTest модуль переменная: SCPCOMMAND

Site

Опишите хост-сайт клиента панели мониторинга коротким текстом. (Имя хоста, домен и т. д.)

Сценарий CTest переменная: CTEST_SITE
CTest модуль переменная: SITE, инициализируется командой site_name()

SubmitURL

Адрес URL сервера панели мониторинга http или https, для отправки результата.

Сценарий CTest переменная: CTEST_SUBMIT_URL
CTest модуль переменная: SUBMIT_URL если задано, иначе CTEST_SUBMIT_URL

TriggerSite

Запись устаревшего параметра. Не используется.

Сценарий CTest переменная: CTEST_TRIGGER_SITE
CTest модуль переменная: TRIGGER_SITE если задано, иначе CTEST_TRIGGER_SITE

Отобразить как JSON объект

При использовании опции командной строки --show-only=json-v1, информация о тесте выводится в формате JSON. Версия 1.0 модели JSON объекта определена следующим образом:

kind

Строка "ctestInfo".

version

Объект JSON, определяющий компоненты версии. Его члены:

major: Целое неотрицательное число, определяющее главный компонент версии.
minor: Целое неотрицательное число, определяющее второстепенный компонент версии.

backtraceGraph

Объект JSON, представляющий информацию о стеке вызовов с последующими членами:

commands

Список имён команд.

files

Список имён файлов.

nodes

Список узлов в формате JSON с членами:

command: Индекс в члене commands объекта backtraceGraph.
file: Индекс в члене files объекта backtraceGraph.
line: Номер строки в файле, где был добавлен стековый след.
parent: Индекс в члене nodes объекта backtraceGraph, представляющий родительский элемент в графе.

tests

Массив JSON, перечисляющий информацию о каждом тесте. Каждый элемент — объект JSON с членами:

name: Имя теста.
config: Настройка, на которой тест может выполняться. Пустая строка означает любую конфигурацию.
command: Список, где первый элемент — команда теста, а последующие элементы — аргументы команды.
backtrace: Индекс в члене nodes объекта backtraceGraph.
properties: Свойства теста. Может содержать ключи для каждого из поддерживаемых свойств теста.

Распределение ресурсов

CTest предоставляет механизм для тестов, позволяющий точно указывать необходимые ресурсы, и для пользователей — указывать доступные ресурсы на выполняемой машине. Это позволяет CTest отслеживать используемые и свободные ресурсы, планируя тесты таким образом, чтобы они не пытались затребовать недоступные ресурсы.

При использовании функции распределения ресурсов CTest не будет перераспределять ресурсы. Например, если у ресурса 8 слотов, CTest не будет запускать тесты, которые в совокупности используют более 8 слотов одновременно. Это ограничивает количество запускаемых тестов в любой момент, даже если используется большое значение аргумента -j, если эти тесты используют несколько слотов из одного ресурса. Кроме того, это означает, что отдельный тест, использующий больше ресурсов, чем доступно на машине, не будет запущен (и будет отображён как Not Run).

Типичный случай использования этой функции — тесты, требующие использования графического процессора (GPU). Несколько тестов могут одновременно выделять память из GPU, но если слишком много тестов попытаются сделать это одновременно, некоторые из них не смогут выделить память, что приведёт к провалу теста, даже если бы тест выполнился успешно при наличии необходимой памяти. Используя функцию распределения ресурсов, каждый тест может указать, сколько памяти ему требуется из GPU, позволяя CTest планировать тесты таким образом, чтобы запуск нескольких таких тестов одновременно не исчерпал пул памяти GPU.

Обратите внимание, что CTest не понимает, что такое GPU или сколько в нём памяти, и не имеет возможности взаимодействовать с GPU для получения этой информации или управления памятью. CTest просто отслеживает список абстрактных типов ресурсов, каждый из которых имеет определённое количество слотов, доступных для использования тестами. Каждый тест указывает количество слотов, которое ему требуется от определённого ресурса, и CTest планирует их так, чтобы общее количество используемых слотов не превышало указанную ёмкость. При выполнении теста и выделении слотов из ресурса для этого теста, тесты могут полагаться на то, что у них есть эксклюзивное использование этих слотов на всё время выполнения процесса теста.

Функция распределения ресурсов CTest состоит из двух входов:

Файл спецификации ресурсов (файл спецификации ресурсов), описанный ниже, который описывает доступные ресурсы в системе.
Свойство RESOURCE_GROUPS тестов, которое описывает необходимые ресурсы для теста.

При запуске теста CTest передает выделенные ресурсы в виде набора переменных среды, как описано ниже. Определение, к какому ресурсу подключаться, остается на усмотрение разработчика теста.

Свойство RESOURCE_GROUPS сообщает CTest, какие ресурсы ожидается использовать тестом, сгруппированные в смысле, понятном для теста. Сам тест должен прочитать переменные среды, чтобы определить, какие ресурсы были выделены для каждой группы. Например, каждая группа может соответствовать процессу, который запустит тест при выполнении.

Обратите внимание, что даже если тест указывает свойство RESOURCE_GROUPS, всё ещё возможно выполнение теста без распределения ресурсов (и без соответствующих переменных среды), если пользователь не передаёт файл спецификации ресурсов. Передача этого файла, либо через аргумент командной строки --resource-spec-file, либо аргумент RESOURCE_SPEC_FILE для ctest_test(), активирует функцию распределения ресурсов. Тесты должны проверить переменную среды CTEST_RESOURCE_GROUP_COUNT, чтобы узнать, активировано ли распределение ресурсов. Эта переменная всегда (и только) определена, если активировано распределение ресурсов. Если распределение ресурсов не активировано, переменная CTEST_RESOURCE_GROUP_COUNT не будет существовать, даже если она существует для родительского процесса ctest. Если тест обязательно требует распределения ресурсов, он может вернуть код ошибки, использовать свойства SKIP_RETURN_CODE или SKIP_REGULAR_EXPRESSION, чтобы указать пропущенный тест.

Файл спецификации ресурсов

Файл спецификации ресурсов — это файл JSON, передаваемый CTest, либо в командной строке ctest(1) в виде --resource-spec-file, либо в качестве аргумента RESOURCE_SPEC_FILE для ctest_test(). Если используется скрипт панели управления и RESOURCE_SPEC_FILE не указан, используется значение CTEST_RESOURCE_SPEC_FILE в скрипте панели управления. Если --resource-spec-file, RESOURCE_SPEC_FILE, и CTEST_RESOURCE_SPEC_FILE в скрипте панели управления не указаны, используется значение CTEST_RESOURCE_SPEC_FILE в файле CMake. Если ничто из этого не указано, файл спецификации ресурсов не используется.

Файл спецификации ресурсов должен быть объектом JSON. Все примеры в этом документе предполагают следующий файл спецификации ресурсов:

{
  "version": {
    "major": 1,
    "minor": 0
  },
  "local": [
    {
      "gpus": [
        {
          "id": "0",
          "slots": 2
        },
        {
          "id": "1",
          "slots": 4
        },
        {
          "id": "2",
          "slots": 2
        },
        {
          "id": "3"
        }
      ],
      "crypto_chips": [
        {
          "id": "card0",
          "slots": 4
        }
      ]
    }
  ]
}

Его члены:

version

Объект, содержащий поле major типа integer и поле minor типа integer. В настоящее время поддерживается только версия major 1, minor 0. Любое другое значение является ошибкой.

local

JSON-массив наборов ресурсов, присутствующих в системе. В настоящее время этот массив ограничен размером 1.

Каждый элемент массива — JSON-объект с членами, имена которых соответствуют требуемым типам ресурсов, например, gpus. Эти имена должны начинаться с маленькой буквы или символа нижнего подчеркивания, а последующие символы могут быть маленькими буквами, цифрами или символами нижнего подчеркивания. Заглавные буквы не допускаются, так как на некоторых платформах переменные окружения нечувствительны к регистру. Более подробную информацию см. в разделе «Переменные окружения» ниже. Рекомендуется, чтобы имя типа ресурса было множественным числом от существительного, например, gpus или crypto_chips (а не gpu или crypto_chip).

Обратите внимание, что имена gpus и crypto_chips — это всего лишь примеры, и CTest не интерпретирует их каким-либо образом. Вы можете самостоятельно придумать любые типы ресурсов, которые вам нужны.

Значение для каждого типа ресурса — JSON-массив, состоящий из JSON-объектов, каждый из которых описывает конкретный экземпляр указанного ресурса. Эти объекты имеют следующие члены:

id

Строка, содержащая идентификатор ресурса. Каждый символ в идентификаторе может быть маленькой буквой, цифрой или символом нижнего подчеркивания. Заглавные буквы не допускаются.

Идентификаторы должны быть уникальными в пределах одного типа ресурса. Однако они не обязательно должны быть уникальными по всем типам ресурсов. Например, допустимо иметь ресурс gpus с именем 0 и ресурс crypto_chips с именем 0, но не два ресурса gpus с одинаковым именем 0.

Обратите внимание, что идентификаторы 0, 1, 2, 3, и card0 — это всего лишь примеры, и CTest не интерпретирует их каким-либо образом. Вы можете самостоятельно придумать любые идентификаторы, которые вам нужны.

slots

Необязательное целое число без знака, определяющее количество доступных слотов на ресурсе. Например, это может быть количество мегабайт оперативной памяти на видеокарте или количество криптографических блоков, доступных на криптографическом чипе. Если slots не указано, используется значение по умолчанию 1.

В приведенном выше примере есть четыре видеокарты с идентификаторами от 0 до 3. Видеокарта 0 имеет 2 слота, видеокарта 1 — 4, видеокарта 2 — 2, а видеокарта 3 — 1 слот по умолчанию. Также есть один криптографический чип с 4 слотами.

`RESOURCE_GROUPS` Свойство

См. RESOURCE_GROUPS для описания этого свойства.

Переменные окружения

После того, как CTest определил, какие ресурсы нужно выделить для теста, он передает эту информацию исполняемому файлу теста в виде ряда переменных окружения. В каждом примере ниже мы будем предполагать, что у рассматриваемого теста есть свойство RESOURCE_GROUPS со значением 2,gpus:2;gpus:4,gpus:1,crypto_chips:2.

Следующие переменные передаются процессу теста:

CTEST_RESOURCE_GROUP_COUNT

Общее количество групп, указанных в свойстве RESOURCE_GROUPS. Например:

CTEST_RESOURCE_GROUP_COUNT=3

Эта переменная будет определена только в том случае, если ctest(1) был задан --resource-spec-file, или если ctest_test() был задан RESOURCE_SPEC_FILE. Если файл с указанием ресурсов не был задан, эта переменная не будет определена.

CTEST_RESOURCE_GROUP_<num>

Список типов ресурсов, выделенных для каждой группы, при этом каждый элемент разделен запятой. <num> — это число от нуля до CTEST_RESOURCE_GROUP_COUNT минус один. CTEST_RESOURCE_GROUP_<num> определено для каждого <num> в этом диапазоне. Например:

CTEST_RESOURCE_GROUP_0=gpus
CTEST_RESOURCE_GROUP_1=gpus
CTEST_RESOURCE_GROUP_2=crypto_chips,gpus

CTEST_RESOURCE_GROUP_<num>_<resource-type>

Список идентификаторов ресурсов и количества слотов каждого идентификатора, выделенных для каждой группы для данного типа ресурса. Эта переменная состоит из серии пар, каждая пара разделена точкой с запятой, а два элемента в паре разделены запятой. Первый элемент каждой пары — id:, за которым следует идентификатор ресурса типа <resource-type>, а второй элемент — slots: за которым следует количество слотов этого ресурса, выделенных для данной группы. Например:

CTEST_RESOURCE_GROUP_0_GPUS=id:0,slots:2
CTEST_RESOURCE_GROUP_1_GPUS=id:2,slots:2
CTEST_RESOURCE_GROUP_2_GPUS=id:1,slots:4;id:3,slots:1
CTEST_RESOURCE_GROUP_2_CRYPTO_CHIPS=id:card0,slots:2

В этом примере группа 0 получает 2 слота с видеокарты 0, группа 1 получает 2 слота с видеокарты 2, а группа 2 получает 4 слота с видеокарты 1, 1 слот с видеокарты 3, и 2 слота с криптографического чипа card0.

<num> — это число от нуля до CTEST_RESOURCE_GROUP_COUNT минус один. <resource-type> — это имя типа ресурса, преобразованное в верхний регистр. CTEST_RESOURCE_GROUP_<num>_<resource-type> определено для произведения каждого <num> в указанном диапазоне и каждого типа ресурса, указанного в CTEST_RESOURCE_GROUP_<num>.

Поскольку на некоторых платформах имена переменных окружения нечувствительны к регистру, имена типов ресурсов могут не конфликтовать в среде, нечувствительной к регистру. Из-за этого, для простоты, все типы ресурсов должны быть перечислены строчными буквами в файле указания ресурсов файле указания ресурсов и в свойстве RESOURCE_GROUPS, и они преобразуются в верхний регистр в переменной окружения CTEST_RESOURCE_GROUP_<num>_<resource-type>.

См. также

Для получения помощи при использовании CMake доступны следующие ресурсы:

Главная страница

https://cmake.org

Основная стартовая точка для изучения CMake.

Онлайн-документация и ресурсы сообщества

https://cmake.org/documentation

На этой веб-странице можно найти ссылки на доступную документацию и ресурсы сообщества.

Форум Discourse

https://discourse.cmake.org

На этом форуме Discourse проводятся обсуждения и задаются вопросы о CMake.

© 2000–2021 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.20/manual/ctest.1.html

ctest(1)

Краткое описание

Описание

Опции

Краткое описание меток и подпроектов

Режим сборки и тестирования

Клиент панели мониторинга

Шаги клиента панели мониторинга

Режимы работы клиента панели мониторинга

Клиент панели мониторинга через командную строку CTest

Клиент панели мониторинга через скрипт CTest

Настройки клиента панели мониторинга

Шаг запуска CTest

Шаг обновления CTest

Шаг CTest Configure

Шаг CTest Build

Шаг тестирования CTest

Шаг покрытия кода CTest

Шаг проверки памяти CTest

Шаг CTest Submit

Отобразить как JSON объект

Распределение ресурсов

Файл спецификации ресурсов

RESOURCE_GROUPS Свойство

Переменные окружения

См. также

`RESOURCE_GROUPS` Свойство