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, что обычно приводило к правомерному, но нежелательному поведению. В CMake 3.10.3 ключевое слово было изменено на DISCOVERY_TIMEOUT, чтобы решить эту проблему. Неясно определённое поведение ключевого слова TIMEOUT в версиях 3.10.1 и 3.10.2 не сохранялось.

© 2000–2020 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.15/module/GoogleTest.html