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