ctest(1)

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

Синопсис

Run Tests
 ctest [<options>] [--test-dir <path-to-build>]

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

Dashboard Client
 ctest -D <dashboard>         [-- <dashboard-options>...]
 ctest -M <model> -T <action> [-- <dashboard-options>...]
 ctest -S <script>            [-- <dashboard-options>...]
 ctest -SP <script>           [-- <dashboard-options>...]

View Help
 ctest --help[-<topic>]

Описание

Исполняемый файл 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

Включить переключение.

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

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

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

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

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

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

--resource-spec-file <file>

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

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

--test-load <level>

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

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

-Q, --quiet

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

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

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

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

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

--output-junit <file>

Новый в версии 3.21.

Запись результатов тестов в формате JUnit.

Этот параметр сообщает CTest записывать результаты тестов в <file> в формате XML JUnit. Если <file> уже существует, он будет перезаписан. При использовании параметра -S для запуска скрипта панели управления используйте ключевое слово OUTPUT_JUNIT с командой ctest_test().

END_OF_DOCUMENT_MARKER

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

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

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

Добавлена в версии 3.14: Параметр --show-only принимает значение <format>.

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

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

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

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

Этот параметр указывает CTest на запуск только тех тестов, метки которых соответствуют заданному регулярному выражению. При использовании нескольких параметров -L, тест будет запущен только в том случае, если каждое регулярное выражение соответствует хотя бы одной метке теста (т. е. несколько меток -L образуют отношение AND). См. Сопоставление меток.

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

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

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

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

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

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

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

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

Этот параметр указывает CTest на НЕ запуск тестов, метки которых соответствуют заданному регулярному выражению. При использовании нескольких параметров -LE, тест будет исключен только в том случае, если каждое регулярное выражение соответствует хотя бы одной метке теста (т. е. несколько меток -LE образуют отношение AND). См. Сопоставление меток.

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

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

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

-FS <regex>, --fixture-exclude-setup <regex>: То же, что и -FA, но исключаются только соответствующие тесты настройки.

-FC <regex>, --fixture-exclude-cleanup <regex>: То же, что и -FA, но исключаются только соответствующие тесты завершения.

-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 запускать тесты в интерактивном или неинтерактивном режиме. В режиме панели мониторинга (Experimental, Nightly, Continuous) по умолчанию используется неинтерактивный режим. В неинтерактивном режиме переменная среды DASHBOARD_TEST_FROM_CTEST устанавливается.

До CMake 3.11 интерактивный режим в Windows позволял отображать системные всплывающие окна отладки. Теперь, из-за использования CTest libuv для запуска процессов тестирования, все системные всплывающие окна отладки всегда блокируются.

--no-label-summary

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

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

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

--no-subproject-summary

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

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

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

--test-dir <dir>: Указать каталог, в котором следует искать тесты, обычно каталог построения проекта CMake. Если не указано, используется текущий каталог.

--test-output-size-passed <size>: Добавлена в версии 3.4.

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

--test-output-size-failed <size>: Добавлена в версии 3.4.

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

--test-output-truncation <mode>: Добавлена в версии 3.24.

Обрезать tail (по умолчанию), middle или head вывода теста после достижения максимального размера вывода.

--overwrite

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

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

--force-new-ctest-process

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

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

END_OF_DOCUMENT_MARKER

--schedule-random

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

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

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

--timeout <seconds>

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

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

--stop-time <time>

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

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

--print-labels

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

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

--no-tests=<action>

Рассматривать отсутствие тестов либо как ошибку (когда <action> установлено в error) либо игнорировать (когда <action> установлено в ignore).

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

Новое в версии 3.26.

Этот параметр также может быть установлен, установив переменную окружения CTEST_NO_TESTS_ACTION.

View Help

Чтобы вывести информацию о версии или выбранные страницы из документации CMake, используйте один из следующих параметров:

-version [<file>], --version [<file>], /V [<file>]: Показать заголовок программы/версии и выйти. Вывод выводится в указанный <file> файл, если задан.

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

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

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

--help-full [<file>]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

--help-commands [<file>]

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

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

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

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

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

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

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

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

--help-modules [<file>]

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

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

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

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

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

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

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

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

--help-policies [<file>]

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

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

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

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

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

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

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

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

--help-properties [<file>]

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

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

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

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

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

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

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

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

--help-variables [<file>]

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

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

Сопоставление меток

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

При использовании -L, для того чтобы тест был включен в выполнение теста, каждое регулярное выражение должно соответствовать хотя бы одной метке. Использование более одного параметра -L означает «соответствие всем этим».

