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