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