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]
                     [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
                     [PROPERTIES name1 value1...]
                     [TEST_LIST var]
                     [DISCOVERY_TIMEOUT seconds]
)

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 могут быть указаны.

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

Указывает, сколько времени (в секундах) 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 не сохранялись.