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

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