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 не сохранено.

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