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