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 <jobs>, --parallel <jobs>

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

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

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

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

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

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

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

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

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

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

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

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

-U, --union

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

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

--rerun-failed

Выполнить только тесты, которые завершились ошибкой ранее.

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

--repeat <mode>:<n>

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

until-fail

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

until-pass

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

after-timeout

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

--repeat-until-fail <n>

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

--max-width <width>

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

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

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

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

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

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

--no-label-summary

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

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

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

--no-subproject-summary

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

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

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

--test-dir <dir>

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

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

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

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

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

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

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

--test-output-truncation <mode>

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

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

--overwrite

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

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

--force-new-ctest-process

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

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

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

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

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

--http1.0

Отправить с использованием HTTP 1.0.

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

--no-compress-output

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

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

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

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

Start

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

Update

Обновить дерево исходных файлов из системы управления версиями. Записать старые и новые версии и список обновлённых исходных файлов. См. раздел Шаг CTest Update ниже.

Configure

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

Build

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

Test

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

Coverage

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

MemCheck

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

Submit

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

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

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

Шаг CTest Start

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

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

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

BuildDirectory

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

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

SourceDirectory

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

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

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

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

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

BZRCommand

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

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

BZRUpdateOptions

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

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

CVSCommand

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

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

CVSUpdateOptions

Командная строка параметров для CVSCommand при обновлении исходного кода.

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

GITCommand

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

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

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

GITInitSubmodules

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

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

GITUpdateCustom

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

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

GITUpdateOptions

Командная строка параметров для GITCommand при обновлении исходного кода.

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

HGCommand

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

• Скрипт CTest переменная: CTEST_HG_COMMAND
• CTest модульная переменная: отсутствует

HGUpdateOptions

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

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

P4Client

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

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

P4Command

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

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

P4Options

Командная строка параметров для P4Command для всех вызовов.

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

P4UpdateCustom

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

• Скрипт CTest переменная: отсутствует
• CTest модульная переменная: CTEST_P4_UPDATE_CUSTOM

P4UpdateOptions

Командная строка параметров для P4Command при обновлении исходного кода.

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

SVNCommand

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

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

SVNOptions

Командная строка параметров для SVNCommand для всех вызовов.

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

SVNUpdateOptions

Командная строка параметров для SVNCommand при обновлении исходного кода.

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

UpdateCommand

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

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

UpdateOptions

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

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

UpdateType

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

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

UpdateVersionOnly

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

• Скрипт CTest переменная: CTEST_UPDATE_VERSION_ONLY

UpdateVersionOverride

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

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

• Скрипт CTest переменная: CTEST_UPDATE_VERSION_OVERRIDE

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

NightlyStartTime

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

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

Шаг CTest Configure

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

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

ConfigureCommand

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

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

LabelsForSubprojects

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

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

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

Шаг CTest Build

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

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

DefaultCTestConfigurationType

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

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

LabelsForSubprojects

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

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

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

MakeCommand

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

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

UseLaunchers

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

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

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

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

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

ResourceSpecFile

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

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

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

LabelsForSubprojects

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

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

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

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

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

SubmitInactivityTimeout

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

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

TriggerSite

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

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

Отображение в формате JSON-объекта

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

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

Обратите внимание, что CTest не знает, что такое видеокарта (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

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

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

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

См. также

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

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

https://cmake.org

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

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

https://cmake.org/documentation

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

Форум Discourse

https://discourse.cmake.org

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