GoogleTest

Этот модуль определяет функции для работы с инфраструктурой Google Test. Предоставляются два механизма для добавления тестов. gtest_add_tests() существует уже некоторое время, первоначально через find_package(GTest). gtest_discover_tests() был представлен в CMake 3.10.

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

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

Дополнительные сведения можно найти в документации соответствующих функций.

Обе команды предназначены для замены использования add_test() для регистрации тестов и создадут отдельный тест CTest для каждого тестового случая Google Test. Обратите внимание, что в некоторых случаях это менее эффективно, так как общую логику подготовки и завершения нельзя разделить между несколькими тестовыми случаями, выполняющимися в одном экземпляре. Однако это предоставляет более подробную информацию о прохождении/непрохождении в CTest, что обычно считается более полезным. По умолчанию имя теста CTest совпадает с именем Google Test (т. е. suite.testcase); см. также TEST_PREFIX и TEST_SUFFIX.

gtest_add_tests

Автоматически добавляет тесты с помощью CTest, сканируя исходный код на наличие макросов Google Test:

gtest_add_tests(TARGET target
                [SOURCES src1...]
                [EXTRA_ARGS arg1...]
                [WORKING_DIRECTORY dir]
                [TEST_PREFIX prefix]
                [TEST_SUFFIX suffix]
                [SKIP_DEPENDENCY]
                [TEST_LIST outVar]
)

gtest_add_tests пытается найти тесты, сканируя исходные файлы. Хотя это в целом эффективно, он использует только базовую регулярную выражение, что может быть обойдено нестандартными объявлениями тестов, и не может полностью «разделить» параметризованные тесты. Кроме того, для обнаружения любых новых, удалённых или переименованных тестов требуется повторный запуск CMake (по умолчанию это означает, что CMake перезапускается при изменении любого файла исходного кода тестов, но см. SKIP_DEPENDENCY). Однако у него есть преимущество в объявлении тестов на этапе CMake, что несколько упрощает установку дополнительных свойств тестов, и он всегда работает в кросс-компилируемой среде.

Параметры:

TARGET target

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

SOURCES src1...

Если указано, будут сканироваться только перечисленные файлы на предмет тестовых случаев. Если этот параметр не задан, будет использовано свойство SOURCES указанной target для получения списка источников.

EXTRA_ARGS arg1...

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

WORKING_DIRECTORY dir

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

TEST_PREFIX prefix

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

TEST_SUFFIX suffix

Аналогично TEST_PREFIX за исключением того, что suffix добавляется к имени каждого обнаруженного тестового случая. Можно указать как TEST_PREFIX так и TEST_SUFFIX.

SKIP_DEPENDENCY

Обычно функция создаёт зависимость, которая заставляет CMake перезапускаться, если какие-либо из сканируемых источников изменены. Это гарантирует обновление списка обнаруженных тестов. Если этого поведения не требуется (например, при написании самих тестовых случаев), этот параметр можно использовать для предотвращения добавления зависимости.

TEST_LIST outVar

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

Пример использования:

include(GoogleTest)
add_executable(FooTest FooUnitTest.cxx)
gtest_add_tests(TARGET      FooTest
                TEST_SUFFIX .noArgs
                TEST_LIST   noArgsTests
)
gtest_add_tests(TARGET      FooTest
                EXTRA_ARGS  --someArg someValue
                TEST_SUFFIX .withArgs
                TEST_LIST   withArgsTests
)
set_tests_properties(${noArgsTests}   PROPERTIES TIMEOUT 10)
set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)

Для обратной совместимости поддерживается следующая форма:

gtest_add_tests(exe args files...)

exe

Путь к исполняемому файлу теста или имя целевой задачи CMake.

args

Список дополнительных аргументов для передачи исполняемому файлу. Весь список должен передаваться как один аргумент. Заключите его в кавычки или передайте "" для отсутствия аргументов.

files...

Список исходных файлов для поиска тестов и тестовых фикстур. В качестве альтернативы используйте AUTO для указания того, что exe — это имя целевой задачи CMake, исходные коды которой следует сканировать.

include(GoogleTest)
set(FooTestArgs --foo 1 --bar 2)
add_executable(FooTest FooUnitTest.cxx)
gtest_add_tests(FooTest "${FooTestArgs}" AUTO)

gtest_discover_tests

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

