GoogleTest

Этот модуль предоставляет команды для использования инфраструктуры Google Test.

Загрузите этот модуль в проекте CMake с помощью:

include(GoogleTest)

Предусмотрено два способа добавления тестов. 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

Задает 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 откладывает обнаружение тестов до момента непосредственно перед их выполнением. Благодаря этому обнаружение происходит в целевой среде, где выше вероятность найти необходимые зависимости времени выполнения.

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

DISCOVERY_EXTRA_ARGS args...

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

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

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

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