GoogleTest

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

Этот модуль определяет функции для работы с инфраструктурой 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>]
)

Новая функция в версии 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

Указывает префикс 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

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

© 2000–2021 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.20/module/GoogleTest.html