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, обычно приводя к допустимому, но нежелательному поведению. Ключевое слово было изменено на DISCOVERY_TIMEOUT в CMake 3.10.3 для решения этой проблемы. Не определено поведение ключевого слова 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.