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 args...]
                [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 args...

Дополнительные аргументы, передаваемые в командной строке каждому тестовому случаю.

Изменено в версии 3.31: Пустые значения в args... сохраняются, см. CMP0178.

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

Изменено в версии 3.31: Пустые значения в свойствах целевых объектов TEST_LAUNCHER и CROSSCOMPILING_EMULATOR сохраняются, см. политику CMP0178.

Пример использования:

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 args...]
                     [WORKING_DIRECTORY dir]
                     [TEST_PREFIX prefix]
                     [TEST_SUFFIX suffix]
                     [TEST_FILTER expr]
                     [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>]
                     [DISCOVERY_EXTRA_ARGS args...]
)

Добавлен в версии 3.10.

gtest_discover_tests() настраивает команду после сборки или перед выполнением теста для исполняемого файла теста, которая генерирует список тестов путём парсинга вывода от запуска исполняемого файла теста с аргументом --gtest_list_tests. По сравнению с подходом парсинга исходного кода gtest_add_tests(), это гарантирует, что получен полный список тестов, включая инстанциации параметризованных тестов. Поскольку обнаружение тестов происходит во время сборки или выполнения теста, нет необходимости повторно запускать CMake, когда список тестов изменяется. Однако, необходимо, чтобы CROSSCOMPILING_EMULATOR был правильно настроен для работы в среде кросс-компиляции.

Кроме того, настройка свойств тестов несколько менее удобна, так как тесты недоступны на этапе CMake. Дополнительные свойства тестов могут быть назначены всему набору тестов с помощью опции PROPERTIES. Если требуется более точный контроль над тестами, пользовательский контент может быть предоставлен через внешний скрипт CTest с помощью свойства каталога TEST_INCLUDE_FILES. Набор обнаруженных тестов становится доступным для такого скрипта через переменную <target>_TESTS (см. опцию TEST_LIST для получения дополнительной информации и ограничений).

Опции:

target

Указывает исполняемый файл Google Test, который должен быть известным целевым исполняемым файлом CMake. CMake подставит местоположение созданного исполняемого файла при выполнении теста.

EXTRA_ARGS args...

Дополнительные аргументы для передачи в командной строке каждому тестовому случаю.

Изменено в версии 3.31: Пустые значения в args... сохраняются, см. CMP0178.

WORKING_DIRECTORY dir

Указывает каталог, в котором следует запускать обнаруженные тестовые случаи. Если эта опция не указана, используется текущий каталог библиотек.

TEST_PREFIX prefix

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

TEST_SUFFIX suffix

Аналогично TEST_PREFIX, за исключением того, что suffix добавляется к имени каждого обнаруженного тестового случая. И TEST_PREFIX, и TEST_SUFFIX могут быть указаны.

TEST_FILTER expr

Добавлен в версии 3.22.

Выражение фильтра для передачи в качестве аргумента --gtest_filter во время обнаружения тестов. Обратите внимание, что выражение представляет собой формат с подстановочными знаками, который сопоставляется с исходными именами тестов, используемыми gtest. Для тестов с параметрами типа или значения эти имена могут отличаться от потенциально красиво отформатированных имён тестов, используемых ctest.

NO_PRETTY_TYPES

По умолчанию индекс типа для тестов с параметрами типа заменяется фактическим именем типа в имени теста CTest. Если это поведение нежелательно (например, потому что имена типов громоздки), эта опция подавит это поведение.

NO_PRETTY_VALUES

По умолчанию индекс значения для тестов с параметрами значения заменяется фактическим значением в имени теста CTest. Если это поведение нежелательно (например, потому что строки значений громоздки), эта опция подавит это поведение.

PROPERTIES name1 value1...

Указывает дополнительные свойства, которые необходимо установить для всех тестов, обнаруженных этим вызовом gtest_discover_tests().

TEST_LIST var

Сделать список тестов доступным в переменной var, а не в стандартной <target>_TESTS. Это может быть полезно, когда один и тот же исполняемый файл тестов используется в нескольких вызовах gtest_discover_tests() . Обратите внимание, что эта переменная доступна только в CTest.

Из-за ограничения правил парсинга CMake любой тест с квадратной скобкой в имени будет исключен из списка тестов, хранящихся в этой переменной. Однако такие тесты по-прежнему будут определены и выполнены ctest как обычно.

DISCOVERY_TIMEOUT num

Добавлен в версии 3.10.3.

Указывает, как долго (в секундах) CMake будет ждать, пока тест перечислит доступные тесты. Если тест занимает больше времени, чем это, обнаружение (и ваша сборка) завершатся ошибкой. Большинство исполняемых файлов тестов очень быстро перечисляют свои тесты, но в некоторых исключительных случаях тест может потребовать более длительного таймаута. По умолчанию значение равно 5. Также см. опцию TIMEOUT для execute_process().

Примечание

В версиях CMake 3.10.1 и 3.10.2 эта опция называлась TIMEOUT. Это вступало в конфликт со свойством теста TIMEOUT, которое является одним из общих свойств, которые обычно устанавливаются с ключевым словом PROPERTIES, что, как правило, приводило к законному, но нежелательному поведению. В CMake 3.10.3 ключевое слово было изменено на DISCOVERY_TIMEOUT, чтобы решить эту проблему. Не сохранено двусмысленное поведение ключевого слова TIMEOUT в 3.10.1 и 3.10.2.

XML_OUTPUT_DIR dir

Добавлен в версии 3.18.

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

DISCOVERY_MODE

Добавлен в версии 3.18.

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

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

DISCOVERY_EXTRA_ARGS args...

Добавлен в версии 3.31.

Дополнительные аргументы для передачи в командной строке для команды обнаружения.

Добавлен в версии 3.29: Свойство целевого объекта TEST_LAUNCHER учитывается при обнаружении и выполнении тестов.

Изменено в версии 3.31: Пустые значения в целевых свойствах TEST_LAUNCHER и CROSSCOMPILING_EMULATOR сохраняются, см. политику CMP0178.