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]
                     [XML_OUTPUT_DIR dir]
                     [DISCOVERY_MODE <POST_BUILD|PRE_TEST>]
)

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

XML_OUTPUT_DIR dir

Если указано, параметр передаётся вместе с --gtest_output=xml: исполняемому файлу теста. Фактическое имя файла такое же, как у целевого объекта теста, включая префикс и суффикс. Это следует использовать вместо EXTRA_ARGS --gtest_output=xml для предотвращения гонок при записи XML-вывода результатов при использовании параллельного выполнения тестов.

DISCOVERY_MODE

Предоставляет больший контроль над тем, когда gtest_discover_tests() выполняет обнаружение тестов. По умолчанию POST_BUILD настраивает команду после сборки для выполнения обнаружения тестов во время сборки. В некоторых сценариях, таких как кросс-компиляция, такое поведение POST_BUILD нежелательно. Напротив, PRE_TEST откладывает обнаружение тестов до непосредственного момента перед выполнением тестов. Таким образом, обнаружение тестов происходит в целевой среде, где у теста больше шансов найти соответствующие зависимости во время выполнения.

DISCOVERY_MODE по умолчанию принимает значение переменной CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE , если она не передана при вызове gtest_discover_tests() . Это обеспечивает механизм глобального выбора предпочтительного поведения обнаружения тестов без необходимости изменения каждого места вызова.