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]
                     [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>]
)

Новое в версии 3.10.

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.

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.

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