ctest(1)

• Синтаксис
• Описание
• Запуск тестов
• Просмотр справки
• Сопоставление меток
• Сводка меток и подпроектов
• Режим сборки и тестирования

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

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

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

  • Шаг запуска CTest
  • Шаг обновления CTest
  • Шаг конфигурирования CTest
  • Шаг сборки CTest
  • Шаг тестирования CTest
  • Шаг покрытия кода CTest
  • Шаг проверки памяти CTest
  • Шаг отправки CTest
• Показать в виде JSON-объектной модели

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

  • Файл спецификации ресурсов
  • RESOURCE_GROUPS Свойство
  • Переменные среды
  • Динамически сгенерированный файл спецификации ресурсов
• Интеграция с сервером задач
• См. также

Синтаксис

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 [<level>], --parallel [<level>]

Запуск тестов параллельно, необязательно ограничив уровень параллелизма.

Добавлено в версии 3.29: <level> может быть опущено, или 0, в этом случае:

• В Интеграции с сервером задач параллелизм ограничен доступными токенами задач.
• В противном случае, если значение опущено, параллелизм ограничен количеством процессоров или 2, что больше.
• В противном случае, если значение 0, параллелизм не ограничен.

Этот параметр также может быть задан переменной среды CTEST_PARALLEL_LEVEL.

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

--resource-spec-file <file>

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

При запуске ctest как клиента панели мониторинга это устанавливает параметр ResourceSpecFile шага CTest Test Step.

--test-load <level>

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

При запуске ctest как клиента панели мониторинга это устанавливает параметр TestLoad шага CTest Test Step.

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

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

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

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

Новые возможности версии 3.14: Параметр --show-only принимает значение <format>.

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

human

Выход в удобном для восприятия формате. Не гарантируется стабильность. Это значение по умолчанию.

json-v1

Вывести информацию о тесте в формате JSON. См. Показать в формате JSON.

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

Запускать тесты с метками, соответствующими регулярному выражению, как описано в string(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). См. Сопоставление меток.

--tests-from-file <filename>

Новые возможности версии 3.29.

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

Этот параметр указывает CTest на запуск тестов, перечисленных в указанном файле. Файл должен содержать одно точное имя теста на строку. Строки, не точно соответствующие ни одному имени теста, игнорируются. Этот параметр можно комбинировать с другими параметрами, такими как -R, -E, -L или -LE.

--exclude-from-file <filename>

Новые возможности версии 3.29.

Исключить тесты, перечисленные в указанном файле.

Этот параметр указывает CTest на НЕ запуск тестов, перечисленных в указанном файле. Файл должен содержать одно точное имя теста на строку. Строки, не точно соответствующие ни одному имени теста, игнорируются. Этот параметр можно комбинировать с другими параметрами, такими как -R, -E, -L или -LE.

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

Введено в версии 3.20.

Укажите каталог, в котором следует искать тесты, обычно каталог сборки проекта 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 в новых процессах.

--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 <keyword> [<file>]

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

<keyword> может быть свойством, переменной, командой, политикой, генератором или модулем.

Соответствующая запись справки по <keyword> выводится в читаемом формате. Вывод выводится в указанный <file> файл.

Изменено в версии 3.28: До CMake 3.28 этот параметр поддерживал только имена команд.

--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, но исключает тесты, а не включает их. Тест исключается, если каждое регулярное выражение соответствует хотя бы одной метке.

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

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

-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>]

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

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

--http-header <header>

Введено в версии 3.29.

Добавить заголовок HTTP при отправке на панель мониторинга.

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

--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 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), это указывает на стандартную конфигурацию, которая будет собрана, если к команде ctest не указан параметр -C. Значение будет подставлено в значение 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

Укажите список меток, разделённых точкой с запятой, которые будут обрабатываться как подпроекты. Это отображение будет передано в 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

В скрипте 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 переменная: отсутствует, определяется по серверу
• 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

Устарело начиная с версии 3.30: Используйте TLSVerify вместо этого.

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

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

Возможные параметры:

CURLOPT_SSL_VERIFYPEER_OFF

Отключить опцию curl CURLOPT_SSL_VERIFYPEER.

CURLOPT_SSL_VERIFYHOST_OFF

Отключить опцию curl CURLOPT_SSL_VERIFYHOST.

DropLocation

Устаревшая опция. Если SubmitURL не задано, оно строится из DropMethod, DropSiteUser, DropSitePassword, DropSite, и DropLocation.

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

DropMethod

Устаревшая опция. Если SubmitURL не задано, оно строится из DropMethod, DropSiteUser, DropSitePassword, DropSite, и DropLocation.

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

DropSite

Устаревшая опция. Если SubmitURL не задано, оно строится из DropMethod, DropSiteUser, DropSitePassword, DropSite, и DropLocation.

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

DropSitePassword

Устаревшая опция. Если SubmitURL не задано, оно строится из DropMethod, DropSiteUser, DropSitePassword, DropSite, и DropLocation.

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

DropSiteUser

Устаревшая опция. Если SubmitURL не задано, оно строится из DropMethod, DropSiteUser, DropSitePassword, DropSite, и DropLocation.

• Сценарий 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

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

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

SubmitInactivityTimeout

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

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

TLSVersion

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

Укажите минимальную версию TLS, разрешенную при отправке на панель мониторинга через https:// URL.

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

TLSVerify

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

Укажите булево значение, определяющее, нужно ли проверять сертификат сервера при отправке на панель управления через https:// URL-адреса.

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

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 --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 целого типа и поле minor целого типа. В настоящее время поддерживается только версия 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

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

В примере файла выше четыре GPU с идентификаторами от 0 до 3. GPU 0 имеет 2 слота, GPU 1 — 4, GPU 2 — 2, а GPU 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 слота от GPU 0, группе 1 — 2 слота от GPU 2, а группе 2 — 4 слота от GPU 1, 1 слот от GPU 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>.

Динамически генерируемый файл задания ресурсов

Проект может необязательно указать единственный тест, который будет использоваться для динамической генерации файла задания ресурсов, который CTest будет использовать для планирования тестов, использующих ресурсы. Тест, который генерирует файл, должен иметь свойство GENERATED_RESOURCE_SPEC_FILE, и должен иметь ровно один фикстур в своём свойстве FIXTURES_SETUP. Эта фикстура считается CTest имеющей специальное значение: это фикстура, которая генерирует файл задания ресурсов. Фикстура может иметь любое имя. Если такая фикстура существует, все тесты, у которых установлено свойство RESOURCE_GROUPS, должны иметь эту фикстуру в своём свойстве FIXTURES_REQUIRED, и файл задания ресурсов не может быть указан с аргументом --resource-spec-file или переменной CTEST_RESOURCE_SPEC_FILE.

Интеграция с сервером задач

В системах POSIX при запуске в контексте сервера задач CTest разделяет свои слоты задач. Это независимо от свойства теста PROCESSORS, которое всё ещё учитывается параллельным уровнем CTest -j. CTest получает ровно один токен от сервера задач перед запуском каждого теста и возвращает его по завершении теста.

Например, рассмотрим Makefile:

test:
	+ctest -j 8

При вызове с помощью make -j 2 test, ctest подключается к серверу задач, получает токен для каждого теста и запускает не более 2 тестов одновременно.

В системах Windows интеграция с сервером задач пока не реализована.

См. также

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

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

https://cmake.org

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

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

https://cmake.org/documentation

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

Форум Discourse

https://discourse.cmake.org

Форум Discourse предоставляет площадку для обсуждения и вопросов о CMake.