ctest(1)

• Синопсис
• Описание
• Опции
• Резюме метки и подпроектов
• Режим сборки и тестирования

• Клиент панели управления

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

• Настройка клиента панели управления

  • Шаг запуска CTest
  • Шаг обновления CTest
  • Шаг конфигурации CTest
  • Шаг сборки CTest
  • Шаг тестирования CTest
  • Шаг покрытия кода CTest
  • Шаг проверки памяти CTest
  • Шаг отправки CTest
• Отображение в формате JSON Object Model

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

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

Синопсис

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

Описание

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

Опции

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

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

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

-Q,--quiet

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

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

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

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

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

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

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

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

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

human

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

json-v1

Вывести информацию о тесте в формате JSON. См. Модель отображения в формате JSON.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

-U, --union

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

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

--rerun-failed

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

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

--repeat <mode>:<n>

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

until-fail

Требуется, чтобы каждый тест выполнялся <n> раз без сбоев, чтобы пройти. Это полезно для обнаружения спорадических сбоев в тестовых сценариях.

until-pass

Разрешить каждому тесту выполняться до <n> раз, чтобы пройти. Повторять тесты, если они завершаются сбоем по любой причине. Это полезно для того, чтобы терпеть спорадические сбои в тестовых сценариях.

after-timeout

Разрешить каждому тесту выполняться до <n> раз, чтобы пройти. Повторять тесты только если они завершаются по таймауту. Это полезно для того, чтобы терпеть спорадические таймауты в тестовых сценариях на загруженных машинах.

--repeat-until-fail <n>

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

--max-width <width>

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

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

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

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

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

--no-label-summary

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

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

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

--no-subproject-summary

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

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

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

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

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

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

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

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

--overwrite

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

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

--force-new-ctest-process

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

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

--schedule-random

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

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

--submit-index

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

--timeout <seconds>

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

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

--stop-time <time>

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

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

--print-labels

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

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

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

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

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

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

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

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

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

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

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

--help-full [<f>]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

--help-commands [<f>]

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

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

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

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

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

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

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

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

--help-modules [<f>]

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

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

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

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

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

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

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

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

--help-policies [<f>]

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

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

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

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

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

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

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

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

--help-properties [<f>]

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

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

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

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

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

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

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

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

--help-variables [<f>]

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

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

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

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

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

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

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

for labels/subprojects j=1...total

где:

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

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

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

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

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

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

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

--build-target

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

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

--build-nocmake

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

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

--build-run-dir

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

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

--build-two-config

Запустить CMake дважды.

--build-exe-dir

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

--build-generator

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

--build-generator-platform

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

--build-generator-toolset

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

--build-project

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

--build-makeprogram

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

--build-noclean

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

--build-config-sample

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

--build-options

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

--test-command

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

--test-timeout

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

Клиент панели управления

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

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

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

--group <group>

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

Отправка панели управления в указанную группу вместо стандартной. По умолчанию панель управления отправляется в группы «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

Настроить программное обеспечение, запустив команду в дереве сборки. Записать журнал конфигурации.

Build

Собрать программное обеспечение, выполнив команду в дереве сборки. Записать журнал сборки и выявить предупреждения и ошибки.

Test

Протестировать программное обеспечение, загрузив CTestTestfile.cmake из дерева сборки и выполнив определенные тесты. Записать выходные данные и результат каждого теста.

Coverage

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

MemCheck

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

Submit

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

Режимы работы клиента панели управления

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

Конфигурация клиента панели мониторинга

Этапы клиента панели мониторинга Dashboard Client Steps могут быть сконфигурированы с помощью именованных настроек, как документировано в следующих разделах.

Шаг запуска CTest

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

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

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

BuildDirectory

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

• Переменная сценария CTest: CTEST_BINARY_DIRECTORY
• Переменная модуля CTest: PROJECT_BINARY_DIR

SourceDirectory

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

• Переменная сценария CTest: CTEST_SOURCE_DIRECTORY
• Переменная модуля CTest: PROJECT_SOURCE_DIR

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

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

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

BZRCommand

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

• Скрипт CTest переменная: CTEST_BZR_COMMAND
• CTest переменная модуля: none

BZRUpdateOptions

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

• Скрипт CTest переменная: CTEST_BZR_UPDATE_OPTIONS
• CTest переменная модуля: none

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 переменная модуля: none

HGUpdateOptions

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

• Скрипт CTest переменная: CTEST_HG_UPDATE_OPTIONS
• CTest переменная модуля: none

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 переменная: none
• 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

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

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

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

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

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

CoverageCommand

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

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

CoverageExtraFlags

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

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

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

Шаг CTest 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 переменная: 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

CudaMemcheckCommand

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

• Скрипт CTest переменная: none
• CTest переменная модуля: CUDA_MEMCHECK_COMMAND

CudaMemcheckCommandOptions

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

• Скрипт CTest переменная: none
• CTest переменная модуля: CUDA_MEMCHECK_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

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

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

DropLocation

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

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

DropMethod

Устаревшая опция. Если 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

TriggerSite

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

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

Показать как JSON Объектную Модель

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

kind

Строка “ctestInfo”.

version

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

major

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

minor

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

backtraceGraph

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

commands

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

files

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

nodes

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

command

Индекс в члене commands объекта backtraceGraph.

file

Индекс в члене files объекта backtraceGraph.

line

Номер строки в файле, где была добавлена информация о трассировке стека.

parent

Индекс в члене nodes объекта backtraceGraph, представляющий родительский узел в графе.

tests

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

name

Имя теста.

config

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

command

Список, где первый элемент — команда теста, а последующие — аргументы команды.

backtrace

Индекс в члене nodes объекта backtraceGraph.

properties

Свойства теста. Может содержать ключи для каждого поддерживаемого свойства теста.

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

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

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

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

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

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

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

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

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

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

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

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

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

local

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

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

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

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

id

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

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

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

slots

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

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

RESOURCE_GROUPS Свойство

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

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

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

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

CTEST_RESOURCE_GROUP_COUNT

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

• CTEST_RESOURCE_GROUP_COUNT=3

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

CTEST_RESOURCE_GROUP_<num>

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

• CTEST_RESOURCE_GROUP_0=gpus
• CTEST_RESOURCE_GROUP_1=gpus
• CTEST_RESOURCE_GROUP_2=crypto_chips,gpus

CTEST_RESOURCE_GROUP_<num>_<resource-type>

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

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

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

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

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

См. также

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

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

https://cmake.org

Основная точка входа для обучения по CMake.

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

https://cmake.org/documentation

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

Форум Discourse

https://discourse.cmake.org

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