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

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

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