gtest_discover_tests(target
                     [EXTRA_ARGS arg1...]
                     [WORKING_DIRECTORY dir]
                     [TEST_PREFIX prefix]
                     [TEST_SUFFIX suffix]
                     [TEST_FILTER expr]
                     [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
                     [PROPERTIES name1 value1...]
                     [TEST_LIST var]
                     [DISCOVERY_TIMEOUT seconds]
                     [XML_OUTPUT_DIR dir]
                     [DISCOVERY_MODE <POST_BUILD|PRE_TEST>]
)

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

gtest_discover_tests() настраивает команду после сборки для исполняемого файла теста, которая генерирует список тестов, анализируя вывод от запуска теста с аргументом --gtest_list_tests. По сравнению с подходом анализа исходного кода в gtest_add_tests(), это гарантирует получение полного списка тестов, включая экземпляры параметризованных тестов. Поскольку обнаружение тестов происходит на этапе сборки, повторный запуск CMake при изменении списка тестов не требуется. Однако это требует, чтобы CROSSCOMPILING_EMULATOR было должным образом настроено для работы в среде кросс-компиляции.

Кроме того, настройка свойств тестов несколько менее удобна, так как тесты недоступны во время CMake. Дополнительные свойства тестов могут быть назначены всему набору тестов с помощью параметра PROPERTIES. Если требуется более точный контроль над тестами, пользовательский контент может быть предоставлен через внешний скрипт CTest с помощью свойства каталога TEST_INCLUDE_FILES. Набор обнаруженных тестов становится доступным для такого скрипта через переменную <target>_TESTS.

Параметры:

target

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

EXTRA_ARGS arg1...

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

WORKING_DIRECTORY dir

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

TEST_PREFIX prefix

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

TEST_SUFFIX suffix

Аналогично TEST_PREFIX , за исключением того, что suffix добавляется к имени каждого обнаруженного тестового случая. Можно указать как TEST_PREFIX, так и TEST_SUFFIX.

TEST_FILTER expr

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

Выражение фильтра для передачи в качестве аргумента --gtest_filter во время обнаружения тестов. Обратите внимание, что выражение имеет формат с подстановкой, который соответствует исходным именам тестов, используемым gtest. Для тестов с параметрами типа или значения эти имена могут отличаться от потенциально красиво отформатированных имён тестов, которые использует ctest.

NO_PRETTY_TYPES

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

NO_PRETTY_VALUES

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

PROPERTIES name1 value1...

Указывает дополнительные свойства, которые должны быть установлены для всех тестов, обнаруженных этим вызовом gtest_discover_tests().

TEST_LIST var

Сделать список тестов доступным в переменной var, а не в <target>_TESTS, значение по умолчанию. Это может быть полезно, когда один и тот же исполняемый файл теста используется в нескольких вызовах gtest_discover_tests() . Обратите внимание, что эта переменная доступна только в CTest.

DISCOVERY_TIMEOUT num

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

Указывает, сколько времени (в секундах) CMake будет ожидать, пока тест перечислит доступные тесты. Если тест занимает больше времени, чем это, обнаружение (и ваша сборка) завершатся ошибкой. Большинство исполняемых файлов тестов перечисляют свои тесты очень быстро, но в некоторых исключительных случаях тест может потребовать более длительного таймаута. Значение по умолчанию равно 5. См. также параметр TIMEOUT в execute_process().

Примечание

В версиях CMake 3.10.1 и 3.10.2 этот параметр назывался TIMEOUT. Это вступало в конфликт со свойством теста TIMEOUT, которое является одним из общих свойств, которое устанавливалось с ключевым словом PROPERTIES, что обычно приводило к юридически верному, но непреднамеренному поведению. Ключевое слово было изменено на DISCOVERY_TIMEOUT в CMake 3.10.3 для решения этой проблемы. Не сохранено двусмысленное поведение ключевого слова TIMEOUT в 3.10.1 и 3.10.2.

XML_OUTPUT_DIR dir

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

При указании параметр передаётся вместе с --gtest_output=xml: исполняемому файлу теста. Фактическое имя файла совпадает с именем целевого файла теста, включая префикс и суффикс. Это следует использовать вместо EXTRA_ARGS --gtest_output=xml для предотвращения гонок при записи XML-вывода результатов при использовании параллельного выполнения тестов.

DISCOVERY_MODE

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

Обеспечивает больший контроль над временем, когда gtest_discover_tests() выполняет обнаружение тестов. По умолчанию POST_BUILD настраивает команду после сборки для выполнения обнаружения тестов во время сборки. В некоторых сценариях, таких как кросс-компиляция, это поведение POST_BUILD нежелательно. В отличие от этого, PRE_TEST откладывает обнаружение тестов до непосредственного выполнения теста. Таким образом, обнаружение тестов происходит в целевой среде, где у теста больше шансов найти соответствующие зависимости выполнения.

DISCOVERY_MODE по умолчанию принимает значение переменной CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE , если оно не указано при вызове gtest_discover_tests(). Это предоставляет механизм для глобального выбора предпочтительного поведения обнаружения тестов без необходимости изменения каждого места вызова.