Параметр -LE работает так же, как -L, но исключает тесты, а не включает их. Тест исключается, если каждое регулярное выражение соответствует хотя бы одной метке.

END_OF_DOCUMENT_MARKER

Если к тесту нет прикрепленных меток, то -L никогда не включит этот тест, и -LE никогда не исключит этот тест. В качестве примера тестов с метками рассмотрим пять тестов с следующими метками:

test1 имеет метки tuesday и production
test2 имеет метки tuesday и test
test3 имеет метки wednesday и production
test4 имеет метку wednesday
test5 имеет метки friday и test

Запуск ctest с -L tuesday -L test выберет test2, у которого есть обе метки. Запуск CTest с -L test выберет test2 и test5, потому что у обоих есть метка, соответствующая этому регулярному выражению.

Поскольку соответствие работает с регулярными выражениями, обратите внимание, что запуск CTest с -L es будет соответствовать всем пяти тестам. Для выбора тестов tuesday и wednesday вместе используйте одно регулярное выражение, которое соответствует любому из них, например -L "tue|wed".

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

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

Новое в версии 3.22: Динамически добавленные метки во время выполнения теста также будут отображаться в сводке по времени. См. Дополнительные метки.

Когда свойство теста 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 раз больше времени CPU/ядра на выполнение тестов для 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-and-test: Переключение в режим сборки и тестирования.

--build-target

Указывает конкретную цель для сборки. Параметр можно указать несколько раз с различными целями, в этом случае каждая цель собирается по очереди. Очистка будет выполнена перед сборкой каждой цели, если не задан параметр --build-noclean.

Если цель --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.

--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>         [-- <dashboard-options>...]
ctest -M <model> -T <action> [-- <dashboard-options>...]
ctest -S <script>            [-- <dashboard-options>...]
ctest -SP <script>           [-- <dashboard-options>...]

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

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

Выполнение теста панели мониторинга.

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

Если <dashboard> не является одним из распознанных значений <Mode><Test>, это будет рассматриваться как определение переменной (см. dashboard-options ниже).

-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 с соответствующими параметрами.

END_OF_DOCUMENT_MARKER ```

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

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

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

Доступные <dashboard-options> следующие:

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

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

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

--group <group>

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

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

Заменяет устаревший параметр --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 Script команда ctest_start() выполняет этот шаг. Аргументы команды могут указывать некоторые настройки шага. Сначала команда выполняет указанную в командной строке команду переменной CTEST_CHECKOUT_COMMAND, если она установлена, чтобы инициализировать директорию исходного кода.

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

BuildDirectory

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

Переменная CTest Script: CTEST_BINARY_DIRECTORY
Переменная модуля CTest: PROJECT_BINARY_DIR

SourceDirectory

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

Переменная CTest Script: CTEST_SOURCE_DIRECTORY
Переменная модуля CTest: PROJECT_SOURCE_DIR

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

В скрипте CTest Script команда 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

В скрипте 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

В скрипте 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

Скрипт 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

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

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

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

TestLoad

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

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

TimeOut

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

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

Чтобы отправить дополнительные значения тестов в CDash, см. Дополнительные измерения тестов.

Шаг CTest Coverage

В скрипте 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 MemCheck

В скрипте 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 Script переменная: none
CTest модульная переменная: none

PurifyCommand

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

CTest Script переменная: none
CTest модульная переменная: PURIFYCOMMAND

ValgrindCommand

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

CTest Script переменная: none
CTest модульная переменная: VALGRIND_COMMAND

ValgrindCommandOptions

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

CTest Script переменная: none
CTest модульная переменная: VALGRIND_COMMAND_OPTIONS

DrMemoryCommand

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

CTest Script переменная: none
CTest модульная переменная: DRMEMORY_COMMAND

DrMemoryCommandOptions

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

CTest Script переменная: none
CTest модульная переменная: DRMEMORY_COMMAND_OPTIONS

CudaSanitizerCommand

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

CTest Script переменная: none
CTest модульная переменная: CUDA_SANITIZER_COMMAND

CudaSanitizerCommandOptions

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

CTest Script переменная: none
CTest модульная переменная: CUDA_SANITIZER_COMMAND_OPTIONS

Шаг CTest Submit

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

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

BuildName

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

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

CDashVersion

Устаревшая опция. Не используется.

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

CTestSubmitRetryCount

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

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

CTestSubmitRetryDelay

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

Сценарий CTest переменная: ни одна, используйте опцию 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