Ты технический писатель с опытом работы более 6 лет. твоя специализация написание…
- User
Ты технический писатель с опытом работы более 6 лет. твоя специализация написание документации для систем сборок: 1. Make 2. Maven 3. Gradle 4. Ant 5. CMake 6. MSBuild 7. npm / yarn 8. Gulp / Grunt 9. Webpack 10. Bazel 11. ninja 12. make и других подобных систем. Сейчас ты описываешь еще одну систему сборки. Вот необходимая тебе информация " Запуск тестов ya make предоставляет развитые возможности запуска тестов. Основными понятиями для тестирование силами ya make являются test, chunk и suite (набор тестов). Test - одна именованная проверка, описанная в виде кода на поддерживаемом языке программирования. В понятие теста включается не только проверка правильности работы кода, но также, например, проверки, что код соответствует рекомендуемому стандарту оформления. Любые падения/ошибки во время исполнения теста относятся непосредственно к исполняемому тесту. Chunk - сущность, представляющая собой запуск программы с тестами (представлен в виде узла в графе команд), в рамках которой исполняются тесты. К chunk относятся все ошибки runtime исполнения за рамками тестов. Например, ошибки запуска тестирования, когда тестовая программа упала на инициализации и тесты даже не запускались, ошибки финализации тестирования, утечки памяти после тестирования, падения тестовых рецептов. Suite - набор из нескольких тестов одного типа и имеющих один и тот же набор зависимостей. Suite содежит по крайней мере один chunk (так называемый sole chunk). Все тесты в наборе имеют общий размер, логику начала (set up) и завершения (tear down) работы, теги и так далее. Некоторые ошибки не позволяют вообще запустить тестирование - сломанные зависимости теста, когда невозможно собрать требуемую для тестирования программу, ошибки подбора хоста для LARGE тестов из-за комбинации sandbox-тегов, которым не соответствует ни один хост. Все такие ошибки относятся к suite. Каждая suite имеет имя, размер (время, отведённое на работу), тип (используемый фреймворк), а также опциональный набор тегов. Все эти параметры могут быть использованы для фильтрации. Кроме того, каждый отдельный тест имеет имя и потому фильтрация может делаться с точностью до отдельного теста. Примечание Имена suite известны системе сборки заранее, а имена тестов выясняются только во время запуска chunk. Это, в частности, означает, что система сборки должна запустить chunk даже если ей надо только узнать имена тестов. Если в коде инициализации chunk есть ошибки, то такой запуск может завершиться ошибкой и система сборки не узнает, какие тесты есть в suite и даже сколько их там. Запуск тестов Для простого запуска тестов есть следующие ключи командной строки: -t — запустить только SMALL тесты. -tt — запустить SMALL и MEDIUM тесты. -ttt, -A, --run-all-tests — запустить тесты всех размеров. --test-param=TEST_PARAM — параметризовать тесты значениями из командной строки. TEST _PARAM имеет вид name=val, доступ к параметрам зависит от используемого фреймворка. Пример ya make -t devtools/examples/tutorials/python Запустит все тесты, которые найдёт по RECURSE/RECURSE_FOR_TESTS от devtools/examples/tutorials/python, включая тесты стиля и тесты импорта для Python. Использует следующие умолчания для сборки: Платформа будет определена по реальной платформе, на которой запущена команда ya make. Тесты будут собраны в режиме debug — он используется по умолчанию. Кроме тестов будут собраны все остальные цели (библиотеки и программы), достижимые по RECURSE/RECURSE_FOR_TESTS от devtools/examples/tutorials/python. Это включает сборку всех необходимых зависимостей. По умолчанию система сборки запустит все запрошенные тесты. После запуска тестов для всех упавших тестов будет выдана краткая информация о падениях (включая ссылки на более полную информацию). Для прошедших и проигнорированных (отфильтрованных) тестов будет выдан только общий короткий статус (количество тех и других). Это поведение меняется следующими ключами: --fail-fast — исполнять тесты до первого падения. -P, --show-passed-tests — показывать каждый прошедший тест --show-skipped-tests — показывать каждый пропущенный (отфильтрованный) тест --show-metrics — показывать метрики тестов Список тестов Список всех тестов, которые будут запущены, можно получить опцией -L (--list-tests). Эта опция поддерживает выбор размера тестов, а также все параметры фильтрации. Примеры
Список всех SMALL тестов
ya make -tL devtools/examples/tutorials/python
Список всех пользовательских тестов (без тестов стиля, импортов и подобных проверок)
ya make -AL --regular-tests devtools/examples/tutorials/python Размер тестов В едином репозитории в одном пулл-реквесте изменения могут вноситься в код и тесты на разных языках программирования. Важно, чтобы проверка любых пулл-реквестов проходила как можно быстрее, поэтому тесты разделены на категории по максимальному разрешённому времени исполнения, которое является значением по умолчанию: SMALL тесты: выполняются не более 1 минуты. Сюда обычно попадает большинство unit-тестов. MEDIUM тесты: выполняются не более 10 минут. Сюда попадают некоторые медленные unit-тесты, интеграционные и end-to-end тесты. LARGE (ранее "FAT") тесты: выполняются не более 1 часа. Содержит особо медленные тесты. В отличие от MEDIUM/SMALL тестов LARGE тесты могут продолжаться даже после завершения остальных проверок пулл-реквеста, потому что запускаются в отдельном процессе в Sandbox. Примечание Строгого соответствия между размером тестов (SMALL, MEDIUM, LARGE) и типом тестов (unit, интеграционные, end to end) нет. В первую очередь нужно ориентироваться на максимальное время исполнения каждого теста. Размер тестов должен быть явно указан в файле ya.make при помощи макроса SIZE. Максимальное время выполнения теста можно уменьшить при помощи макроса TIMEOUT. Параллельный запуск тестов По умолчанию тесты внутри одной suite выполняются последовательно в рамках одного chunk (так называемого sole chunk) в виде отдельного узла графа команд ya. Тесты из разных suite (ya.make) выполняются параллельно, но последовательно в рамках одно chunk. Во время формирования графа команда ya не может знать, сколько будет тестов в suite, так как для этого требуется сборка и листинг тестов средствами тестового фреймворка. Так как ya оперирует статическим графом команд (он не меняется по мере исполнения и целиком известен для исполнителя), то на этапе конфигурации мы только можем заранее вставить нужное количество chunk'ов, каждый из которых исполнит непересекающееся множество тестов. Чтобы разбить выполнение тестов из suite на несколько chunk'ов, нужно воспользоваться макросами FORK_TESTS, FORK_SUBTESTS и FORK_TEST_FILES. Каждый chunk наследует общие параметры теста из ya.make: размер, таймаут, требования на ресурсы и другие: таким образом удобно распараллелить тесты, которые из-за своего количества перестали укладываться в таймаут. FORK_TESTS, FORK_SUBTESTS – режимы, при которых вместо sole chunk запуск suite разбивается на несколько chunk'ов, каждый из которых получает дополнительные параметры в виде общего количества chunk'ов, участвующих в разбиении и своего порядкового номера: по этим параметрам каждый chunk определяет подмножество тестов, которое надо запустить. Количество chunk'ов по умолчанию равно 10, это значение можно изменить с помощью SPLIT_FACTOR(X) (при локальной разработке SPLIT_FACTOR можно переопределить с помощью --split-factor=Х. --split-factor=1 отключает режим форков). Отличие FORK_TESTS от FORK_SUBTESTS заключается в том, что FORK_TESTS считает тесты, объединенные в классы, неделимой сущностью, в то время как FORK_SUBTESTS разбивает в том числе тестовые классы и в разных chunk'ах могут оказаться тесты, принадлежащие одному классу, что может быть нежелательно, если у классов есть тяжёлые подготовительные стадии. FORK_TEST_FILES – разбивает прогон тестов из suite на количество chunk'ов, равное количеству файлов с тестами, перечисленных в ya.make, каждый запуск работает только с одним конкретным файлом. FORK_TESTS, FORK_SUBTESTS принимают необязательный аргумент - SEQUENTIAL или MODULO, определяющий, как будет происходить разделение тестов по chunk'ам. SEQUENTIAL разделяет тесты равными диапазонами, предварительно их отсортировав по имени. MODULO разделяет тесты по модулю SPLIT_FACTOR, предварительно их отсортировав (т.е. при SPLIT_FACTOR(2), первый тест попадёт в первый chunk, второй тест во второй, третий в первый и т.д.) Если аргумент не указан, значение по умолчанию - SEQUENTIAL. FORK_TEST_FILES можно комбинировать с FORK_TESTS или FORK_SUBTESTS, тогда будет дополнительное разбиение запуска тестов из каждого файла. FORK_TEST_FILES поддержан только для pytest.
Фильтрация тестов Suite можно фильтровать по различным свойствам: --test-size=TEST_SIZE_FILTERS — запускать только выбранные размеры --test-type=TEST_TYPE_FILTERS — запускать только выбранные типы тестов. Перед именами типов тестов можно использовать + для включения suite в фильтр и - для исключения. Таким образом --test-type -import_test запустит все тесты, кроме import_test. Фильтр --test-type unittest+gtest запустит только unittest и gtest. --style — запускать только тесты стиля --regular-tests — запускать только пользовательские тесты --test-tag=TEST_TAGS_FILTER — запускать только сюиты с определёнными тегами. Перед именами тегов можно использовать + для включения тега в фильтр и - для исключения. Таким образом --test-tag tag1+tag2-tag3 запустит все тесты, у которых есть tag1, tag2 и нет tag3. Фильтр --test-tag -tag3 запустит все тесты без тега tag3. Фильтр --test-tag ya:anytag запустит все тесты со всеми тегами. Помимо фильтрации suite можно фильтровать отдельные тесты: -F=TESTS_FILTERS, --test-filter=TESTS_FILTERS — фильтрация тестов по имени. Будет запущен тест, полное имя которого строго соответствует TESTS_FILTERS. Для запуска подмножества тестов в шаблоне можно указать символ * (соответствует любому количеству символов). Каждый последующий шаблон расширяет подмножество запускаемых тестов. Например -F 'a' -F 'Bc' запустит все тесты имена которых заканчиваются на a или начинаются на B и заканчиваются на c. Шаблоны взяты в одинарные кавычки для того чтобы shell не развернул фильтр в список файлов, которому может соответствовать шаблон. -F="[X/Y] chunk", --test-filter="[X/Y] chunk" — фильтрация тестов по chunk'ам. Внутри [] можно использовать * для фильтрации. --test-filename=TEST_FILES_FILTER — запускать тесты только из выбранного исходного файла (работает только для pytest и hermione, другие тестовые фреймоврки не предоставляют такой информации). -X, --last-failed-tests — запустить только тесты упавшие в предыдущем запуске. Указание дополнительных фильтров (например с помощью -F) расширяет множество тестов, которое будет запущено. Обычно это требуется, когда вы хотите следить за корректным статусом некоторых тестов, помимо перезапуска упавших от предыдущего прогона. При указании флага -F можно использовать специальные символы: ya make -t -F .py::::* JUnit5-тесты можно фильтровать по тегам @Tag: --junit-args '--junit-tags "tag1 tag2 tag3"' - запуск всех тестов, у которых есть хотя бы один из указанных тегов (теги можно также разделять плюсом, например tag1+tag2). Подробнее можно почитать тут. Совет Для правильного указания параметров фильтрации воспользуйтесь опцией получения списка тестов. Её же можно использовать, чтобы проверить, что ваш фильтр работает правильно. Канонизация (и переканонизация) Система сборки ya make для некоторых типов тестов поддерживает сравнение с эталонными (каноническими) данными. Если эти данные нужно обновить воспользуйтесь опцией -Z (--canonize-tests). В этом режиме вместо сравнения данных с эталонными, сами эталонные данные будут заменены и при необходимости отправлены в Sandbox. В локальное рабочее пространство будут внесены все необходимые изменения. Внимание Не забудьте закоммитить локальные изменения, иначе новые эталонные данные не будут доступны в CI. Типы тестов Типом теста называется выполнение проверок с использованием одного конкретного инструмента, например, фреймворка pytest для Python или утилиты проверки форматирования кода go fmt для Golang. Полный список типов тестов приведен : black Проверка форматирования кода на python3 утилитой black. classpath.clash Проверка наличия дублирующихся классов в classpath при компиляции Java проекта. eslint Проверка стиля и типичных ошибок кода на TypeScript с использованием утилиты ESLint. exectest Выполнение произвольной команды и проверка её кода возврата flake8.py2 Проверка стиля кода на Python 2 c использованием утилиты Flake8 flake8.py3 Проверка стиля кода на Python 3 c использованием утилиты Flake8 fuzz Fuzzing тест g_benchmark Выполнение бенчмарков на C++ библиотекой Google Benchmark go_bench Выполнение бенчмарков на Go утилитой go bench gofmt Проверка форматирования кода на Go утилитой go fmt go_test Выполнение тестов на Go утилитой go test govet Выполнение статического анализатора кода на Go утилитой go vet gtest Выполнение тестов на С++ с использованием фреймворка Google Test java Выполнение тестов на Java с использованием фреймворка JUnit java.style Проверка форматирования кода на Java утилитой checkstyle ktlint Проверка стиля Kotlin кода с использованием утилиты ktlint py2test Тесты на Python 2 с использованием фреймворка pytest py3test Тесты на Python 3 с использованием фреймворка pytest pytest Тесты на Python любой версии с использованием фреймворка pytest unittest Тесты на C++ с использованием фреймворка unittest validate_resource Проверка времени жизни Sandbox ресурса
Описание тестов В этом разделе подробно рассказано как описывать тесты в ya.make файлах. Про запуск тестов можно прочитать вот здесь В нашей системе сборки ya make можно описать тесты для основных языков. Поддержка тестов реализована поверх фреймворков для тестирования в этих языках. Подробную информацию про устройство тестов в языке можете найти на соответствующих страницах (C++, Python, Java, Go). Общие понятия Два основных понятия для тестов в ya make это test и suite. test - это конкретная именованная проверка. suite - сущность, включающая в себя тесты в рамках описываемого модуля. Как описывать ya.make По умолчанию один тестовый модуль является одной suite. suite аккумулирует в себе ошибки тестирования, которые выходят за пределы определения теста, например: ошибки получения списка тестов ошибки инициализации тестирования (до фактического выполнения тестов) ошибки финализации тестирования Сьюита имеет несколько параметров: Указание фрэймворка тестирования Список файлов с тестами Список зависимостей Размер Тэги Требования к запуску тестов Переменные окружения Таймаут на запуск Список зависимостей Мы придерживаемся идеи герметичности тестов. Это значит, что тест должен быть зависимым только от входных данных, которые были явно задекларированы в ya.make. Чтобы обеспечить герметичность тестов, каждый запуск проходит в чистом окружении, которое содержит только указанные явно зависимости из ya.make. Помимо сборочных зависимостей (описываются макросом PEERDIR()), для тестов нужно описывать зависимости на входные данные для запуска тестов. Они бывают двух типов: Другие проекты из единого репозитория. Например, вам может потребоваться исполняемый файл, исходные коды которого расположены в другом проекте. Такие зависимости описываются при помощи макроса DEPENDS(). Все пути строятся относительно корня ircadii и указываются через пробел до ya.make. Тестовые данные. Например, сюда относятся различные эталонные файлы: логи, списки, тестовые дампы баз данных. Такие файлы могут храниться как и в ircadii, так и в Sandbox. Для описания тестовых данных можно использовать макросы: DATA() FROM_SANDBOX() Более полную информацию про использование данных в тестах можно прочитать здесь. Сборка и запуск тестов Основная задача ya make - cборка. Поэтому handler собирает все указанные цели и достижимые от них по RECURSE. Однако, основная цель у ya test / ya make -t - запуск тестирования. Поэтому по умолчанию будут собираться только те цели, которые необходимы для запуска тестирования. Это, например, позволяет запускать конкретные типы тестов без сборки: ya test --test-type black запустит только python black линтер, без какой-либо сборки. Примечание Модули, достижимые по RECURSE, но не используемые в тестах или сами не являющиеся тестовыми модулями не будут собираться. Для того чтобы ya test / ya make -t собирал все достижимые цели, нужно добавить ключ -b / --build-all.
Размер тестов Размер тестов задается макросом SIZE(). Сейчас существуют три размера: SIZE(SMALL) - максимальный таймаут 60s (1min). Размер по умолчанию. SIZE(MEDIUM) - максимальный таймаут 600s (10min). SIZE(LARGE) - максимальный таймаут 3600s (1hour). Тэги теста Тесты можно фильтровать по тэгам. Тэги проставляются с помощью макроса TAG().
Требования к запуску теста Макрос REQUIREMENTS() позволяет указать требования, необходимые для запуска тестов. С помощью этого макроса можно задать: количество ядер необходимый объем свободного места на диске необходимый объем оперативной памяти необходимый объем RAM-диска ID контейнера ограничения сети Все возможные описания требований указаны в разделе Общие макросы Переменные окружения С помощью макроса ENV(key=value) можно задать значение переменной окружения при запуске теста. Каждая переменная окружения задается отдельным макросомм. Иерархия проекта с тестами Предлагается в папке проекта иметь lib, bin, tests или lib/tests. Мы не рекомендуем указывать RECURSE в ya.make, содержащем описание модуля, но можно после директивы END() добавлять RECURSE_FOR_TESTS на тесты, проверяющие этот модуль. Тогда project/ya.make может состоять из RECURSE( project/bin project/lib project/lib/tests ) В project/lib не должно быть RECURSE на tests или определение модуля тестов, однако можно поставить RECURSE_FOR_TESTS. В этом случае при запуске ya make -t из каталога project инициируется сборка проекта с прогоном тестов. А другие проекты, желая подключать вашу библиотеку, будут писать PEERDIR(project/lib) без установления зависимости от ваших тестов. Гранулярные тесты Гранулярные зависимости в сборке это хорошо, тоже самое относится и к тестам. Если у вас в тестовом модуле более ~15 файлов с тестами (к java не относится) скорее всего вам нужно разбить ваш suite на несколько логических. Как правило всё множество тестов можно кластеризовать по каким-либо признакам - по тестируемым сущностям, по зависимостям, по типу тестирования, по сценариям тестирования. Такое разбиение больших тестовых suite может значительно ускорить локальную разработку и время прохождения PR в CI: при исправлении тестов или добавлении новых будет запускаться только целевой suite более гранулярные зависимости позволяют запускать только те тесты, которые по настоящему зависят от них более гранулярные зависимости ускоряют конфигурацию ускоряется рантайм тестирования, так как ускоряется процедура дискаверинга тестов в каждый отдельный suite может быть прописан REQUIREMENTS соответствующий действительности логическая группировка упрощает организацию тестовых файлов Пример антипаттерна: тестовый модуль с сотнями тестовых файлов и макросами FORK_TEST()/FORK_TEST_FILES(). Такая организация suite приводит к огромному прожиганию ресурсов впустую, так как при изменении любого файла будут вынуждены перезапуститься абсолютно все тесты в suite. Локальный запуск одного конкретного test case из такого suite может происходить очень долго. Возможности тестов Канонизация У тестов есть возможность сообщить о своих результатах в виде данных, которые необходимо верифицировать с каноническими. Такие тесты необходимо первый раз канонизировать, после чего системе будут доступны референсные данные для сравнения. Канонический результат будет сохранен рядом с тестом в директорию canondata//result.json или вынесен в ресурс Sandbox, в зависимости от переданных параметров в тесте. Каждый фреймворк для написания тестов предоставляет свою поддержку механизма канонизации. Канонизация поддержана для всех языков, кроме C++. Метрики Наш CI поддерживает выгрузку пользовательских метрик из тестов. При подключении проекта к автосборке история теста с метриками будет сохраняться и отображаться в CI. При локальной сборке будет доступен отчет. Параллельный запуск тестов По умолчанию тесты внутри одного ya.make файла выполняются последовательно в рамках отдельной задачи сборочного графа, а тесты из разных ya.make выполняются параллельно. Для того, чтобы разбить выполнение тестов из одного ya.make на несколько параллельных запусков, можно воспользоваться макросами FORK_TESTS, FORK_SUBTESTS и FORK_TEST_FILES. Каждый запуск будет выполнен в отдельной задаче сборочного графа. Важно отметить, что каждый подзапуск наследует общие параметры теста из ya.make, такие как размер, таймаут, требования на ресурсы и т.д. Таким образом удобно распараллелить тесты, которые из-за своего количества перестали укладываться в таймаут, но если в ya.make стоит требование cpu(4), то при большом количестве параллельных задач, локальный запуск ya make может замедлиться. Не все FORK-макросы поддержаны для конкретного тестового фреймворка и языка: перед их использованием, уточните текущий статус в документации.
Exec-тесты Помимо обычных тестов, которые будут описаны в специфичных для языков разделах, есть возможность писать exec-тесты. Exec-тесты позволяют выполнить произвольную команду и убедиться, что она успешно завершается. Успешным считается завершение команды с кодом возврата 0. Подробнее про описание Exec-тестов написано здесь. Как описывать тесты для языков C++ Сейчас поддержаны два тестовых фреймворка: unittest - собственная разработка gtest - популярное решение от Google Также есть отдельная библиотека library/cpp/testing/common, в которой находятся полезные утилиты, независящие от фреймворка. Бенчмарки: Используется библиотека google benchmark и модуль G_BENCHMARK. Все подключенные к автосборке бенчмарки запускаются в CI по релевантным коммитам и накапливают историю метрик. Fuzzing: Фаззинг - это техника тестирования, заключающаяся в передаче приложению на вход неправильных, неожиданных или случайных данных. Все подробности здесь. Linting: Поддержан статический анализ файлов с помощью clang-tidy. Подробнее про подключение своего проекта к линтингу в автосборке можно прочитать здесь. Метрики: Помимо метрик от бенчмарков также можно сообщать числовые метрики из UNITTEST() и GTEST(). Для добавления метрик используйте функцию testing::Test::RecordProperty если работаете с gtest, или макрос UNIT_ADD_METRIC если работаете с unittest. TEST(Solver, TrivialCase) { // ... RecordProperty("num_iterations", 10); RecordProperty("score", "0.93"); } Минимальный ya.make для тестов выглядит так: UNITTEST() | GTEST() | G_BENCHMARK() OWNER(...) SRCS(tests.cpp) END() Python Основным фреймворком для написания тестов на Python является pytest. Поддерживаются Python 2 (модуль PY2TEST), Python 3 (модуль PY3TEST) и модуль PY23_TEST. Все тестовые файлы перечисляются в макросе TEST_SRCS(). Для работы с файлами, внешними программами, сетью в тестах следует использовать специальную библиотеку yatest. Метрики: Чтобы сообщить метрики из теста, необходимо использовать funcarg metrics. def test(metrics): metrics.set("name1", 12) metrics.set("name2", 12.5) Бенчмарки: Для бенчмарков следует использовать функцию yatest.common.execute_benchmark(path, budget=None, threads=None). Чтобы результаты отображались в CI, результаты нужно записывать в метрики. Канонизация: Можно канонизировать простые типы данных, списки, словари, файлы и директории. Тест сообщает о данных, которые нужно сравнить с каноническими, через возврат их из тестовой функции командой return. Linting: Все python файлы, используемые в сборке и тестах, подключаемые через ya.make в секциях PY_SRCS() и TEST_SRCS(), автоматически проверяются flake8 линтером. Python imports: Для программ PY2_PROGRAM, PY3_PROGRAM, PY2TEST, PY3TEST, PY23_TEST, собранных из модулей на питоне, добавлена проверка внутренних модулей на их импортируемость - import_test. Это позволит обнаруживать на ранних стадиях конфликты между библиотеками, которые подключаются через PEERDIR, а также укажет на неперечисленные в PY_SRCS файлы (но не TEST_SRCS). Java Для тестов используется фреймворк JUnit версий 4.x и 5.x. Тестовый модуль для JUnit4 описывается модулем JTEST() или JTEST_FOR(path/to/testing/module). JTEST(): система сборки будет искать тесты в JAVA_SRCS() данного модуля. JTEST_FOR(path/to/testing/module): система сборки будет искать тесты в тестируемом модуле. Для включения JUnit5 вместо JTEST() необходимо использовать JUNIT5(). Содержание ya.make файла для JUNIT5() и JTEST() отличается только набором зависимостей. Минимальный ya.make файл выглядит так: JTEST() JAVA_SRCS(FileTest.java) PEERDIR(
Сюда же необходимо добавить зависимости от исходных кодов вашего проекта
contrib/java/junit/junit/4.12 # Сам фреймворк JUnit 4 contrib/java/org/hamcrest/hamcrest-all # Можно подключить набор Hamcrest матчеров ) END() Java classpath clashes: Есть возможность включить автоматическую проверку на наличие нескольких одинаковых классов в Java Classpath. В проверке участвует не только имя класса, но и хэш-сумма файла с его исходным кодом, так как идентичные классы из разных библиотек проблем вызывать не должны. Для включения этого типа тестов в ya.make файл соответствующего проекта нужно добавить макрос CHECK_JAVA_DEPS(yes). Linting: На все исходные тексты на Java, которые подключены в секции JAVA_SRCS, включён статический анализ. Для проверки используется утилита checkstyle. Канонизация: Для работы с канонизированными данными используйте функции из devtools/jtest. Go Тесты работают поверх стандартного тулинга для Go. Для работы с зависимостями теста следует использовать библиотеку library/go/test/yatest. Все тестовые файлы должны иметь суффикс _test.go. Они перечисляются в макросе GO_TEST_SRCS. Тестовый модуль описывается модулем GO_TEST() или GO_TEST_FOR(path/to/testing/module). GO_TEST(): система сборки будет искать тесты в GO_TEST_SRCS() данного модуля. GO_TEST_FOR(path/to/testing/module): система сборки будет искать тесты в GO_TEST_SRCS в тестируемом модуле. Минимальные ya.make файлы выглядят так: GO_TEST() GO_TEST_SRCS(file_test.go) END() Канонизация: Для работы с такими тестами используйте library/go/test/canon. Пример. Бенчмарки: Чтобы включить бенчмарки в проекте, нужно добавить тэг ya:run_go_benchmark в ya.make проекта. Пример.
Общие макросы Зависимости DEPENDS() DEPENDS(path1 [path2...]) Указывает зависимости на другие проекты, которые нужно собрать и результаты которых должны быть доступны тесту. В параметрах перечисляются относительные пути от корня ircadii. Параметры suite SIZE() SIZE(SMALL | MEDIUM | LARGE) Задаёт размер suite. Сейчас существует три размера: SMALL - максимальный таймаут 60s. Размер по умолчанию. MEDIUM - максимальный таймаут 600s. LARGE - максимальный таймаут 3600s. Важно Если в ya.make листе указаны несколько значений макроса SIZE(), например, через вложенный INCLUDE, то последнее значение переопределяет все предыдущие. TIMEOUT() TIMEOUT(time) Устанавливает таймаут на запуск всей сьюиты. По умолчанию равен: 60s (1min) для SMALL тестов; 600s (10min) для MEDIUM тестов; 3600s (1hour) для LARGE тестов. Примечание Таймаут не может быть больше, чем максимальная длительность теста данного размера. Если запуск сьюиты разбит на части (FORK_TEST_FILES()/FORK_TESTS()/FORK_SUBTESTS()), то указанный таймаут ограничивает время работы каждого запуска в отдельности. TAG() TAG(tag1 [tag2...]) Позволяет задать пользовательские теги, по которым можно фильтровать запуск suite в ya test, см. опцию --test-tag. Ниже представлен список специальных системных тегов, которые могут менять поведение тестов. Запуск тестов: ya:always_minimize: приводит к постоянной минимизации корпуса после фаззинга, см подробности в документации к fuzzing. ya:manual: тест не будет запускаться, если явно не указано запускать тесты с таким тегом ya:norestart: тест не будет перезапускаться при определенных ошибках ya:not_autocheck: не запускать тест при проверке pull requests Логирование: ya:full_logs: приводит к падению сьюиты, если размер логов привысил 100Мб ya:huge_logs: увеличивает ограничение на размер логов теста с 100Мб до 1Гб ya:sys_info: добавляет вывод системной информации в лог до и после выполнения всех рецептов и тестов ya:trace_output: включает логирование создаваемых файлов и их размеров при помощи системного вызова ptrace. Работает только под Linux. Может замедлять тестирование ya:dump_node_env: печатает дерево директорий относительно build_root узла сразу после его запуска в лог test-results//run_test.log. Позволяет узнать чистое окружение тестового узла, которое приехало по зависимостям ya:dump_test_env: печатает дерево директорий относительно build_root узла непосредственно перед запуском враппера тестов в лог test-results//run_test.log. Позволяет узнать окружение в котором будут запускаться тесты (после запуска рецептов). Не работает вместе с ya:dirty, так как привело бы к полному обходу ircadii. large-тесты: ya:fat: помечает тест как LARGE ya:force_distbuild: запускает тест в distbuild вне зависимости от его размера ya:force_sandbox: запускает тест в Sandbox. Используется только вместе с тегом ya:fat ya:noretries: тесты с таким тегом не будут запускаться в автосборке повторно ya:privileged: запускает тесты в Sandbox в контейнере от имени root ya:sandbox_coverage: включает LARGE тесты в подсчет покрытия. Нужно использовать вместе с ya:force_sandbox ya:relwithdebinfo: тесты с таким тэгом будут собираться с флагом --build relwithdebinfo - релизная сборка с включенными ассертами для C++. Тесты, собранные с --build relwithdebinfo, могут исполняться медленне, чем для релизной сборки, но ассерты могут дать больше полезной информации. Управление окружением: ya:copydata: Пути, указанные в макросе DATA() подключаются в тестовое окружение не симлинками, а рекурсивно копируются, при этом всем файлам и каталогам выставляются права на запись пользователя и группы ya:copydataro: Аналогично ya:copydata, но наоборот, всем файлам и каталогам запрещается запись для пользователя, группы и других Остальные: ya:external: уведомляет систему, что тест использует внешние системы (сеть, внешние базы данных). Это значит, что такой тест потенциально нестабильный. Уведомления о поломках таких тестов будут приходить только владельцам теста и не будут приходить авторам комита, на котором тест сломался ya:no_graceful_shutdown: завершает выполнение процесса с тестами при помощи сигнала SIGQUIT вместо SIGTERM. Это позволяет, например, поймать стектрейс состояния, в котором находится тест ya:notags: используется для фильтрации тестов, не имеющих тегов Sandbox-теги: sb:XXXX: позволяет задать набор тегов для выбора агента Sandbox. При указании нескольких тегов sb:, они соединяются через логическое ИЛИ sb:ttl=inf: позволяет задать TTL в днях для создаваемого в таске YA_MAKE ресурса BUILD_OUTPUT. Тег следует использовать, если автозапуск LARGE тестов от лица вашего робота потребляет много дисковой квоты из-за больших выходных данных в этом ресурсе. TTL по умолчанию равен 14 дней sb:logs_ttl=14: позволяет задать TTL в днях для создаваемого в таске YA_MAKE ресурса TASK_LOGS. Тег следует использовать, если автозапуск LARGE тестов от лица вашего робота потребляет много дисковой квоты из-за больших выходных данных в этом ресурсе. TTL по умолчанию равен 14 дней sb:store_output_binaries: сохраняет собранные бинари large-тестов в ресурсах типа BUILD_OUTPUT таски YA_MAKE REQUIREMENTS() REQUIREMENTS( [cpu:] [disk_usage:] [ram:] [ram_disk:] [container:] [network:<restricted|full>] [dns:<default|local|dns64>]) [yav:<ENV_NAME>=<value|file>::] ) Позволяет настроить требования к окружению, в котором будет выполняться тест. Large-тесты в основном запускаются под Sandbox, поэтому всё, что связано с Sandbox, можно смело соотносить с Large-тестами (кроме случаев когда large-тесты запускаются на YT). Name Default Values Applicability Description container - Sandbox ID Sandbox контейнера, в котором будет выполняться тест cpu 1 1.. / all Local / Distbuild / Sandbox Количество процессорных ядер, необходимых тестам для корректной работы. Конечное значение рассчитывается как min(требуемое, количество_ядер_на_хосте). При указании all тестовый узел будет работать монопольно, в этом случае если у suite есть несколько chunk, то запуск выстроится в цепочку запуска chunk disk_usage 100 1.. Sandbox Необходимый объём свободного места на файловой системе в Gb. Для Large теста превращается в требование disk_usage у Sandbox таски. dns default default / local / dns64 Sandbox Настраивает использование NAT64 в Sandbox. default - доступ в интернет по IPv4 невозможен, local - используются настройки из файла /etc/resolv.conf.local. Имеет смысл только для кастомных контейнеров, в которых этот файл существует. dns64 - доступ в Интернет по IPv4 возможен. Весь резолвинг имён происходит через ферму ns64-cache.yandex.net network restricted restricted / full Local* / Distbuild Определяет тип доступа к сети. full - есть доступ во внешнюю сеть. restricted - можно использовать только localhost. Локально учитывается только на linux при указании ключа --private-ns-drive (или --autocheck-mode). ram - 1.. Distbuild / Sandbox Необходимый объём оперативной памяти в Gb. ram_disk - 1.. Local* / Sandbox / Distbuild Необходимый объём RAM диска в Gb. На Distbuild выделяется для каждого узла. На Sandbox выдяляется один на всю suite - заказывается в виде требования у Sandbox таски. Локально учитывается только на linux при указании ключа --private-ram-drive (или --autocheck-mode). Тест может узнать путь к созданому для него RAM диску через API взаимодействия с тестовым окружением: Java, Python yav - см. описание Sandbox Ключ из секретницы в виде шаблона <ENV_NAME>=<value/file>::, который получит тест через указанную переменную окружения, где <ENV_NAME> - имя переменной, <value/file> тип передачи секрета (value - значение секрета будет записано в указанный ENV_NAME, file - секрет будет записан во временный файл и до путь до него будет передан через ENV_NAME), - id yav секрета, - имя ключа из секрета Мы крайне не рекомендуем использовать секреты и предлагаем стараться обходиться без них, используя моки или другие техники тестирования. Использование секрета ломает воспроизводимость теста и не позволяет его запускать разработчикам без доступа до него. Так же появляется стейт за границами репозитория и статуc теста начинает зависеть от комплементарности системы использующей секрет и самого секрета в yav. При использовании секретов suite автоматически получает тег ya:external, т.е. падения такого тестa в CI будут видны только владельцам теста. sb_vault - см. описание Sandbox Deprecated, используйте yav . Ключ из sandbox-vault. Должен соответствовать паттерну <ENV_NAME>=<value/file>::. Для доступа из Large-тестов секрет должен быть пошарен (Shared with) с группой REVIEW-CHECK-FAT. При использовании секретов suite автоматически получает тег ya:external, т.е. падения такого тестa в CI будут видны только владельцам теста. Примечание Параметры disk_usage и container работают только для LARGE тестов. Параметр container позволяет запускать тесты в заранее подготовленном окружении в виде образа LXC или Porto контейнера. Поскольку RAM-диск использует оперативную память, суммарное значение полей ram и ram_disk не может превышать максимально возможное значение размера оперативной памяти для тестов данного размера. Актуальные требования можно посмотреть вот тут, словарь TestSize.DefaultRequirements. Requirement SMALL MEDIUM LARGE CPU 1 .. 4 1 .. 4 1 .. 4 RAM 8 .. 32 8 .. 32 8 .. 32 RAM disk 0 .. 4 0 .. 4 0 .. 4 Требования для LARGE учитываются только при запуске на Distbuild - для тестов размеченных с помощью тега TAG(ya:force_distbuild). По умолчанию LARGE тесты сейчас запускаются в Sandbox, где нет этих ограничений. ENV() ENV(key=[value]) Задает значение переменной окружения key значение value при запуске теста. Параллельный запуск тестов FORK_TESTS() FORK_TESTS(mode) Разбивает запуск suite на несколько chunk'ов. По умолчанию количество chunk'ов равно 10. Это значение можно изменить с помощью макроса SPLIT_FACTOR(x). В отличие от FORK_SUBTESTS считает тесты, объединенные в один класс, неделимой сущностью. Каждый chunk наследует общие параметры теста из ya.make: размер, таймаут, требования на ресурсы. Поэтому этот макрос удобно использовать, чтобы распараллелить тесты, которые не укладываются в таймаут. Параметр mode определяет, каким образом будет происходить распределение тестов по chunk'ам. Может быть равен SEQUENTIAL или MODULO. Если аргумент не указан, то по умолчанию равен SEQUENTIAL. SEQUENTIAL распределяет тесты равными диапозонами, предварительно отсортировав их по имени. MODULO разделяет тесты по модулю, предварительно их отсортировав. FORK_SUBTESTS() FORK_SUBTESTS(mode) Разбивает запуск suite на несколько chunk'ов. По умолчанию количество chunk'ов равно 10. Это значение можно изменить с помощью макроса SPLIT_FACTOR(x). В отличие от FORK_TESTS может разбивать тесты, объединенные в один класс, в разные chunk'и. Нежелательно использовать, если у классов есть тяжелые подготовительные стадии. Каждый chunk наследует общие параметры теста из ya.make: размер, таймаут, требования на ресурсы. Поэтому этот макрос удобно использовать, чтобы распараллелить тесты, которые не укладываютсмя в таймаут. Параметр mode определяет, каким образом будет происходить распределение тестов по chunk'ам. Может быть равен SEQUENTIAL или MODULO. Если аргумент не указан, то по умолчанию равен SEQUENTIAL. SEQUENTIAL распределяет тесты равными диапозонами, предварительно отсортировав их по имени. MODULO разделяет тесты по модулю, предварительно их отсортировав. FORK_TEST_FILES() FORK_TEST_FILES() Разбивает прогон тестов из suite на количество chunk'ов, равное количеству файлов с тестами, перечисленных в ya.make. Каждый запуск работает только с одним конкретным файлом. Можно комбинировать вместе с FORK_TESTS() и FORK_SUBTESTS(). В этом режиме будет происходить дополнительное разбиение тестов для каждого файла. Важно Поддержан только для pytest. SPLIT_FACTOR() SPLIT_FACTOR(x) Изменяет количество chunk'ов при параллельном запуске тестов. Можно использовать только с FORK_TESTS() и FORK_SUBTESTS(). Специфичные макросы USE_RECIPE() USE_RECIPE(path [arg1 arg2...]) Подключает рецепт для настройки тестового окружения к тесту. Если тест описан с использованием макросов FORK_TEST() / FORK_SUBTESTS(), то рецепт будет подготавливать отдельное окружение для каждого запуска. SKIP_TEST() SKIP_TEST(Reason) Отключает тесты для всей модульной сьюиты. Параметром указывается причина отключения. NO_LINT() NO_LINT() Отключает codestyle проверки для java и python. Важно Использование NO_LINT() разрешено только в contrib.
Канонизация У тестов есть возможность сообщить о своих результатах в виде данных, которые необходимо сравнить с каноническими. Чтобы система имела доступ к каноническим данным, их нужно в первый раз канонизировать. Необходимо отметить, что сравнение с каноническими значениями происходит на стороне ya, следовательно, чтобы иметь возможность верифицировать такие тесты, их надо запускать через ya make. Каждый фреймворк для написания тестов предоставляет свою поддержку механизма канонизации, описанную в соответствующих разделах. Канонизация в C++ Важно На данный момент нативная канонизация в C++ тестах не поддержана. DEVTOOLS-1467 Ниже описано несколько альтернативных способов автоматически обновлять канонические данные для C++ тестов, помимо нативной канонизации. Матчер в gtest Матчер NGTest::GoldenFileEq(filename), доступный в модуле GTEST, умеет сравнивать тестируемые данные с содержимым указанного файла и обновлять этот файл при запуске теста с аргументом --test-param GTEST_UPDATE_GOLDEN=1: TEST(Suite, Name) { std::string data = RenderSomeTextData(); EXPECT_THAT(data, NGTest::GoldenFileEq(SRC_("golden/data.txt"))); } Мы настоятельно не рекомендуем использовать этот способ для тестирования бинарных данных. В репозитории следует хранить только файлы, изменения в которых можно посмотреть на код-ревью: тексты, конфиги, картинки. Дополнительный EXECTEST Можно канонизировать вывод от тестов или выходные файлы с помощью отдельного ya.make с EXECTEST(), который будет зависеть от теста и запускать вручную указанные тесты. Документация про EXECTEST. Также см. пример. Канонизация в Python Тест сообщает о данных, которые нужно сравнить с каноническими, путем их возврата из тестовой функции командой return. На данный момент поддерживаются все простые типы данных, списки, словари и файлы: def test(): return [1, 2.0, True] Канонизация файлов Для того, чтобы вернуть файл, необходимо воспользоваться функцией yatest.common.canonical_file(path, diff_tool=None, local=False, universal_lines=False, diff_file_name=None, diff_tool_timeout=None) path: путь до файла; diff_tool: путь к программе для сравнения канонических файлов. По умолчанию используется diff. Нестандартные программы для сравнения канонических файлов; local: сохранять файл в репозиторий, а не в Sandbox. Мы настоятельно не рекомендуем хранить бинарные канонические файлы в репозитории; universal_lines: нормализует EOL; diff_file_name: название для файла с дифом. По умолчанию - <имя сравниваемого файла>.diff); diff_tool_timeout: таймаут на запуск diff tool. Для канонизации нескольких файлов, необходимо вернуть список или словарь с объектами canonical_file. def test1(): return [yatest.common.canonical_file(output_path1), yatest.common.canonical_file(output_path2)] def test2(): return { "path1_description": yatest.common.canonical_file(output_path1), "path2_description": yatest.common.canonical_file(output_path2) } Канонизация директорий Для того, чтобы канонизировать содержимое директории, необходимо воспользоваться функцией yatest.common.canonical_dir(path, diff_tool=None, diff_file_name=None, diff_tool_timeout=None) path: путь до директории; diff_tool: путь к программе для сравнения канонических файлов. По умолчанию используется diff. Нестандартные программы для сравнения канонических файлов; diff_file_name: название для файла с дифом. По умолчанию - <имя сравниваемой директории>.diff); diff_tool_timeout: таймаут на запуск diff tool. Важно Все директории загружаются в sandbox, их нельзя сохранять локально в canondata, в отличие от canonical_file.
Канонизация запуска программы Для того, чтобы канонизировать stdout программы нужно воспользоваться функцией yatest.common.canonical_execute(binary, args=None, check_exit_code=True, shell=False, timeout=None, cwd=None, env=None, stdin=None, stderr=None, creationflags=0, file_name=None, save_locally=False) binary:абсолютный путь до программы; args: аргументы программы; check_exit_code: бросает ExecutiopnError, если запуск программы завершается с ошибкой; shell: использовать shell; timeout: таймаут на выполнении програмы; cwd: рабочая директория; env: окружение для запуска команды; stdin: поток ввода команды; stderr: поток ошибок команды; creationflags: creationFlags команды запуска; file_name: имя output файла. По умолчанию используется имя программы binary. Конечное название файла будет <file_name>.out.txt save_locally: сохранять файл в репозиторий, а не в Sandbox. Мы настоятельно не рекомендуем хранить бинарные канонические файлы в репозитории; diff_tool: путь к программе для сравнения канонических файлов. По умолчанию используется diff. Нестандартные программы для сравнения канонических файлов; diff_file_name: название для файла с дифом; diff_tool_timeout: таймаут на запуск diff tool. Для канонизации stdout запуска python-скриптов можно воспользоваться функцией yatest.common.canonical_py_execute(script_path, args=None, check_exit_code=True, shell=False, timeout=None, cwd=None, env=None, stdin=None, stderr=None, creationflags=0, file_name=None) Если нужно канонизировать вывод нескольких программ, то результат canonical_execute можно сохранять в переменные, а в тесте вернуть словарь: res1 = yatest.common.canonical_execute(binary1) res2 = yatest.common.canonical_execute(binary2) return {"stand_initializer": res1, "prog2": res2} Канонизация stdout программы Канонизация stdout python script Ожидаемое несоответствие канонизации В pytest поддерживается механизм xfail (expected to fail), которым размечают тесты, которые падают ожидаемо. Однако, в силу того что канонизация является надстройкой над всеми тестовыми фреймворками, их механизмы никак не могут влиять или управлять процедурой сверки канонических данных. Поэтому тест размеченный xfail и имеющий diff с каноническими данными будет в статусе поломки. Для того чтобы разметить, что у теста канонические данные отличаются от полученных в ходе тестирования или отсутствую канонические данные и это нормально, его нужно разметить маркером @pytest.mark.xfaildiff. В этом случае: Если тест упадёт он будет в статусе FAIL Если тест успешно отработает и вернёт канонические данные, но их не с чем будет сравнить (канонизации ещё не было и вы не хотите канонизировать неверные данные) или они будут отличаться, то статус теста будет XFAIL Если тест успешно отработает и канонические данные совпадут, тест упадёт со статусом XPASS При канонизации (-Z/--canonize-tests) тесты рамечанные xfaildiff НЕ канонизируются. xfaildiff в качестве pytest.param и декоратора Канонизация в Java Чтобы канонизировать данные, нужно использовать функции из devtools/jtest. Канонизация объектов Для канонизации объектов нужно использовать функцию ru.yandex.devtools.test.Canonizer.canonize(Object). Важно помнить, что объект будет сериализован с помощью new Gson().toJson(obj). Важно На каждый тест может быть только один вызов ru.yandex.devtools.test.Canonizer.canonize(Object): если их будет несколько, последний перетрет изменения всех предыдущих.
Канонизация файлов Для того, чтобы канонизировать файл, нужно использовать ru.yandex.devtools.test.CanonicalFile. По умолчанию все файлы загружаются в Sandbox. Чтобы сохранить локально, нужно задать параметр local в true. Мы настоятельно не рекомендуем хранить бинарные канонические файлы в репозитории. Помимо обычного diff, можо использовать кастомный diff_tool. Подробнее, как правильно его оформлять, описано здесь. Если в качестве diff_tool используется JAVA_PROGRAM, то в таком варианте путь к ней необходимо передавать вместе с путем до java. Использование JAVA_PROGRAM как diff tool Канонизация в Go Для канонизации данных нужно использовать library/go/test/canon. Канонизация объектов Для канонизации внутриязыковых объектов нужно использовать функцию SaveJSON. Пример Канонизация внутреязыковых объектов Канонизация файлов Для того, чтобы канонизировать файл, нужно использовать SaveFile. По умолчанию все канонизированные файлы загружаются в mds/sandbox.Чтобы сохранять эти файлы локально, нужно в фукнцию SaveFile передать аргумент canon.WithLocal(true). Помимо обычного diff, можо использовать кастомный diff_tool. Подробнее, как правильно его оформлять, описано здесь.
Канонизация с нестандартным diff tool Diff tool для сравнения канонических файлов и директорий По умолчанию, во всех фреймворках для сравнения канонизированных данных используется diff, но для каждого языка есть возможность использовать кастомный diff tool. Для того, чтобы переопределить программу для сравнения канонических файлов, нужно: Добавить в секцию DEPENDS теста путь к ya.make программы, которая удовлетворяет следующим условиям (аналогично системному diff): Принимает на вход два неименованных аргумента - пути к файлам, которые надо сравнить; В случае, если файлы одинаковые возвращает 0, если разные, то код возврата равен 1 и в stdout выведена информация, которая указывает на различия. В тестах в соответствующих функциях для канонизации файла или директории передать путь к програме. Примечание Программа сравнения вызывается только в случае расхождения чек-суммы полученного тестом файла с каноническим: это надо учитывать при отладке diff tool. Как канонизировать Для того, чтобы канонизировать результат теста, нужно воспользоваться опцией -Z, --canonize-tests: ya make -tF --canonize-tests [--owner --token ] Канонический результат будет сохранен рядом с тестом в репозитории в директорию canondata//result.json или вынесен в ресурс Sandbox, в зависимости от переданных параметров в тесте. Все созданные/удаленные файлы в процессе канонизации заносятся в репозиторий, но не коммитятся сразу, таким образом, одним коммитом можно послать тест и его канонический результат. Важно Не меняйте руками никакие данные внутри директории canondata - это приведёт к тому, что тест будет работать некорректно, потому что до сверки канонических данных ya make проверяет чек-суммы из canondata/result.json, и если они расходятся, то только в этом случае строит diff. Поэтому ручное изменение канонических данных не приведёт к обнаружению diff'а. Всегда переканонизируйте результаты с помощью ya make -AZ. Внимание Нам известно, что иногда при переканонизации тестов возникает ошибка, когда тест не может достать данные для канонизации из кэша. Проявляется это следующим образом: NoResourceInCacheException: There is no suitable resource <resource_info> in cache. При возникновении у вас такой проблемы, пожалуйста, обратитесь в DEVTOOLSSUPPORT с приложенной информацией о падении, для этого: Добавьте в ya.make падающих тестов следующие тэги: TAG(ya:dump_node_env ya:dump_test_env) Запустите ваши тесты еще раз и загрузите получившуюся директорию test-results в sandbox: ya upload test-results Создайте тикет в devtoolsupport https://forms.ypurdomen.xx/surveys/devtools/ c описанием проблемы и приложите ссылку на полученный в предыдущем пункте ресурс Чтобы починить эту проблему, нужно удалить кэш ya. Для этого можно вызвать следующую команду: ya gc cache --size-limit 0 Канонизация в Sandbox Канонизировать результаты тестов можно с помощью sandbox задач YA_MAKE и YA_MAKE_2. Для этого нужно: в поле Targets указать путь до теста; выбрать Run tests; выбрать Canonize tests. Дополнительные опции канонизации --owner: имя владельца ресурса с каноническими данными в Sandbox. По умолчанию, имя текущего пользователя; --user: имя пользователя для авторизации в Sandbox. По умолчанию, имя текущего пользователя; --token: токен для авторизации в Sandbox. Необходимо получить на странице в Sandbox. Если токен не передан, будет произведена попытка авторизации по SSH-ключам (поддерживаются rsa/dsa-ключи), которые ожидаются или в ~/.ssh, или в SSH-агенте. Публичная часть ключа должна быть загружена на Стафф; --key: путь к приватной части rsa/dsa-ключа для авторизации в Sandbox. Публичная часть этого ключа должна быть загружена на Стафф; Если протокол загрузки канонических данных в Sandbox не задан, то предпочтение будет отдано http. Протокол можно задать явно: --canonize-via-skynet: загрузка только через протокол skynet: на канонические данные, которые нужно загрузить в Sandbox, делается sky share, потом rbtorrent-ссылка используется для загрузки; --canonize-via-http: загрузка только через протокол http. Просмотр ретроспективы канонического результата теста Для того, чтобы посмотреть, как менялся канонический результат теста, нужно прогнать конкретный тест в режиме --canon-diff ya make -t --canon-diff PREV. Можно передать имя теста через параметр -F(--test-filter), для этого можно сначала вывести список тестов в текущей папке ( ircadii/ya make -t --canon-diff HEAD -L); В качестве аргумента --canon-diff можно передать PREV, HEAD, :. Данным режимом удобно пользоваться, когда результат частично или целиком был загружен в Sandbox, и svn diff не очень помогает. Скачивание канонических данных из разных хранилищ Данный режим может быть полезен, если ваши тесты могут запускаться как внутренними, так и внешними людьми без доступов к аркадийным сервисам. Такой сценарий может возникнуть, например, если ваш проект живет одновремменно и в ИРАКАДИИ и в opensource. Канонизация с указанием backend Чтобы результаты канонизации могли быть переиспользованы разными backend-ами, нужно при канонизации тестов добавить --canonization-backend="storage.ypurdomen.xx/get-devtools". При таком запуске, результаты канонизации будут загружены в mds-хранилище, но backend в canondata будет записан в виде шаблона, который может резолвиться в canonization-backend. Параметризация backend Чтобы подменить backend при запуске тестов с канонизацией, нужно указать --canonization-backend="<custom_backend>", где custom_backend - это http-хранилище, куда вы сами загрузили результаты канонизации. Если тесты канонизировались с использованием бэкенда, но --canonization-backend при запуске тестов не был указан, то будет использоваться storage.ypurdomen.xx/get-devtools Параметризация протокола При запуске тестов с указанием кастомного бэкенда, вы можете сами выбрать протокол для скачивания канонических данных с помощью опции --canonization-scheme. Если этот параметр не указан, будет использоваться https. Формат После канонизации, рядом с тестом появляется файл canondata/result.json внутри него лежат ссылки, куда были загружены канонические данные. В случае запуска канонизации без дополнительных опций, канонизационные backend'ы в этих ссылках будут указаны явно. При указании --canonization-backend, в ссылках вместо явного укзаания бэкенда, будет присутствовать место для его подстановки. Внутри canondata/result.json нас будет интересовать поле uri у канонических данных. Внутри этого поля лежат ссылки для скачивания канонических данных. Без --canonization-backend: uri: https://storage.ypurdomen.xx/get-devtools/1936842/8e0725ae6bf6a51c5b510adf7ab5b65a0a685a8f/resource.tar.gz#exectest.run_hello_world_/stdout.out С --canonization-backend uri: https://{canondata_backend}/1809005/61174eb05585f2f1c67e0387c436e184f0ccc131/resource.tar.gz#exectest.run_hello_world0_/stdout.out рассмотри подробнее формат uri: схема - https бэкенд - storage.ypurdomen.xx/get-devtools путь до архива в mds-storage - 1936842/8e0725ae6bf6a51c5b510adf7ab5b65a0a685a8f/resource.tar.gz путь до файла внутри архива - exectest.run_hello_world_/stdout.out При загрузке данных в пользовательский storage, нужно сохранить формат uri, изменив только бэкенд и, возможно протокол, чтобы после подстановки вашего backend в uri получалась валидная ссылка. Проверки кода и корректности данных Система сборки поддерживает разнообразные проверки стиля и кода. Большинство из них является opt-out, т.е. подключаются автоматически, с возможностью отключения. ya test / ya make -t поддерживает ключ --style, который запускает только style-тесты и легковесные проверки, к которым не относятся регулярные тесты. Если запускаемые проверки не зависят от сборки, то ya test --style запустит только линтеры, без сборки. Примечание Все style-тесты по умолчанию кешируются, что эквивалентно команде ya test --cache-tests. Это значит, что при перезапуске ya test без изменения исходного кода style-тесты не будут перезапускаться, а вернут результат из кеша. Это сделано для ускорения локального прогона style-тестов, которые являются быстрыми и стабильными. Для принудительного перезапуска тестов нужно добавить ключ --retest. python flake8 Все python-файлы, используемые в сборке и тестах, подключаемые через ya.make в секциях PY_SRCS и TEST_SRCS, автоматически проверяются линтером flake8. Допустимая длина строки установлена в 200 символов. В редких случаях можно игнорировать конкретные строки целиком, указывая конкретные коды ошибок, добавляя к нужной строке комментарий # noqa или # noqa: E101. Внутри init.py можно подавлять только ошибку F401 Module imported but unused с помощью комментария # flake8 noqa: F401 в начале файла. Примечание Только для директории contrib допустимо отключение проверки стиля макросом NO_LINT(). В ИРАКАДИИ используется единый конфиг, через который включаются некоторые плагины. Изменения в конфиге должны быть согласованы с python-com@. Важно Если локально у вас есть ошибки flake8, которых нет в Автосборке/CI, скорей всего вы столкнулись с вашим техдолгом, см. документацию о миграциях. Для временного отключения подобных ошибок используйте запуск YA_TEST_DISABLE_FLAKE8_MIGRATIONS=0 ya test и запланируйте починку. Коды ошибок описаны на следующих страницах:
flake8rules.com pypi.org/project/flake8-commas pydocstyle.org bandit.readthedocs.io black Для проектов на python3 можно добавить макрос STYLE_PYTHON(), который будет генерировать тест, проверяющий соответствие кода в модуле аркадийному style guide. В качестве линтера использует black c минимальным конфигом, который применяется в ya style. Примечание Макрос STYLE_PYTHON() можно указывать только для типов модулей PY3* и PY23*. Быстро добавить макрос в проект можно командой: ya project macro add STYLE_PYTHON --recursive --quiet --after PY3_LIBRARY --after PY23_LIBRARY --after PY3TEST --after PY23_TEST --after PY3_PROGRAM Для запуска только black тестов внутри проекта используйте команду ya test --test-type black. Для автоматического применения ya style в PyCharm см. заметку от srg91. python imports Для программ PY2_PROGRAM, PY3_PROGRAM, PY2TEST, PY3TEST, PY23_TEST, собранных из модулей на Python, есть проверка внутренних модулей на их импортируемость - import_test. Импорт-тесты не являются style-тестами и не входят в множество тестов --style, так как требуют сборку. Импорт-тесты обнаруживают на ранних стадиях конфликты между библиотеками, которые подключаются через PEERDIR, а также указывают на неперечисленные в PY_SRCS файлы (но TEST_SRCS не проверяется). Проверять герметичность каждого модуля python достаточно дорого - требуется сборка python и его компоновка с целевым модулем только для одного теста, поэтому проверка импортируемости добавляется только для исполняемых программ, которые будут работать в таком виде на production. По этой причине проверяются только модули, подключаемые к сборке через PY_SRCS, но не через TEST_SRCS. Проверку можно отключить c помощью макроса NO_CHECK_IMPORTS. Он принимает список масок модулей, которые не нужно проверять: NO_CHECK_IMPORTS( devtools.pylibrary.* ) В программах можно написать NO_CHECK_IMPORTS() без параметров, чтобы полностью отключить проверку импортов. Бывает, что в общих библиотеках импорты происходят по условию, например в psutil: if sys.platform.startswith("win32"): import psutil._psmswindows as _psplatform При этом сама библиотека остаётся работоспособной, но импорт-тест будет падать, потому что проверяет все модули, влинкованные в бинарник, а у psutil._psmswindows есть зависимость от Windows. В таком случае надо написать:
NO_CHECK_IMPORTS( psutil._psmswindows ) Примечание Информацию о времени загрузки импортированных модулей после исполнения импорт-теста записывается в файл *.import_test.out соответсвующего теста. В конце файла можно найти список самых медленных импортов, исполненных в тесте. Примечание Если информации о времени исполнения импортов недостаточно и хочется получить больше деталей о причинах медленной загрузки модулей, то можно отпрофилировать основную точку входа импорт-теста, используя ваш любимы профайлер (например cProfile). java java style На все исходные тексты на Java, которые подключены через ya.make в секции JAVA_SRCS, запускаются автоматические проверки java codestyle. Проверки осуществляются при помощи утилиты [checkstyle](http://checkstyle.sourceforge.net checkstyle) версии 7.6.1. Мы поддерживаем 2 уровня "строгости" - обычный и строгий (большее количество проверок). Строгий уровень включается макросом LINT(strict) в ya.make. Конфигурационные файлы checkstyle для обычных и строгих проверок находятся в директории resource, табличка с описанием находится тут. java classpath clashes Есть опциональная проверка дублирующихся классов в classpath при компиляции java проекта. Проверяется имя класса и хэш файла с его исходным кодом, то есть идентичные классы из разных библиотек проблем вызывать не должны. Проверка включается макросом CHECK_JAVA_DEPS(yes) в ya.make. kotlin ktlint Автоматически добавляется к проектам на Kotlin, которые используют нашу систему сборки. Подробнее про утилиту можно узнать тут. Для отключения ktlint достаточно в ya.make файле модуля написать NO_LINT(ktlint). При запусках ktlint использует корневой .editorconfig. Исключения ktlint Для проекта можно настроить временные исключения из правил. Применять исключения нужно крайне редко в сложных случаях, например, при миграциях на новый ktlint и при наличии множества ошибок, которые нельзя исправить автоматически после выполнения команды ktlint -F. В случае применения исключений разработчик обязан создать тикет на исправление всех ошибок в исключении и запланировать его выполнение. Как добавить исключения в проверки: Создать файл с исключениями путем выполнения команды из корня ircadii ya tool ktlint {path-to-project} --baseline={path-to-project}/{path-to-file}. Создать тикет в очередь проекта на исправление всех ошибок в исключении. Добавить в ya.make проекта макрос с указанием относительного пути до файла с исключениями и ссылку на тикет с исправлениями. Например, KTLINT_BASELINE_FILE(ktlint-baseline.xml "https://st.ypurdomen.xx/REMOVE-BASELINE-1") go gofmt Автоматически добавляется к проектам на go, является проверкой стиля. Подробнее см. документацию к gofmt. govet Автоматически добавляется к проектам на go, является статической проверкой, позволяющей находить подозрительные конструкции и плохие практики. Подробнее см. документацию. cpp clang tidy Clang-tidy запускается с помощью ya test -DTIDY, так как требует полностью другой граф сборки. Подробнее см. отдельный раздел про clang tidy. frontend eslint Автоматически добавляется к проектам на TypeScript, использует ESLint. Проверяет стиль кода и типичные ошибки. Набор правил лежит здесь. Для отключения eslint достаточно в ya.make файле модуля написать NO_LINT(). external resources sandbox resource Не является style-тестом. В тестах можно использовать Sandbox-ресурсы в виде зависимостей. Такие ресурсы должны иметь ttl = inf, чтобы тесты сохраняли свою работоспособность даже после того, как новая версия теста начнёт использовать другую версию ресурса. Поэтому ко всем suite, использующим Sandbox-ресурсы, добавляется автоматический тест validate_resource, который проверяет ttl ресурса. Так как тест обязан кешироваться, то он зависит исключительно от номера ресурса, в противном случае на каждый коммит в Аркадию все такие тесты пришлось бы перезапускать, тратя ресурсы и создавая нагрузку на Sandbox. Поэтому в случае обнаружения ошибки в PR и исправления ttl у ресурса, в новых итерациях он не перестанет падать. Для этого в ya.make с падающих тестов нужно добавить вызов макроса VALIDATE_DATA_RESTART(Х), где в качестве X указать текущую head-ревизию репозитория. Это значение добавится к расчёту uid теста и в новой итерации в PR тест будет перезапущен. Подробней о VALIDATE_DATA_RESTART см в документации к макросу DATA. Проверку можно отключить макросом DISABLE_DATA_VALIDATION(). clang tidy Для C++ поддержан линтинг исходного кода, из LIBRARY, PROGRAM, DLL, G_BENCHMARK, UNITTEST, GTEST с помощью clang-tidy. Для запуска линтинга нужно вызвать ya make -t -DTIDY. Примечание При запуске ya make с флагом -DTIDY, вместо узлов компиляции запускается clang-tidy для соответствующих исходников. В этом режиме сборки не происходит, так как граф строится в другой конфигурации, хотя и генерируются все необходимые зависимости для тайдинга. Поэтому clang-tidy тесты, и только они могут быть запущены при указании -DTIDY. По умолчанию clang-tidy использует базовый аркадийный конфиг. Изменения в этом конфиге должны быть согласованы с cpp-com@. Чтобы подключить свой проект к линтингу в автосборке, укажите нужный путь в этом файле. Некоторые ошибки, обнаруженные с помощью проверок в clang-tidy, могут быть автоматически исправлены. В этом случае в сниппете suite будет написана команда для их автоматического исправления с помощью ya clang-tidy --fix. Кастомные конфиги для clang-tidy Если ваш проект уже подключен к тайдингу в автосборке и вам хочется расширить множество проверок, вы можете воспользоваться механизмом проектных конфигов для clang-tidy Немного терминологии Базовый конфиг - Конфиг, описывающий основные проверки и их опции для проверок clang-tidy. Конфиг декларируется тут. При создании нового базового конфига, туда заносятся только те проверки и опции, который конфликтуют с ircadii style guide. Если ваш проект использует аркадийный стиль, вам не нужно создавать свой базовый конфиг! Базовый общеаркадийный конфиг - конфиг, по умолчанию являющийся базовым. в этом конфиге описываются основные опции и проверки из ircadii style guide. Проектный конфиг - конфиг, относящийся к отдельному проекту. Создается авторами проектов, декларируется тут. Этот конфиг будет объединен с базовым конфигом, который используется в вашем проекте. Ограничения, накладываемые на проектный конфиг Конфиг не должен противоречить ircadii-style-guide. Проверки из конфига не должны сильно замедлять тайдинг. Для выполнения этих требований мы завели whitelist доступных проверок и их опций. Проверки, не перечисленные в whitelist, будут удалены из конфига. Любые изменения whitelist должны быть одобрены cpp-com@. Создание своего конфига clang-tidy конфиг - это yaml файл, в котором перечислены проверки и их опции. Список доступных проверок можно найти тут. Список опций для проверки можно найти на странице проверки. пример готового конфига. Подключение проектного конфига к автосборке Чтобы в автосборке начал работать ваш конфиг, достаточно добавить ваш проект в словарь. В этом словаре ключ - это префикс относительно корня ircadii, к которому будет применяться ваш конфиг, а значение - путь до конфига относительно корня ircadii. Конфиги для проектов, не соответствующих аркадийному style-guide Если ваш проект использует стиль, отличный от аркадийного, вам нужно создать свой базовый конфиг. Чтобы задекларировать ваш базовый конфиг в системе сборки, вы должны добавить этот конфиг в словарь, по аналогии с проектным конфигом. Сам конфиг стоит положить в директорию, где лежат другие базовые конфиги. В новом базовом конфиге должны содержаться только проверки и опции, которые конфликтуют с ircadii-style-guide. Остальная часть конфига должна быть вынесена в ваш проектный конфиг. Создание и изменение вашего базового конфига должно быть согласовано с cpp-com@ С каким конфигом будет запускаться проверка? Итоговый конфиг будет сконструирован из вашего проектного конфига и базового конфига. Вот как это будет происходить: Отфильтруются все проверки и опции из проектного конфига, в соответствии с whitelist. В итоговый конфиг добавятся оставшиеся проверки из проектного конфига. В итоговый конфиг добавятся проверки из базового конфига. В итоговый конфиг добавятся все опции из базового и проектного конфигов, при возникновении конфликтов побеждает проектный конфиг. схема получения конфига Из-за фильтрации проектного конфига и дальнейшего объединения с базовым, может быть непонятно, с каким конфигом запускается clang-tidy в автосборке. Чтобы решить эту проблему, в хендлере ya clang-tidy поддержана опция --show-autocheck-config, которая выведет финальный автосборочный конфиг на экран. Локальный запуск с проектным конфигом ya make -A -DTIDY - запустит ваши clang-tidy тесты "как в автосборке" ya clang-tidy --use-autocheck-config - Вариант, аналогичный предыдущему. ya clang-tidy --use-autocheck-config --fix - попытается починить обнаруженные проблемы. Если перед этим запускался вариант (2), то результаты тайдинга возьмутся из кэша. ya clang-tidy - запустит проверку с вашим проектным конфигом, игнорируя whitelist и базовый конфиг Включение tidy в CLion Для того чтобы CLion подхватил Аркадийный конфиг clang-tidy нужно сгенерировать проект, добавив опцию --setup-tidy. Для того чтобы не нужно было постоянно указывать ключ, его можно указать в конфиге ya, добавив секцию вида: [ide.clion] setup_tidy = true Подробней о настройке CLion проекта можно почитать в документации ya ide clion. Включение tidy в VS Code Для того чтобы VS Code подхватил Аркадийный конфиг clang-tidy нужно: установить clang-tidy plugin сгенерировать VS Code проект, выполнив ya ide vscode-clangd --setup-tidy в директории нужного проекта Для того чтобы не нужно было постоянно указывать ключ, его можно указать в конфиге ya, добавив секцию вида: [ide.vscode-clangd] setup_tidy = true
Тесты : запуск произвольных программ Данный тип тестов позволяет выполнить произвольную команду и убедиться, что она успешно завершается. Примечание Примеры exec-тестов можно найти здесь. Успешным считается завершение команды с кодом возврата 0. Стандартные программы unix и команды shell не доступны, некоторые аналоги можно подключить через DEPENDS. Простое описание теста в ya.make выглядит так: OWNER(g:some-group) EXECTEST() # Объявляем Exec-тест
RUN( # Команда, которую хотим выполнить cat input.txt ) DATA( # Тестовые данные (здесь лежит input.txt) ircadii/devtools/ya/test/tests/exectest/data ) DEPENDS( # Зависимость от других проектов (здесь лежат исходные коды cat) devtools/dummy_ircadii/cat )
Текущий каталог для теста (каталог с input.txt)
TEST_CWD(devtools/ya/test/tests/exectest/data) END() В общем случае в одном ya.make можно объявить несколько разных команд: OWNER(g:some-group) EXECTEST() RUN( # Первый тест NAME test-1 # Явное объявление имени теста echo "1" ) RUN( # Второй тест NAME test-hello-world echo "Hello, world!" ) END() Каждое объявление макроса RUN - это отдельный тест. Тесты выполняются в том порядке, в котором перечислены в файле. Важно При параллельном запуске тестов в каждый из параллельно выполняемых потоков попадает только часть команд, указанных в ya.make. Поэтому не рекомендуется писать команды, результаты выполнения которых зависят от выполнения команд из вышестоящих макросов RUN. В общем виде макрос RUN предоставляет множество других возможностей: OWNER(g:some-group) EXECTEST() RUN( NAME my-test # Имя теста ENV TZ=Europe/Moscow ENV LANG=ru_RU.UTF-8 # Переменные окружения echo "1" # Команда и ее флаги STDIN {IRCADII_ROOT}/my-project/filename.txt # Файл, который подается с stdin команде STDOUT {TEST_CASE_ROOT}/test.out # Куда сохранить stdout команды STDERR {TEST_CASE_ROOT}/test.err # Куда сохранить stderr команды CWD {IRCADII_BUILD_ROOT}/my-project # Рабочий каталог теста CANONIZE {TEST_CASE_ROOT}/test.out # Путь до файла с эталонными данными (будет сохранен в Sandbox) CANONIZE_LOCALLY {TEST_CASE_ROOT}/test.out # Путь до файла с эталонными данными (будет сохранен в подкаталог canondata) CANONIZE_DIR {TEST_CASE_ROOT}/dir # Путь до директории с эталонными данными (будет сохранён в Sandbox) CANONIZE_DIR_LOCALLY {TEST_CASE_ROOT}/dir # Путь до директории с эталонными данными (будет сохранен в подкаталог canondata) DIFF_TOOL my-project/tools/my-difftool/my-difftool # Путь до исполняемого файла, используемого для сравнения вывода теста с эталонными данными DIFF_TOOL_TIMEOUT # Таймаут на запуск diff_tool ) DEPENDS( my-project/tools/my-difftool ) END() Для указания путей доступны следующие переменные: Переменная Описание {IRCADII_BUILD_ROOT} Корень сборочной директории {IRCADII_ROOT} Корень единого репозитория {TEST_SOURCE_ROOT} Путь к каталогу, в котором находится ya.make-файл текущего теста {TEST_CASE_ROOT} Путь к каталогу с результатами текущего теста {TEST_WORK_ROOT} Путь к рабочему каталогу теста {TEST_OUT_ROOT} Путь к каталогу с результатами прохождения всех тестов (результаты каждого теста лежат во вложенном каталоге) Внимание Программы, подключенные по DEPENDS не складываются в Аркадию, после исполнения теста там может оказаться симлинк, но во время исполнения теста программы там нет. Не используйте {IRCADII_ROOT} для указания пути до запускаемой программы. Бинари обычно доступны вообще без указания пути, но путь от корня Ircadii (без указания корня) тоже сработает. Полезные программы not - инвертирует выходной код нормально завершившейся программы. Иногда нужно проверить, что тестируемая программа при нужных условиях завершается с ненулевым кодом (но не падает и не выходит по сигналу). Не стоит злоупотреблять такими тестами. Пример: RUN( NAME "my_program fails with wrong arguments" not my_program wrong arguments ) DEPENDS( my_project/my_program tools/not ) Тесты Unit-тесты в Ircadii оформляются в виде отдельных целей со своим ya.make. Для их запуска используется команда ya make -t. Подробности есть в документации ya; см. также: RECURSE_FOR_TESTS. Для написания тестов у нас имеется два фреймворка: unittest (наша собственная разработка) и gtest (популярное решение от Google). Также есть библиотека library/cpp/testing/common, в которой находятся полезные утилиты, не зависящие от фреймворка. Поддержка gtest в Ircadii появилась недавно, поэтому фреймворк не очень распространен. Тем не менее, у него есть ряд преимуществ по сравнению с unittest: очень подробно выводится контекст, когда ломается тест; два семейства макросов для сравнения: ASSERT останавливает тест, EXPECT отмечает тест как проваленный, но не останавливает его, давая возможность выполнить остальные проверки; возможность расширять фреймворк с помощью механизма матчеров; можно использовать gmock (справедливости ради заметим, что gmock можно использовать и в unittest; однако в gtest он проинтегрирован лучше, а проекты уже давно объединены); можно сравнивать некоторые типы — и даже получать относительно понятное сообщение об ошибке — даже если не реализован operator<<; интеграция почти с любой IDE из коробки; фреймворк известен во внешнем мире, новичкам не нужно объяснять, как писать тесты; есть поддержка fixtures (в unittest тоже есть, но имеет существенные недостатки реализации); есть поддержка параметрических тестов (один и тот же тест можно запускать с разными значениями входного параметра); можно использовать в open-source проектах. К недостаткам gtest можно отнести: отсутствие поддержки аркадийных стримов. Впрочем, для популярных типов из util мы сделали собственные реализации PrintTo; отсутствие макроса, проверяющего, что код бросает ошибку с данным сообщением. Мы сделали такой макрос сами, а также добавили несколько полезных матчеров; Четких рекомендаций по выбору фреймворка для тестирования нет — руководствуйтесь здравым смыслом, обсудите с командой, взвесьте все «за» и «против». Учитывайте, что при смене типа тестов с unittest на gtest потеряется история запуска тестов в CI. Впрочем, если ваши тесты не мигают (а мы очень на это надеемся), история вам и не нужна. Gtest Подробная документация по gtest доступна в официальном репозитории gtest и gmock. Этот раздел дает лишь базовое представление о фреймворке, а также описывает интеграцию gtest в Аркадию. Для написания тестов с этим фреймворком используйте цель типа GTEST. Минимальный ya.make выглядит так: GTEST() OWNER(...) SRCS(test.cpp ...) END() Поддерживаются стандартные для Ircadii настройки тестов: TIMEOUT, FORK_TESTS и прочие. Подробнее про это написано в документации ya. Внутри cpp файлов с тестами импортируйте library/cpp/testing/gtest/gtest.h. Этот заголовочный файл подключит gtest и наши расширения для него. Для объявления тестов используйте макрос TEST. Он принимает два параметра: название группы тестов (test suite) и название конкретного теста. Примечание В ircadii своя реализация функции main, реализовывать ее не нужно. Для кастомизации своих тестов можно воспользоваться хуками из library/cpp/testing/hook. Пример минимального cpp файла с тестами: #include <library/cpp/testing/gtest/gtest.h>
TEST(BasicMath, Addition) { EXPECT_EQ(2 + 2, 4); }
TEST(BasicMath, Multiplication) { EXPECT_EQ(2 * 2, 4); } Для выполнения проверок в теле теста используйте специальные макросы. Они, в отличие от стандартных Y_ASSERT и Y_ABORT_UNLESS, умеют печатать развернутые сообщения об ошибках. Например, ASSERT_EQ(a, b) проверит, что два значения равны; в случае, если это не так, макрос отметит тест как проваленный и остановит его.
Каждый макрос для проверки имеет два варианта: ASSERT останавливает тест, EXPECT — нет. По-умолчанию используйте EXPECT, так вы получите больше информации после запуска тестов. Используйте ASSERT только если проверяете условие, от которого зависит корректность дальнейшего кода теста:
TEST(EtheriaHeart, Activate) { auto* result = NEtheria::Activate();
// Если указатель нулевой, последующие проверки приведут к UB. ASSERT_NE(result, nullptr); EXPECT_EQ(result->Code, 0); EXPECT_EQ(result->ConnectedCrystals, 5); EXPECT_GE(result->MaxPower, 1.5e+44);} Полный список доступных макросов есть в официальной документации и документации по продвинутым возможностям gtest. Также gtest позволяет добавить к каждой проверке пояснение. Оно будет напечатано если проверка провалится. Для форматирования пояснений используется std::ostream: TEST(LotrPlot, Consistency) { EXPECT_GE(RingIsDestroyed() - FrodoLeftHobbiton(), TDuration::Days(183)) << no, eagles were not an option because << Reasons(); } Для более сложных проверок предусмотрен механизм матчеров. Например, проверим, что контейнер содержит элемент, удовлетворяющий определенному условию: TEST(GtestMatchers, SetElements) { THashSet elements{"water", "air", "earth", "fire"}; EXPECT_THAT(elements, testing::Contains("air")); EXPECT_THAT(elements, testing::Contains(testing::StrCaseEq("Fire"))); } Наши расширения добавляют макрос для проверки сообщений в исключениях: TEST(YException, Message) { EXPECT_THROW_MESSAGE_HAS_SUBSTR( ythrow yexception() << "black garnet is not active", yexception, "not active"); Для тестирования кода, прекращающего выполнение приложения (например, выполняющего Y_ASSERT или Y_ABORT_UNLESS), используйте макросы EXPECT_DEATH, EXPECT_DEBUG_DEATH, ASSERT_DEATH, ASSERT_DEBUG_DEATH: TEST(Vector, AccessBoundsCheck) { TVector empty{}; EXPECT_DEBUG_DEATH(empty[0], "out of bounds"); } Матчер NGTest::GoldenFileEq(filename) описан в разделе канонизация. Unittest Для написания тестов с этим фреймворком используйте цель типа UNITTEST. Минимальный ya.make выглядит так: UNITTEST() OWNER(...) SRCS(test.cpp ...) END() Поддерживаются стандартные для Ircadii настройки тестов: TIMEOUT, FORK_TESTS и прочие. Подробнее про это написано в документации ya. Внутри cpp файлов с тестами подключите library/cpp/testing/unittest/registar.h. Важно
Не подключайте файл library/cpp/testing/unittest/gtest.h — это deprecated интерфейс unittest, который пытается выглядеть как gtest. Для объявления группы тестов используйте макрос Y_UNIT_TEST_SUITE. Для объявления тестов внутри группы используйте макрос Y_UNIT_TEST. Пример минимального cpp файла с тестами: #include <library/cpp/testing/unittest/registar.h>
Y_UNIT_TEST_SUITE(BasicMath) { Y_UNIT_TEST(Addition) { UNIT_ASSERT_VALUES_EQUAL(2 + 2, 4); }
Y_UNIT_TEST(Multiplication) { UNIT_ASSERT_VALUES_EQUAL(2 * 2, 4); }} Для выполнения проверок в теле теста используйте специальные макросы: Макрос Описание UNIT_FAIL(M) Отметить тест как проваленный и остановить его. UNIT_FAIL_NONFATAL(M) Отметить тест как проваленный но не останавливать его. UNIT_ASSERT(A) Проверить, что условие A выполняется. UNIT_ASSERT_EQUAL(A, B) Проверить, что A равно B. UNIT_ASSERT_UNEQUAL(A, B) Проверить, что A не равно B. UNIT_ASSERT_LT(A, B) Проверить, что A меньше B. UNIT_ASSERT_LE(A, B) Проверить, что A меньше или равно B. UNIT_ASSERT_GT(A, B) Проверить, что A больше B. UNIT_ASSERT_GE(A, B) Проверить, что A больше или равно B. UNIT_ASSERT_VALUES_EQUAL(A, B) Проверить, что A равно B. В отличие от UNIT_ASSERT_EQUAL, воспринимает char* как null-terminated строку, а также печатает значения переменных с помощью IOutputStream при провале проверки. UNIT_ASSERT_VALUES_UNEQUAL(A, B) Проверить, что A не равно B. В отличие от UNIT_ASSERT_UNEQUAL, воспринимает char* как null-terminated строку, а также печатает значения переменных с помощью IOutputStream при провале проверки. UNIT_ASSERT_DOUBLES_EQUAL(E, A, D) Проверить, что E и A равны с точностью D. UNIT_ASSERT_STRINGS_EQUAL(A, B) Проверить, что строки A и B равны. В отличие от UNIT_ASSERT_EQUAL, воспринимает char* как null-terminated строку. UNIT_ASSERT_STRINGS_UNEQUAL(A, B) Проверить, что строки A и B не равны. В отличие от UNIT_ASSERT_UNEQUAL, воспринимает char* как null-terminated строку. UNIT_ASSERT_STRING_CONTAINS(A, B) Проверить, что строка B является подстрокой в A. UNIT_ASSERT_NO_DIFF(A, B) Проверить, что строки A и B равны. Печатает цветной diff строк при провале проверки. UNIT_ASSERT_EXCEPTION(A, E) Проверить, что выражение A выбрасывает исключение типа E. UNIT_ASSERT_NO_EXCEPTION(A) Проверить, что выражение A не выбрасывает исключение. UNIT_ASSERT_EXCEPTION_CONTAINS(A, E, M) Проверить, что выражение A выбрасывает исключение типа E, сообщение которого содержит подстроку M. У каждого макроса UNIT_ASSERT есть версия UNIT_ASSERT_C, позволяющая передать пояснение к проверке. Например: UNIT_ASSERT_C(success, "call should be successful"); UNIT_ASSERT_GT_C(rps, 500, "should generate at least 500 rps"); Mock Для реализации mock-объектов мы используем gmock. Если вы используете gtest, gmock подключен автоматически. Если вы используете unittest, для подключения gmock нужно добавить PEERDIR на library/cpp/testing/gmock_in_unittest и импортировать файл library/cpp/testing/gmock_in_unittest/gmock.h. Доступ к зависимостям Если вы используете в своем ya.make зависимости, то обращаться к таким данным в коде теста нужно, используя библиотеку library/cpp/testing: #include <library/cpp/testing/common/env.h> void ReadDependency() { // Путь до файла/директории из репозитория, описанных с помощью макроса DATA("ircadii/devtools/dummy_ircadii/cat/main.cpp") TString testFilePath = ArcadiaSourceRoot() + "/devtools/dummy_ircadii/cat/main.cpp";
// Путь до Sandbox-ресурса, описанного макросом DATA(sbr://53558626) # test.txt TString sandboxResourcePath = GetWorkPath() + "/test.txt"; // Путь до файла из DEPENDS("devtools/dummy_ircadii/cat") // Обратите внимание: путь в DEPENDS указывает до сборочной цели, а BinaryPath требует указания пути до файла TString binaryFilePath = BinaryPath("devtools/dummy_ircadii/cat/cat");} Утилиты для тестирования Все функции и утилиты, которые не зависят от тестового фреймворка распологаются в директории common Получение сетевых портов в тестах: Для получения сетевого порта в тестах необходимо использовать функцию NTesting::GetFreePort() из network.h, которая вернет объект - владелец для порта. Порт будет считаться занятым до тех пор, пока владелец жив. Во избежание гонок с выделением портов необходимо держать объект-владелец в течении всей жизни теста, или по крайней мере пока в тесте не запустится сервис, который вызовет bind на этом порту. Пример использования: #include <library/cpp/testing/common/network.h> TEST(HttpServerTest, Ping) { auto port = NTesting::GetFreePort(); auto httpServer = StartHttpServer("localhost:" + ToString(port)); auto client = CreateHttpClient("localhost:" + ToString(port)); EXPECT_EQ(200, client.Get("/ping").GetStatus()); } Функции для получения путей для корня ircadii и до корня билд директории в тестах. Все функции расположены в файле env.h с описанием. Хуки для тестов Хуки позволяют выполнять различные действия при старте или остановке тестовой программы. Подробнее про использование можно прочитать в README.md Тесты с канонизацией вывода Тесты с канонизацией вывода используются для регрессионного тестирования. При первом запуске теста вывод тестируемой программы сохраняется, при последующих запусках система проверяет, что вывод не изменился. К сожалению, в C++ такие тесты в данный момент не поддерживаются. За состоянием поддержки этой возможности можно следить в задаче DEVTOOLS-1467. Параметры теста Поведение тестов можно настраивать, передавая в них параметры. При запуске тестов, используйте ключ --test-param чтобы передать в тест пару ключ-значение. Например: ya make -t --test-param db_endpoint=localhost:1234. Для доступа к параметру из теста используйте функцию GetTestParam: TEST(Database, Connect) { auto endpoint = GetTestParam("db_endpoint", "localhost:8080"); // ... } Метрики теста Наш CI поддерживает возможность выгрузки из теста пользовательских метрик. У каждой метрики есть название и значение — число с плавающей точкой. CI покажет график значений метрик на странице теста. Для добавления метрик используйте функцию testing::Test::RecordProperty если работаете с gtest, или макрос UNIT_ADD_METRIC если работаете с unittest. Например, создадим метрики num_iterations и score: TEST(Solver, TrivialCase) { // ... RecordProperty("num_iterations", 10); RecordProperty("score", "0.93"); } Важно RecordProperty принимает на вход целые числа и строки. Наш CI не умеет работать со строковыми значениями метрик, поэтому каждую строку он будет воспринимать как число. В случае, если строку не удастся преобразовать в число, тест упадет. Бенчмарки Для написания бенчмарков мы используем библиотеку google benchmark и цель G_BENCHMARK в ya.make файле — пример. G_BENCHMARK поддержан на уровне ya make -t / ya test Все подключенные к автосборке G_BENCHMARK запускаются в CI по релевантным коммитам и накапливают историю метрик, которая может быть полезна для поиска регрессий. Для G_BENCHMARK доступно: Листинг бенчмарков: ya test -rL - выведет список доступных бенчмарков Вывод метрик на консоль: ya test -r -P --show-metrics Фильтрация: ya test -rF - запустит все бенчмарки, удовлетворяющие Сбор корок в случае таймаута или падения бенчмарка по сигналу Graceful обработка таймаута - при таймаутах мы сохраняем весь текущий прогресс и строим итоговый отчет о тестировании, основываясь на этой информации. Сбор метрик для успешно завершившихся бенчмарков. При запуске в автосборке, эти метрики можно будет увидеть на странице теста в CI. Для G_BENCHMARK недоступно:
FORK_(SUB)TESTS: предполагается, что G_BENCHMARK это микробенчмарки и в параллельном запуске нет необходимости. Дополнительные опции для benchmark C помощью макроса BENCHMARK_OPTS() можно передать дополнительные параметры в запуск benchmark. Например BENCHMARK_OPTS( --benchmark_min_time=2 --benchmark_min_iters=1 ) Тесты с Sanitizer ya make -t --sanitize X позволяет собирать инструментированные программы с санитайзерами. Сейчас поддерживаются: address, memory, thread, undefined, leak. Можно указывать только один санитайзер за раз. Параметризация опций санитайзеров Локальный запуск ya make -t --sanitize X учитывает стандартные опции для санитайзеров переданные через переменные окружения. По умолчанию тестовая машинерия добавляет всем санитайзерам опцию exitcode=100 для специальной обработки падений тестов в этой конфигурации. В UBSAN_OPTIONS дополнительно выставляются опции print_stacktrace=1,halt_on_error=1. Вы можете зафиксировать опции санитайзеров для конкретных тестов через макрос ENV() в ya.make, например: ENV(ASAN_OPTIONS=detect_stack_use_after_return=1) Cборка с санитайзером в Sandbox Для сборки следует использовать задачу YA_MAKE/YA_MAKE2, в которой можно выбрать требуемый санитайзер в поле Build with specified sanitizer Запуск тестов c санитайзером в Автосборке В автосборке подключены 2 типа cанитайзеров: memory и address, так как они достаточно легковесны и стабильны. Для подключения проекта ко всем типам cанитайзеров следует добавить свой проект в autocheck/linux/sanitizer_common_targets.inc Если требуется только memory санитайзер, то в autocheck/linux/sanitizer_memory_targets.inc Если требуется только address санитайзер, то в autocheck/linux/sanitizer_address_targets.inc Отключение тестов от сборки с санитайзерами Вы можете сделать проект не достижимым по рекурсам для санитайзеров, подключив проекты более гранулярно. См. предыдущий абзац. Вы можете сделать проект не достижимым по рекурсам для санитайзеров, например: IF (NOT SANITIZER_TYPE) RECURSE_FOR_TESTS( test ) ENDIF() Отключить конкретный тест с помощью тега ya:not_autocheck, например: IF (SANITIZER_TYPE) TAG(ya:not_autocheck) ENDIF() Отключить инструментирование конкретной библиотеки c помощью макроса NO_SANITIZE() С помощью макроса SUPPRESSIONS() можно указать файл содержащий правила для подавления ошибок в стандартной нотации с поддержкой комментариев начинающихся с #. Механизм поддерживается для address, leak и thread санитайзеров. Пример для protobuf: ya.make tsan.supp Важно Добавлять исключения следует только если вы переносите известные исключения из контриба или отчётливо понимаете, что сообщение от санитайзеров ложноположительное (скорей всего нет и вам следует внимательней разобраться в проблеме). Каждое обновление кода или компилятора должно приводить к пересмотру suppression списка. Отладка тестов санитайзера Для отладки падающих тестов нужно собрать библиотеку с включённым санитайзером. Для этого в ya make нужно передать дополнительный флаг --sanitize=memory (на примере санитайзера памяти, см. выше). Возможно, для воспроизведения потребуется также повторить настройки оптимизации --build=release. Для перехвата исключения под отладчиком нужно добавить точку останова: br __msan_warning_with_origin_noreturn (если не сработает, см. другие варианты тут и тут). Под отладчиком же можно посмотреть, что санитайзер думает про каждый бит используемой памяти: call (void)__msan_print_shadow(&myVar, sizeof(myVar)) (в vscode перед командой нужно добавить -exec, вводить в окне Debug Console, а результаты смотреть в Terminal). Согласно документации единичные биты обозначают неинициализированную память. " Напиши "Готов писать документацию", после изучения информации.
- Assistant
Готов писать документацию
- User
подробно с объяснениями опиши опцию системы сборки -b, --build-all Собрать цели, не требуемые для запуска тестов, но достижимые с RECURSE’s
- Assistant
Опция
-bили--build-allсистемы сборки является важным инструментом для управления процессом сборки проектов, особенно когда дело касается тестирования и взаимодействия различных компонентов системы. Давайте разберемся, что означает эта опция и зачем она может быть использована.Что делает
-bили--build-all?Опция
-bили--build-allпри использовании в командной строке системы сборки (например,ya make -t -b) указывает системе сборки собрать все цели, которые могут быть достигнуты через директивыRECURSEвya.makeфайле, даже если эти цели не требуются непосредственно для запуска текущих тестов.Зачем это нужно?
В большом и сложном проекте, содержащем множество зависимостей и подпроектов, не всегда очевидно, какие именно компоненты требуются для выполнения определенного набора тестов. По умолчанию, система сборки пытается оптимизировать процесс, собирая только то, что действительно необходимо для запуска запрашиваемых тестов. Это хорошо с точки зрения экономии времени и ресурсов.
Тем не менее, в некоторых случаях может возникнуть потребность в полной сборке всех компонентов программного продукта, даже тех, которые не используются в тесте напрямую. Например:
- Проверка полной интеграции: Чтобы убедиться в том, что все компоненты системы способны корректно работать вместе, требуется сборка полного проекта.
- Обновления в зависимостях: Если в проекте были сделаны обновления, которые могут косвенно повлиять на работу других компонентов, полезно провести полную сборку для выявления возможных проблем.
- Подготовка к деплою: В рамках подготовки к деплою или публикации проекта важно убедиться, что все его части собраны и готовы к использованию.
Как это работает?
При вызове системы сборки с опцией
-bили--build-all, система анализируетya.makeфайлы на предмет директивRECURSE, прослеживая все возможные пути сборки до каждого компонента проекта. Это включает в себя все библиотеки, программы, тесты и прочие цели, которые можно собрать. В результате, процесс сборки охватывает весь проект в полном объеме, не ограничиваясь только требуемыми для тестирования компонентами.Важно понимать, что использование этой опции может значительно увеличить время сборки, особенно для больших проектов с множеством зависимостей. Поэтому важно применять её осознанно, когда действительно требуется полная сборка.
Пример использования
Предположим, у вас есть проект со множеством модулей и подмодулей, и вы хотите убедиться, что недавно внесенные изменения не поломали сборку других не связанных напрямую с тестами компонентов. Вызывая команду:
ya make -t -bвы инициируете полную сборку проекта, что позволит обнаружить и предотвратить возможные проблемы до момента деплоя или передачи продукта заказчику.
- User
подробно с объяснениями опиши опцию системы сборки --build-only-test-deps Собрать только цели, требуемые для запрашиваемых тестов
- Assistant
Опция
--build-only-test-depsсистемы сборки – это ключевой инструмент при выполнении тестов, который позволяет оптимизировать процесс сборки, фокусируясь исключительно на тех компонентах системы, которые необходимы для выполнения заданных тестов. Эта опция существенно снижает время и ресурсы, требуемые для сборки, поскольку исключает из процесса компоненты, не участвующие в тестировании.Как работает
--build-only-test-deps?При запуске системы сборки с этой опцией, механизм сборки проанализирует зависимости тестов, которые были запрошены для выполнения. Включение только необходимых для тестов зависимостей позволяет исключить из сборочного процесса все лишнее, что не имеет отношения к текущему тестовому прогону.
Вместо того, чтобы следовать всем путям в директивах
RECURSEи собирать весь проект полностью (что может быть весьма времязатратно и ресурсоемко), система сборки сфокусирована только на той части проекта, которая действительно используется в тестах.Зачем использовать эту опцию?
Основная цель опции
--build-only-test-deps– повышение эффективности процесса разработки и тестирования. Минимизируя количество собираемых компонентов, разработчики могут быстрее получить результаты тестов и сэкономить ресурсы сборочной машины.Эта опция особенно полезна в больших проектах со множеством модулей и компонентов, когда необходимо быстро проверить изменения в конкретной части системы, не тратя время на сборку нерелевантных частей.
Пример использования
Предположим, разработчик внес изменения в модуль, отвечающий за логику работы сетевых запросов, и хочет запустить только тесты, относящиеся к этому модулю, не собирая остальную часть проекта. В этом случае команда для сборки и тестирования будет выглядеть примерно так:
ya make -t --build-only-test-deps network_testsЗдесь
network_tests– это идентификатор или путь к тестам, которые необходимо выполнить. Система сборки выполнит анализ, определит, какие компоненты проекта требуются для выполнения данного набора тестов, и соберет только их.Важные замечания
- Использование
--build-only-test-depsпредполагает, что разработчик знает, какие тесты ему нужно запустить, и какие компоненты системы они затрагивают. - Несмотря на удобство этой опции для быстрого тестирования, периодически следует выполнять полную сборку проекта, чтобы убедиться в корректной интеграции всех его частей.
В заключение, опция
--build-only-test-depsявляется ценным инструментом для оптимизации процесса тестирования, позволяя сосредотачиваться на реально используемых зависимостях и экономить время и системные ресурсы. - Использование
- User
подробно с объяснениями опиши опцию системы сборки --strip-skipped-test-deps Не собирать зависимости пропущенных тестов
- Assistant
Опция
--strip-skipped-test-depsв системе сборки представляет собой эффективный инструмент для оптимизации процесса запуска тестов, поскольку она позволяет исключить из процесса сборки зависимости тех тестов, которые по тем или иным причинам будут пропущены. Это означает, что система сборки не будет тратить время и ресурсы на подготовку тестов и их зависимостей, которые итак не будут выполнены. Давайте более подробно рассмотрим работу этой опции и её влияние на процесс разработки.Как работает
--strip-skipped-test-deps?Когда вы запускаете систему сборки с этой опцией, механизм сборки проводит предварительный анализ запрашиваемых для выполнения тестов. Если на основании конфигурации запуска или внешних условий (например, фильтров, указанных разработчиком) определённые тесты маркированы к пропуску, то все зависимости, которые необходимы исключительно для этих тестов, будут исключены из сборки.
Польза использования
--strip-skipped-test-deps- Уменьшение времени сборки: Основным и, пожалуй, самым очевидным преимуществом является сокращение общего времени на процесс сборки, поскольку система не будет заниматься бесполезной генерацией артефактов для пропущенных тестов.
- Снижение нагрузки на ресурсы: Уменьшается потребление ресурсов машины (CPU, оперативная память, дисковое пространство), так как работа будет сосредоточена только на актуальных для запуска целях.
- Более чистое тестирование: Тестовый процесс становится более предсказуемым и менее подверженным случайным факторам, связанным с поведением не используемых компонентов.
Сценарий использования
Рассмотрим пример, когда команда разработки работает над большим проектом с множеством модулей и подмодулей. Изменения вносятся в один модуль, и разработчики хотят запустить только тесты, связанные с этим модулем, пропуская все остальные. В данном случае запуск сборки с опцией
--strip-skipped-test-depsпозволит существенно ускорить процесс, исключив несвязанные с текущим заданием проверки и их зависимости.Подводные камни
Использование опции
--strip-skipped-test-depsтребует от разработчиков ясного представления о тестовом покрытии кода и зависимостях между различными частями системы. Важно помнить, что пропуск сборки зависимостей для неиспользуемых тестов может привести к отсутствию важных проверок, если выборка тестов настроена неправильно.Заключение
Опция
--strip-skipped-test-depsявляется мощным инструментом для оптимизации процесса тестирования в проектах. Она позволяет сосредоточить ресурсы на сборке и выполнении только тех тестов, которые действительно имеют значение в текущем контексте разработки, тем самым повышая эффективность процесса разработки и тестирования программного обеспечения. Однако, как и любой инструмент, он требует аккуратного и осознанного применения. - User
подробно с объяснениями опиши опцию системы сборки --strip-idle-build-results Удалить все узлы результатов (включая узлы сборки), не требуемые для запуска тестов
- Assistant
Опция
--strip-idle-build-resultsсистемы сборки — это ещё одно мощное средство для оптимизации процесса сборки, особенно когда речь идет о масштабных проектах с множеством модулей и тестов. Эта опция позволяет системе сборки удалить результаты сборки, которые в конечном итоге не используются непосредственно для запуска тестов. Данная функциональность ценится за возможность экономии как времени, так и дискового пространства, освобождая ресурсы для других задач.Как работает
--strip-idle-build-results?Когда вы запускаете систему сборки со включенной опцией
--strip-idle-build-results, в процессе сборки система активно отслеживает, какие именно артефакты (файлы результата сборки) требуются для успешного выполнения заданных тестов. По завершении процесса сборки, вся информация о "лишних" узлах — т.е., те, которые не связаны с запуском тестов — удаляется.Преимущества использования
--strip-idle-build-results- Экономия дискового пространства: Особенно актуально для масштабных проектов, где артефакты сборки могут занимать значительное пространство.
- Уменьшение времени сборки: Удаление ненужных узлов сборки может уменьшить общее время, требуемое для сборки и подготовки тестов.
- Повышение эффективности: Освобождение системных ресурсов позволяет более эффективно использовать их для других процессов, например, для параллельной работы или выполнения более важных задач.
Сценарии использования
- Большие проекты: Где сборка всех модулей и их тестов может затягиваться на длительное время и занимать много места на диске. Это может быть особенно актуально для CI/CD систем, где каждая сборка проекта должна быть максимально эффективной по времени и ресурсам.
- Ограниченные ресурсы: Например, при сборке на локальном компьютере разработчика с ограниченным диском или в условиях ограниченных ресурсов сборочных серверов.
Подводные камни
- Важно понимать, что использование данной опции требует точного понимания зависимостей проекта, так как преждевременное удаление "лишних" узлов может привести к необходимости пересборки некоторых модулей или даже к невозможности выполнения некоторых тестов.
- Также следует быть осторожным с этой опцией при локальной разработке, когда в процессе работы над одной задачей предполагается последующий запуск других тестов или использование собранных артефактов для других целей.
Заключение
Опция
--strip-idle-build-resultsпредставляет собой ценный инструмент для оптимизации процесса сборки в условиях, когда необходима максимальная экономия времени и дискового пространства. Она особо полезна в средах непрерывной интеграции и для проектов с большим количеством модулей и зависимостей. Правильное применение этой опции позволяет существенно увеличить эффективность сборки, однако требует внимательного управления зависимостями и тестами, чтобы не удалились необходимые компоненты. - User
подробно с объяснениями опиши опцию --no-strip-idle-build-results Не удалять узлы результатов (включая узлы сборки), не требуемые для запуска тестов
- Assistant
Опция
--no-strip-idle-build-resultsявляется командой для системы сборки, которая директивно указывает сохранить все результаты сборки (или узлы сборки), включая те, которые не нужны для прямого запуска тестов. Эта опция является противоположностью к--strip-idle-build-results, о которой шла речь ранее. Она обеспечивает более широкий охват сборки, гарантируя, что ничего не будет исключено или удалено из результата сборки, даже если это не нужно непосредственно для тестирования.Как работает
--no-strip-idle-build-results?При запуске системы сборки с использованием опции
--no-strip-idle-build-results, механизм сборки производит компиляцию и сборку всех целей проекта, включая те, что указаны в файлахya.makeчерез директивыRECURSE, без исключения. Это означает, что результаты сборки всех модулей, библиотек, вспомогательных утилит и тестов будут сохранены.Зачем использовать эту опцию?
Использование
--no-strip-idle-build-resultsможет быть полезным в нескольких сценариях:-
Разработка и отладка: В процессе разработки и отладки может потребоваться доступ ко всем артефактам сборки, включая те, что не связаны напрямую с текущим тестом, чтобы вносить изменения и немедленно видеть результаты в контексте всего проекта.
-
Подготовка к деплою: Перед деплоем или релизом проекта полезно убедиться, что все компоненты системы собраны правильно и полностью. Это помогает обнаружить возможные проблемы или недостающие компоненты до публикации.
-
Полная сборка проекта: В некоторых случаях требуется выполнение полной сборки проекта для оценки зависимостей, проверки интеграции модулей или генерации полного набора артефактов.
Пример использования
Предположим, команда разработчиков работает над большим проектом и хочет выполнить полную сборку проекта (включая все модули и тесты) для проведения комплексной проверки перед релизом. В этом случае команда сборки может быть запущена с опцией
--no-strip-idle-build-results, что гарантирует сохранение всех артефактов сборки.ya make --no-strip-idle-build-resultsВажные моменты
-
Эта опция может значительно увеличить время сборки, особенно для крупных проектов, поскольку требует компиляции и сохранения всех компонентов проекта.
-
Опция может привести к увеличению потребления дискового пространства из-за сохранения всех артефактов сборки.
-
Необходимо тщательно взвешивать необходимость полной сборки проекта в зависимости от текущих задач и ресурсов разработчика или команды.
Заключение
Опция
--no-strip-idle-build-resultsявляется полезным инструментом в арсенале разработчика для сценариев, требующих полного охвата и сохранения результатов сборки проекта. Она обеспечивает гибкость и контроль над процессом сборки, позволяя сохранить все узлы результатов для дальнейшей работы, тестирования или деплоя. -
- User
подробно с объяснениями опиши опцию --junit=JUNIT_PATH Путь к генерируемому отчету JUnit
- Assistant
Опция
--junit=JUNIT_PATHв системе сборки предназначена для генерации отчёта о результатах выполнения тестов в формате JUnit. Формат JUnit стал де-факто стандартом для представления результатов тестирования в многих инструментах непрерывной интеграции (CI), таких как Jenkins, GitLab CI и других, благодаря своей универсальности и широкой поддержке.Как работает
--junit=JUNIT_PATH?При запуске тестов с указанием этой опции, система сборки выполняет все запрашиваемые тесты, а затем агрегирует информацию о прохождении каждого теста, результаты (удачные и неудачные исполнения), время выполнения и возможные сообщения об ошибках в один отчет в формате XML, соответствующем спецификации JUnit.
JUNIT_PATHздесь — это путь к файлу, куда будет записан сгенерированный отчет. Этот путь может указывать как на локальный файловый путь в системе разработчика, так и на путь в среде непрерывной интеграции, где отчет будет использоваться для дальнейшего анализа и представления результатов тестирования.Зачем использовать эту опцию?
- Интеграция с системами CI/CD: Упрощает анализ результатов тестирования, интегрируясь с внешними инструментами и сервисами, которые могут автоматически интерпретировать результаты тестов в формате JUnit.
- Унификация отчетности: Позволяет использовать единый формат отчетов при работе с разными языками программирования и тестовыми фреймворками, поддерживающими формат JUnit.
- Более глубокий анализ результатов: Системы CI часто предоставляют расширенные возможности для анализа и визуализации результатов на основе отчетов JUnit, включая тренды, статистики и даже отслеживание изменений в динамике выполнения тестов.
Пример использования
Предположим, что вы разрабатываете проект и используете систему сборки для запуска тестов. Вы хотите получить отчет о результатах тестирования в формате JUnit для интеграции с Jenkins. В этом случае вы можете добавить опцию в вашу команду запуска тестов следующим образом:
ya make -t --junit=/path/to/your/project/test-results/results.xmlПосле выполнения команды в указанном месте
(/path/to/your/project/test-results/results.xml)будет создан файл XML с отчетом о результатах тестирования в формате JUnit, который затем может быть импортирован в Jenkins или любую другую систему, поддерживающую анализ JUnit отчетов.Важные моменты
- До запуска тестов с этой опцией убедитесь, что указанный каталог для сохранения отчета существует, или ваша система сборки имеет разрешение на создание файлов и каталогов в указанном месте.
- Для максимальной совместимости результатов и визуализаций в CI/CD стоит ознакомиться с дополнительными опциями и настройками используемой системы CI по работе с отчетами JUnit.
Использование опции
--junit=JUNIT_PATHпозволяет эффективно интегрировать процесс тестирования в общий рабочий процесс разработки и непрерывную интеграцию, обеспечивая удобство анализа результатов и возможность автоматического уведомления о проблемах, выявленных в ходе тестирования. - User
подробно с объяснениями опиши опцию --no-test-outputs Не сохранять testing_out_stuff
- Assistant
Опция
--no-test-outputsв системе сборки используется для контроля над сохранением выводов тестов, а именно файлов и данных, которые тесты могут генерировать в процессе их выполнения. Это может включать в себя логи выполнения, временные файлы, результаты выполнения и другие "artifacts", созданные тестами. Обозначениеtesting_out_stuffможно интерпретировать как "вещи, созданные - User
продолжай
- Assistant
в процессе тестирования".
Назначение и применение
--no-test-outputsОпция
--no-test-outputsпредставляет собой директиву системе сборки, указывающую не сохранять вышеупомянутые файлы и данные, созданные во время тестирования. Это может быть полезно в различных сценариях, например:- Сокращение объема используемого дискового пространства: Тесты, особенно в больших и комплексных проектах, могут генерировать значительный объем выходных данных. Не сохраняя эти данные, можно значительно экономить место на диске.
- Ускорение процесса сборки и тестирования: Процесс записи данных на диск может занять некоторое время, особенно если генерируемые файлы велики или если тестов много и каждый из них создает выходные данные.
- Улучшение чистоты среды сборки и тестирования: В некоторых случаях может быть важно, чтобы среда сборки и тестирования оставалась максимально "чистой" и не загромождалась лишними файлами, что упрощает анализ результатов и управление средой.
При этом стоит учитывать, что использование
--no-test-outputsможет также означать, что будет потерян важный контекст или диагностическая информация, которую выходные данные могли бы предоставить для анализа проблем и ошибок, выявленных во время тестирования. Поэтому решение о применении этой опции следует принимать, взвешивая нужду в данных против потребностей в ресурсах и чистоте среды.Пример использования
Допустим, проект находится в активной фазе разработки, и разработчики выполняют зацикленные итерации сборки и тестирования на локальной машине. Чтобы минимизировать влияние на дисковое пространство и ускорить процесс выполнения тестов, они могут принять решение временно не сохранять выходные данные тестов с помощью
--no-test-outputs.ya make -t --no-test-outputsВ этом случае система сборки выполнит все запрашиваемые тесты, но не сохранит никаких файлов, созданных в процессе их выполнения.
Заключение
Использование опции
--no-test-outputsпредоставляет гибкость в управлении процессом сборки и тестирования, позволяя ускорить выполнение тестов и сохранить ресурсы системы за счет отказа от сохранения выходных данных тестов. Однако при её применении важно учитывать потенциальные недостатки, связанные с потерей возможности детального анализа результатов тестирования. Поэтому выбор между сохранением и отказом от выходных данных тестов должен базироваться на текущих потребностях и условиях разработки, а также на важности выходных данных для дальнейшего анализа и отладки. - User
подробно с объяснениями опиши опцию --dir-outputs-in-nodes Включить поддержку dir outputs в узлах
- Assistant
Опция
--dir-outputs-in-nodesв системе сборки обеспечивает поддержку директорий в качестве выходных данных узлов сборки. Это означает, что при включении этой опции система сборки может обрабатывать целые директории как результат выполнения задачи сборки, а не только отдельные файлы.Как это работает?
В обычном режиме работы системы сборки каждый узел (или задача сборки) генерирует один или несколько файлов в качестве выходных данных. Такой подход хорошо подходит для большинства задач, но иногда требуется, чтобы результатом работы узла была целая директория со множеством файлов и поддиректорий. Примером может служить сборка документации, генерация ресурсов для веб-приложений или компиляция ассетов для игр, где результатом работы является набор файлов и структура директорий.
Опция
--dir-outputs-in-nodesразрешает создание таких узлов, указывая системе сборки, что она должна ожидать и корректно обрабатывать директории как выходные данные узлов.Преимущества использования
--dir-outputs-in-nodes- Улучшенная поддержка для комплексных задач сборки: Эта опция позволяет более эффективно справляться с задачами, где результатом работы является не один файл, а целая иерархия директорий и файлов.
- Упрощение конфигурации сборки: Вместо необходимости описывать каждый файл в выходной директории как отдельный узел или ресурс, разработчики могут работать с директорией как с одним логическим блоком.
- Оптимизация работы системы сборки: Использование директорий как единичных выходных единиц упрощает отслеживание изменений и сокращает время на анализ зависимостей и определение необходимости пересборки.
Пример использования
Предположим, вы работаете над веб-проектом, и ваша задача состоит в генерации оптимизированных изображений для сайта. Исходные файлы изображений находятся в одной директории, и вы хотите получить оптимизированные версии в другой директории, сохраняя исходную структуру папок.
ya make --dir-outputs-in-nodes /path/to/source/images/directory /path/to/destination/optimized/images/directoryВ этом случае система сборки обработает генерацию оптимизированных изображений, рассматривая всю директорию
/path/to/destination/optimized/images/directoryкак выходной результат работы узла, а не каждый файл по отдельности.Важные замечания
Использование этой опции требует внимательного планирования структуры сборки, поскольку она изменяет подход к определению выходных данных сборки. Необходимо убедиться, что все связанные задачи и узлы корректно настроены на работу с директориями как с выходными единицами, а также что инструменты и скрипты, обрабатывающие результаты сборки, правильно обрабатывают случай, когда выходными данными являются директории.
Использование
--dir-outputs-in-nodesобеспечивает большую гибкость в работе системы сборки и позволяет адаптировать процесс сборки под конкретные задачи и требования проекта, но требует тщательной настройки и проверки конфигурации. - User
подробно с объяснениями опиши опцию --keep-full-test-logs Не урезать логи при distbuild
- Assistant
Опция
--keep-full-test-logsв системе сборки – это специализированная директива, используемая в контексте распределённой сборки (distbuild), главная функция которой заключается в сохранении полных логов исполнения тестов, вместо их обрезки или урезания.Контекст использования
В распределённых системах сборки, где процесс сборки и тестирования проекта распределяется между множеством серверов или агентов, для ускорения обработки и минимизации времени сборки, часто применяются различные оптимизации. Одной из таких оптимизаций является урезание логов тестов, которое помогает снизить объём трафика данных между узлами и центральными хранилищами логов, а также облегчает последующий анализ результатов тестирования, удаляя излишнюю информацию.
Однако, в некоторых случаях, полная информация из логов тестов необходима для детального анализа проблем, выявленных в процессе тестирования, особенно когда речь идет о сложных сбоях или ошибках, проявляющихся только в специфических условиях.
Как работает
--keep-full-test-logs?Система сборки, вызванная с опцией
--keep-full-test-logs, изменяет стандартное поведение урезания логов, указывая инфраструктуре отказаться от оптимизации удаления части данных из лог файлов. В результате этого все строки, сгенерированные процессом исполнения тестов, сохраняются в логах полностью, не подвергаясь фильтрации или скрытию частей информации.Применение
Эту опцию целесообразно использовать в ситуациях, когда требуется максимально подробное понимание действий и реакций тестируемой системы, а также для выявления и диагностики непростых, редких или малоизученных проблем, которые были обнаружены в процессе тестирования.
ya make -t --keep-full-test-logsПлюсы и минусы
Преимущества:
- Упрощается процесс выявления и исправления ошибок благодаря доступности всех деталей исполнения тестов;
- Облегчается процесс аудита и верификации результатов тестирования, так как вся история исполнения остаётся доступной для анализа.
Недостатки:
- Увеличивается объём используемого дискового пространства для хранения логов;
- Может увеличиться время передачи данных между узлами сборки и хранилищем логов из-за большего объёма передаваемой информации;
- Потребуется больше времени на прохождение через подробные логи при анализе результатов.
Заключение
Использование опции
--keep-full-test-logsв системе сборки представляет собой важный инструмент для глубокого анализа и диагностики проблем в процессе разработки ПО, особенно при работе в условиях распределённой системы сборки. Несмотря на потенциальное увеличение ресурсных затрат, получаемое преимущество в виде полной прозрачности процесса тестирования может значительно облегчить поиск и исправление сложных, редких или новых ошибок в программном коде. - User
подробно с объяснениями опиши опцию --test-node-output-limit=TEST_NODE_OUTPUT_LIMIT Указывает лимит размера файлов вывода (в байтах)
- Assistant
Опция
--test-node-output-limit=TEST_NODE_OUTPUT_LIMITв контексте системы сборки используется для установления ограничения на максимальный размер файлов вывода, которые генерируются в процессе выполнения тестов. Это позволяет контролировать объём данных, сохраняемых после работы тестов, важно для управления использованием дискового пространства, особенно в условиях ограниченных ресурсов или при работе с большим количеством тестов.Как работает
--test-node-output-limit=TEST_NODE_OUTPUT_LIMIT?При выполнении теста система сборки отслеживает размер файлов вывода (логов, дампов, временных файлов и пр.), генерируемых каждым тестовым узлом. Если объём данных превышает установленный лимит
TEST_NODE_OUTPUT_LIMIT, указанный в байтах, система может обрезать эти файлы до указанного размера или же не сохранять часть вывода, превышающую этот лимит. В результате, для каждого теста сохраняется лишь наиболее важная часть вывода, позволяя снизить потребление ресурсов хранения.Применение
Опция
--test-node-output-limit=особенно полезна в следующих сценариях:-
Ограниченное дисковое пространство: на некоторых CI серверах или локальных машинах может быть ограничено доступное дисковое пространство для хранения результатов тестирования. Установив лимит на размер вывода, можно предотвратить забивание дисковой квоты.
-
Большое количество тестов: в проектах с большим объёмом тестов объем данных может быстро увеличиться до неудобоваримых размеров. Установление лимитов помогает держать общий объём данных под контролем.
-
Сложные тесты: некоторые комбинации тестов могут выдавать чрезмерно много данных, что делает анализ результатов затруднительным. Ограничение размера вывода помогает сохранить только самую важную информацию.
Пример использования
Предположим, что вы хотите ограничить вывод каждого тестового узла размером не более 1 МБ (1048576 байт). В этом случае команда запуска сборки и тестирования будет выглядеть так:
ya make -t --test-node-output-limit=1048576Важные моменты
-
Выбор размера лимита: определяя значение
TEST_NODE_OUTPUT_LIMIT, необходимо найти баланс между желанием сэкономить место и необходимостью сохранения достаточного объёма информации для анализа и дебага тестов. Слишком маленький лимит может привести к потере важных данных, в то время как слишком большой лимит снижает эффективность опции. -
Последствия применения: хотя этот параметр помогает управлять ресурсами, важно помнить, что его использование может привести к тому, что некоторая важная информация для диагностики и исправления ошибок будет потеряна из-за обрезки вывода.
-
Гибкость: В некоторых ситуациях может оказаться целесообразным использовать различные лимиты для разных групп тестов в зависимости от их характеристик и важности получаемой информации.
Заключение
Опция
--test-node-output-limitявляется эффективным средством для оптимизации использования ресурсов при выполнении тестирования, позволяя разработчикам и инженерам по качеству сохранять контроль над объёмом генерируемых данных и предотвращая ненужное потребление дискового пространства и затраты на обработку избыточных данных. -
- User
подробно с объяснениями опиши опцию --test-keep-symlinks Не удалять символические ссылки из выходных данных теста
- Assistant
Опция
--test-keep-symlinksдля системы сборки специально разработана для управления сохранением символических ссылок, которые возникают в ходе выполнения тестов. При использовании этой опции система сборки не будет удалять символические ссылки из выходных данных теста, что может быть полезно в различных сценариях разработки и тестирования.Контекст использования
Символические ссылки (или симлинки) — это файлы, которые указывают на другие файлы или директории в файловой системе. Они могут использоваться в процессе тестирования для имитации определённых структур файловой системы, обращения к файлам без копирования реального содержимого или создания контролируемых условий тестовой среды.
По умолчанию, системы сборки и тестирования могут удалять символические ссылки после теста с целью очистки и возврата к изначальному, "чистому" состоянию тестовой среды. Однако, в некоторых случаях, сохранение симлинков может быть желательным или даже необходимым для дальнейшего анализа результатов исполнения тестов или для передачи данных между различными тестами.
Как работает
--test-keep-symlinks?При запуске тестов с этой опцией система сборки изменяет своё стандартное поведение таким образом, чтобы символические ссылки, созданные в процессе выполнения тестов, не удалялись после их завершения. Это означает, что вся структура директорий, файлы и симлинки, созданные или использованные тестами, будут сохранены в их исходном виде, давая возможность для последующего анализа или использования.
Примеры использования
-
Анализ проблем с зависимостями: если тестирование включает анализ правильности разрешения и использования зависимостей (например, библиотек или модулей), сохранение символических ссылок может помочь в диагностике проблем с путями доступа.
-
Передача состояния между тестами: в некоторых комплексных тестовых сценариях состояние из одних тестов (например, настроенная структура директорий с помощью симлинков) может быть использовано последующими тестами.
-
Отладка источников данных: при тестировании систем, которые работают с разнообразными источниками данных (например, медиа-серверы или базы данных), сохранение симлинков может облегчить отладку путей доступа к данным в тестовой среде.
Важные моменты
Использование
--test-keep-symlinksтребует дополнительной аккуратности с точки зрения управления ресурсами файловой системы и организации тестовой среды:- Сохранение симлинков может повлиять на поведение последующих тестов, особенно если они ожидают "чистую" среду.
- Необходимо учитывать, что сохранённые символические ссылки могут ссылаться на данные, которые изменились или были удалены после проведения тестов, что может привести к неверным результатам при их анализе или повторном использовании.
Заключение
Опция
--test-keep-symlinksпредоставляет разработчикам гибкий инструмент для контроля сохранения символических ссылок в тестовой среде, что может быть критически важным для определенных видов тестирования или анализа ошибок. Правильное применение этой опции позволяет улучшить понимание и отладку сложных взаимодействий внутри тестируемой системы. -
- User
подробно с объяснениями опиши опцию --python-coverage Собрать информацию о покрытии кода для Python
- Assistant
Опция
--python-coverageпризвана активировать сбор информации о покрытии кода (code coverage) для проектов, написанных на Python, в рамках процесса тестирования. Покрытие кода — это метрика, используемая для измерения степени, в которой исходный код программы исполнен при тестировании. Эта метрика позволяет разработчикам понять, какие части кода были и не были проверены тестами, выделяя области, которые потенциально могут содержать непойманные ошибки.Как работает
--python-coverage?Запуская тесты с использованием
--python-coverage, система сборки интегрируется с инструментами покрытия кода Python (например, с популярной утилитойcoverage.py), чтобы автоматически измерить и собрать данные о том, какие строки кода были выполнены в процессе исполнения тестов. По завершении тестов собранная информация о покрытии кода обычно представляется в форме детальных отчётов, которые могут содержать процент покрытия, а также указывать конкретные строки кода, которые не были исполнены.Применение
Опция
--python-coverageнаиболее ценна в контекстах, где разработчики стремятся улучшить качество кода и надежность программного обеспечения, так как позволяет:- Идентифицировать пробелы в тестовом покрытии: Помогает выявить части кода, которые не покрыты тестами, и может служить руководством для разработки дополнительных тестов.
- Оптимизировать существующие тесты: Позволяет разработчикам определить избыточные тесты, которые не увеличивают общее покрытие кода, и тем самым оптимизировать тестовую среду.
- Повысить надежность программного обеспечения: Путем сосредоточения внимания на увеличении покрытия тестами критически важных частей кода.
Пример использования
Допустим, ваш проект содержит множество Python модулей, и вы хотели бы получить общее представление о покрытии кода тестами. Для этого можно запустить следующую команду в системе сборки:
ya make -t --python-coverageПосле выполнения тестов система сборки генерирует отчет о покрытии кода, который можно анализировать для дальнейших улучшений в тестовом покрытии.
Важные моменты
- Интеграция с инструментами CI/CD: Данные о покрытии кода особенно полезны, когда они интегрированы с системами непрерывной интеграции и развертывания, так как это позволяет автоматически отслеживать изменения в покрытии на протяжении всего цикла разработки.
- Выбор инструмента покрытия: Важно убедиться, что используемый инструмент покрытия кода хорошо интегрируется с вашей средой разработки и системой сборки, а также поддерживает необходимые вам форматы отчетов.
- Тщательный анализ отчетов: Хотя высокий процент покрытия кода тестами является желательной целью, он не гарантирует отсутствие ошибок. Важно также сосредотачиваться на качестве тестов и на том, насколько хорошо они проверяют различные варианты использования программного обеспечения.
Итак, опция
--python-coverageявляется важным инструментом для контроля качества кода и улучшения надежности ПО за счет точного измерения тестового покрытия и позволяет разработчикам стремиться к постоянному улучшению в этих областях. - User
подробно с объяснениями опиши опцию --ts-coverage Собрать информацию о покрытии кода для TypeScript
- Assistant
Опция
--ts-coverageв системе сборки служит для сбора информации о покрытии кода специально для проектов на TypeScript. Покрытие кода (code coverage) — критически важная метрика для оценки качества тестирования программного обеспечения, которая показывает, какая часть кода была исполнена в процессе запуска тестов. Цель этой метрики — предоставить четкое понимание того, какие участки кода были проверены тестами, а какие остались без внимания. Это позволяет разработчикам улучшить качество тестов и уверенно вносить изменения в код.Сбор данных о покрытии кода для TypeScript
TypeScript является надмножеством JavaScript, добавляющим строгую типизацию и другие функции для улучшения масштабируемости и поддержки кода. По своей сути, после компиляции TypeScript-код преобразуется в JavaScript, который уже и выполняется в целевой среде (например, в браузере или на сервере Node.js).
Опция
--ts-coverageактивирует инструменты, которые анализируют, какие части исходного кода на TypeScript были исполнены во время тестирования, и генерируют отчеты о покрытии. Для этого могут использоваться специализированные инструменты покрытия, адаптированные или совместимые с TypeScript, такие как Istanbul (nyc), которые могут работать с исходным кодом на TypeScript напрямую или через его карты кода (source maps).Преимущества использования
--ts-coverage- Улучшенное тестирование: Предоставление данных о покрытии кода напрямую для TypeScript позволяет разработчикам напрямую видеть, какие именно участки типизированного кода охвачены тестами, что особенно важно для выявления неочевидных проблем, связанных с типами.
- Оптимизация тестов: Информация о покрытии помогает определить участки кода, которые не покрыты тестами, что позволяет оптимизировать дальнейшую разработку тестов и сосредоточить усилия на ключевых областях.
- Интеграция с циклом CI/CD: Данные о покрытии могут использоваться в системах непрерывной интеграции и доставки для автоматизации контроля качества кода и обеспечения стандартов качества.
Как использовать
--ts-coverageВо время запуска процесса тестирования проекта через систему сборки добавление опции
--ts-coverageактивирует сбор данных:ya make -t --ts-coverageЗависимо от конкретной настройки среды и используемых инструментов, могут потребоваться дополнительные шаги для настройки или конфигурации инструментов покрытия кода, чтобы они работали с TypeScript эффективно.
Важные моменты и ограничения
- Инструменты покрытия: Проверьте совместимость используемых инструментов для анализа покрытия с TypeScript, так как некоторые инструменты могут требовать дополнительной настройки или использования плагинов.
- Компиляция TypeScript: Поскольку TypeScript компилируется в JavaScript, важно убедиться, что механизм покрытия кода корректно учитывает карты кода (source maps) для правильного отображения информации о покрытии на исходные файлы TypeScript.
- Обработка результатов: Понимание и анализ отчетов о покрытии кода требует внимательного рассмотрения, особенно в свете специфики TypeScript, таких как его система типов и компиляция в JavaScript.
Итак, использование опции
--ts-coverageявляется ценным помощником в процессе разработки и тестирования TypeScript-проектов, позволяя разработчикам детально оценить качество и охват тестирования их кода. - User
подробно с объяснениями опиши опцию --go-coverage Собрать информацию о покрытии кода для Go
- Assistant
Опция
--go-coverageв системе сборки применяется для сбора информации о покрытии кода в проектах, написанных на языке программирования Go. Это критически важная функциональность для оценки эффективности существующего набора тестов и идентификации участков кода, которые не покрываются тестами, что позволяет повысить качество и надёжность программного обеспечения.Как работает
--go-coverage?При использовании опции
--go-coverageв команде сборки и тестирования, система сборки активирует инструментарий Go для измерения покрытия кода тестами. В Go средство покрытия встроено непосредственно в стандартный пакетgo test, который не только выполняет тесты, но и может собирать данные о покрытии кода при добавлении флага-cover.Процесс сбора покрытия работает за счет внедрения специальных аннотаций в исходный код перед его выполнением, что позволяет инструменту отслеживать, какие строки кода были выполнены во время тестирования. После завершения выполнения тестов данные покрытия собираются и обычно представляются в виде отчета.
Зачем использовать эту опцию?
- Улучшение тестового покрытия: С помощью отчётов о покрытии кода можно определить, какие именно участки кода были или не были исполнены во время тестов, что дает возможность разработчикам создать дополнительные тесты для неохваченных областей.
- Повышение качества кода: Информация о покрытии кода помогает обеспечить, что все важные части программы тщательно протестированы, уменьшая количество ошибок и повышая общую надёжность программного продукта.
- Оптимизация процесса разработки: Данные о покрытии могут также помочь в определении избыточного или неиспользуемого кода, который можно убрать, делая проект более лёгким и гибким.
Пример использования
Если вы работаете над проектом на Go и хотите получить отчёт о покрытии кода тестами, вы могли бы использовать следующую команду:
ya make -t --go-coverageЭта команда запустит доступные тесты для вашего проекта и соберёт данные о покрытии кода. Результаты могут быть представлены в различных формах, например, в виде HTML-отчета, показывающего покрытие каждого файла кода, или как сырые данные, которые можно дополнительно анализировать при помощи других инструментов.
Важные моменты
- Комплексность данных: Важно понимать, что высокий процент покрытия кода не гарантирует его полной безошибочности. Важно также обращать внимание на качество тестов и то, насколько они эффективно проверяют различные аспекты логики программы.
- Интеграция с CI/CD: Интеграция сбора данных о покрытии кода в процесс непрерывной интеграции и доставки может автоматизировать отслеживание изменений в покрытии кода и улучшать принятие решений о необходимости дальнейших действий.
Итак, использование опции
--go-coverageпредставляет собой ценный инструмент для любого проекта на Go, стремящегося к высокому качеству, стабильности и надёжности программного обеспечения. - User
подробно с объяснениями опиши опцию --java-coverage Собрать информацию о покрытии кода для Java
- Assistant
Опция
--java-coverageв контексте системы сборки предназначена для активации сбора данных о покрытии кода в проектах на языке программирования Java. Сбор информации о покрытии кода является важным элементом в процессе разработки и тестирования программного обеспечения, поскольку он позволяет оценить, какую часть кода затрагивают выполненные тесты, выявить части кода, не покрытые тестами, и определить потенциальные уязвимые места в логике приложения.Как работает
--java-coverage?Использование опции
--java-coverageпри запуске сборки проекта или его тестов задействует инструменты для сбора данных о покрытии кода в Java, такие как JaCoCo (Java Code Coverage), Emma или Cobertura. Эти инструменты анализируют, какие строки и ветви кода исполняются при запуске автоматизированных тестов (например, JUnit тестов), и генерируют отчеты о покрытии, которые помогают разработчикам оптимизировать набор тестов и обеспечивают более высокое качество кода.Преимущества использования
--java-coverage- Определение покрытия тестами: Информация о том, какие конкретно участки кода были задействованы при выполнении тестов, помогает разработчикам локализовать участки, требующие дополнительного внимания, и написания новых тестов.
- Оптимизация процесса разработки тестов: Понимание покрытия кода позволяет избежать написания избыточных тестов на уже хорошо покрытые тестами части приложения, а также сосредоточиться на тех аспектах, которые требуют улучшения.
- Улучшение качества и надежности программного обеспечения: Повышение уровня покрытия тестами напрямую связано с выявлением и предотвращением потенциальных ошибок и проблем в программе еще на этапе разработки.
Пример использования
Допустим, вы разрабатываете Java-проект и хотите убедиться в том, что ваши тесты покрывают достаточный объем кода. В этом случае вы бы использовали команду сборки с опцией
--java-coverage, чтобы активировать сбор данных о покрытии:ya make -t --java-coverageПосле выполнения тестов система сборки сгенерирует отчет о покрытии кода, который вы можете просмотреть, чтобы оценить эффективность текущих тестов и определить области кода без достаточного покрытия.
Важные моменты
- Выбор инструмента покрытия: В зависимости от того, какой инструмент используется для сбора данных о покрытии (JaCoCo, Emma, Cobertura), могут отличаться методы генерации и форматы отчетов о покрытии. Стоит выбрать тот инструмент, который наилучшим образом соответствует потребностям проекта и интеграции с системами CI/CD.
- Интеграция с CI/CD: Многие системы непрерывной интеграции поддерживают автоматическое извлечение и анализ отчетов о покрытии, что позволяет отслеживать изменения в покрытии со временем и автоматически оценивать влияние нового кода и тестов на общее качество проекта.
- Комплексный подход к качеству: Необходимо помнить, что высокий процент покрытия кода тестами сам по себе не гарантирует отсутствие ошибок. Важно также обращать внимание на качество самих тестов и соответствие тестовых случаев требованиям к функциональности программного продукта.
Таким образом, опция
--java-coverageпредставляет собой важный инструмент для обеспечения высокого качества тестирования и разработки Java-проектов, позволяя разработчикам получить полную картину охвата кода тестами и выявить потенциальные "слепые зоны" в тестовом покрытии. - User
подробно с объяснениями опиши опцию --clang-coverage Покрытие кода на основе исходных кодов Clang (автоматически увеличивает таймаут тестов в 1.5 раза)
- Assistant
Опция
--clang-coverageв системах сборки исходного кода используется для активации сбора информации о покрытии кода (code coverage) для проектов, написанных на языках C и C++, с использованием компилятора Clang. Функция покрытия кода — это критически важная практика в процессе разработки программного обеспечения, позволяющая измерить, какая часть кода была выполнена в процессе тестирования, выявляя неохваченные участки кода, которые потенциально могут содержать ошибки или уязвимости.Как работает
--clang-coverage?Эта опция включает инструменты Clang для сбора данных о покрытии исходного кода при выполнении тестов. Clang поддерживает различные механизмы для измерения покрытия кода, в том числе Source-based Code Coverage, который обеспечивает подробный и точный анализ покрытия с минимальным влиянием на производительность исполняемых тестов. Этот подход базируется на использовании профилировщика LLVM, который собирает информацию о исполнении кода во время выполнения программы, записывая данные о количестве проходов каждой строки кода или исполнении каждой ветви условий.
Преимущества использования
--clang-coverage- Подробное покрытие на уровне исходного кода: Позволяет получить высокую точность данных о покрытии, включая информацию о ветвлениях и использовании отдельных строк кода.
- Глубокий анализ: Способствует выявлению участков кода, которые не были задействованы в ходе тестирования, что указывает на потребность в дополнительных тестах.
- Оптимизация процесса разработки: Использование данных о покрытии помогает сфокусироваться на улучшении качества кода и тестов, избегая лишней работы по написанию избыточных тестов для уже хорошо покрытых участков.
Повышение таймаута тестов
Собрать информацию о покрытии кода интенсивнее в плане использования ресурсов, по сравнению с обычным процессом тестирования. В связи с этим опция
--clang-coverageавтоматически увеличивает таймаут тестов в 1.5 раза, чтобы обеспечить достаточно времени для сбора всех необходимых данных о покрытии без риска прерывания теста из-за превышения лимита времени.Пример использования
Для активации сбора информации о покрытии кода в проекте при помощи Clang, используйте команду:
ya make -t --clang-coverageВажные моменты
- Выбор компилятора: Убедитесь, что ваш проект компилируется с использованием компилятора Clang, так как опция
--clang-coverageрассчитана на инструментарий именно этого компилятора. - Анализ результатов: После выполнения тестов с включенной опцией
--clang-coverageважно правильно интерпретировать полученные результаты, чтобы на их основе принимать решения о необходимости разработки новых тестов или улучшении существующих. - Интеграция с CI/CD: Включение сбора данных о покрытии кода в процесс непрерывной интеграции и развертывания может значительно улучшить качество и надежность программного обеспечения, но требует настройки сбора, хранения и анализа данных о покрытии в этих системах.
Использование опции
--clang-coverageпредоставляет разработчикам мощный инструмент для контроля и улучшения качества программного кода на C/C++ в проектах, где используется компилятор Clang, позволяя более эффективно управлять процессом разработки и тестирования. - User
подробно с объяснениями опиши опцию --coverage-report Создать HTML отчет о покрытии кода (используйте с --output)
- Assistant
Опция
--coverage-reportв системах сборки используется для создания подробного отчёта о покрытии кода в формате HTML, который является визуальным и удобным средством для анализа покрытия кода тестами. Эта опция должна использоваться в сочетании с опцией--output, которая указывает место для сохранения сгенерированного отчёта.Как работает
--coverage-report?Когда вы запускаете процесс тестирования с активированным сбором информации о покрытии кода, опция
--coverage-reportзапускает дополнительный процесс по обработке собранных данных о покрытии и генерации на их основе отчёта в HTML формате. Этот отчет содержит детализированную информацию о проценте покрытия кода тестами, выделяя те участки кода, которые были исполнены во время тестирования, и те, которые остались без внимания.Преимущества использования
--coverage-report- Визуализация: HTML отчет обладает высокой читаемостью и удобен для анализа. Он может предоставлять графики, цветовые индикаторы и навигацию по коду проекта для более глубокого понимания покрытия.
- Удобство анализа: С помощью отчета легко выявить пробелы в тестовом покрытии и распределить усилия на разработку тестов для критически важных участков кода.
- Документация состояния покрытия: Отчет можно использовать как документацию текущего состояния покрытия кода в проекте, что полезно как для внутренних потребностей команды, так и для внешних аудитов.
Использование
--coverage-reportс--outputДля генерации HTML отчета о покрытии кода следует использовать опцию
--coverage-reportвместе с--output, указывая директорию для сохранения отчета. Например:ya make all --coverage-report --output /path/to/coverage/reportЭта команда запустит процесс сборки и тестирования с активацией сбора данных о покрытии кода и последующей генерацией HTML отчета, который будет сохранен в указанной директории.
Важные моменты
- Настройка среды: Убедитесь, что ваша среда разработки и инструменты тестирования правильно настроены для сбора данных о покрытии кода. В зависимости от языка и инструментов, может потребоваться предварительная конфигурация.
- Обработка больших проектов: Генерация отчета для крупных проектов с многочисленными тестами может быть ресурсозатратной и занимать значительное время.
- Версионирование отчетов: Рассмотрите возможность версионирования отчетов о покрытии кода, чтобы отслеживать прогресс покрытия кода тестами в динамике.
Использование опции
--coverage-reportпредоставляет ценные инсайты относительно качества и полноты тестирования проекта, позволяя разработчикам и командам QA сфокусироваться на улучшении покрытия и, как следствие, повышении качества программного продукта. - User
подробно с объяснениями опиши опцию --coverage-prefix-filter=COVERAGE_PREFIX_FILTER Анализировать только пути, соответствующие шаблону
- Assistant
Опция
--coverage-prefix-filter=COVERAGE_PREFIX_FILTERпредназначена для фильтрации данных о покрытии кода по определенному шаблону пути в проектах, где включен сбор информации о покрытии кода. Эта функциональность важна для сосредоточения анализа покрытия на специфических участках проекта и исключения из отчетов о покрытии кода тех частей программы, анализ которых не представляет интереса или является нецелесообразным.Как работает
--coverage-prefix-filter=COVERAGE_PREFIX_FILTER?Когда активирована опция сбора данных о покрытии кода, процесс тестирования может собирать информацию о всех исполняемых строках кода в проекте. Это может привести к созданию очень обширных и детализированных отчетов, в которых информация о ключевых модулях или компонентах смешивается с данными о вспомогательных библиотеках, тестовых данных или автоматически сгенерированном коде. Чтобы избежать этого, опция
--coverage-prefix-filterпозволяет указать шаблон или префикс пути, ограничивая тем самым анализ покрытия только интересующими разработчиков директориями и файлами.COVERAGE_PREFIX_FILTER— это шаблон пути (или несколько шаблонов, если их несколько), который указывает, какие файлы или директории следует анализировать на предмет покрытия кода тестами. Пути, не соответствующие указанному шаблону, будут исключены из анализа и отчета о покрытии.Пример использования
Предположим, проект содержит модули
src/с основным кодом приложения иlib/с внешними зависимостями. Если требуется сосредоточить анализ покрытия кода только на модулеsrc/, можно использовать следующую команду:ya make -t --coverage-prefix-filter=src/Эта команда скажет системе сборки собрать данные о покрытии кода, ограничив анализ путями, которые начинаются с
src/, исключая из отчета код из директорииlib/и других несоответствующих фильтру путей.Важные моменты
- Точность фильтрации: Чем точнее задан фильтр, тем более релевантной будет информация в отчете о покрытии кода. Важно правильно указать шаблон, чтобы не исключить важные части кода из анализа.
- Использование нескольких фильтров: В зависимости от системы сборки, может поддерживаться использование нескольких фильтров одновременно для более гранулярного управления анализом покрытия.
- Производительность: Фильтрация может сократить время анализа покрытия и размер генерируемых отчетов, что упрощает их последующий анализ и сокращает время, необходимое для обработки данных о покрытии кода.
Использование опции
--coverage-prefix-filterпредоставляет гибкие возможности для управления процессом сбора и анализа данных о покрытии кода, позволяя разработчикам сосредоточиться на наиболее важных для проекта участках кода, что способствует повышению их качества и надежности. - User
подробно с объяснениями опиши опцию --coverage-exclude-regexp=COVERAGE_EXCLUDE_REGEXP Исключить из отчета покрытия кода пути, соответствующие шаблону
- Assistant
Опция
--coverage-exclude-regexp=COVERAGE_EXCLUDE_REGEXPявляется мощным инструментом для управления сбором данных о покрытии кода в процессе тестирования программного обеспечения. Эта опция позволяет явно указать регулярное выражение (regexp), соответствующие пути к файлам или каталогам в проекте, которые следует исключить из отчета о покрытии кода. Таким образом, разработчики могут фильтровать и исключать специфические участки кода, которые по тем или иным причинам не должны учитываться при оценке покрытия тестами.Как работает
--coverage-exclude-regexp=COVERAGE_EXCLUDE_REGEXP?При активации этой опции и выполнении тестов с параллельным сбором данных о покрытии кода, система сборки применит заданное регулярное выражение для фильтрации путей файлов и директорий. Любые файлы или директории, пути которых совпадают с указанным регулярным выражением, будут исключены из финального отчета о покрытии кода. Это позволяет исключить из анализа вспомогательные библиотеки, тестовый код, сгенерированный код и прочие части проекта, которые не представляют интереса в контексте текущей задачи анализа.
Преимущества использования
--coverage-exclude-regexp- Фокус на важных частях кода: Позволяет сосредоточить анализ покрытия на значимых и критических участках кода, исключая шум от вспомогательных и предопределенных частей проекта.
- Улучшение производительности: Исключение нерелевантных файлов и папок может сократить время выполнения анализа покрытия и размер генерируемого отчета, делая процесс более быстрым и эффективным.
- Удобство анализа отчетов: Сокращение объема лишней информации в отчетах о покрытии упрощает их анализ и интерпретацию, позволяя быстрее принимать решения по улучшению качества кода.
Пример использования
Предположим, что в проекте есть каталоги с автоматически сгенерированным кодом или с внешними библиотеками, которые не нужно учитывать при оценке покрытия кода. Для исключения этих каталогов можно использовать следующую команду с определенным регулярным выражением:
ya make -t --coverage-exclude-regexp='/externals/|/generated/'В этом примере
'/externals/|/generated/'является регулярным выражением, которое исключает все пути, содержащие/externals/или/generated/, тем самым убирая код из этих директорий из отчета о покрытии.Важные моменты
- Точность регулярных выражений: Необходимо точно формулировать регулярные выражения, чтобы избежать случайного исключения важного кода. Рекомендуется тестировать регулярные выражения на небольшом наборе данных перед применением их в большом проекте.
- Перекрестная проверка: После применения фильтров стоит перекрестно проверить, что все необходимые участки кода попали в отчет о покрытии, и что исключения были применены корректно.
Использование опции
--coverage-exclude-regexpпредставляет собой ценный инструмент в арсенале инструментов разработчика для точного контроля и анализа покрытия кода тестами, позволяя повысить качество программного продукта и эффективность процесса разработки. - User
подробно с объяснениями опиши опцию --sancov Собрать информацию о покрытии кода санитайзером (автоматически увеличивает таймаут тестов в 1.5 раза)
- Assistant
Опция
--sancovпредставляет собой параметр системы сборки, который активирует сбор данных о покрытии кода при помощи инструментов санитайзеров (Sanitizers), таких как AddressSanitizer, ThreadSanitizer, MemorySanitizer и других. Санитайзеры — это мощные инструменты, обеспечивающие динамический анализ кода для выявления различных видов ошибок, таких как обращения за границы массивов, использование неинициализированной памяти и состязания данных. В контексте опции--sancov, основное внимание уделяется построению отчетов о покрытии кода на основе анализа, проведенного данными инструментами.Как работает
--sancov?При использовании
--sancovв команде сборки, система настраивает среду выполнения и компиляцию тестовых и целевых модулей таким образом, чтобы включить механизмы отслеживания исполнения кода санитайзерами. Эти механизмы генерируют специальные данные о покрытии кода в ходе выполнения тестов, позволяя точно определить, какие части кода были задействованы. По завершении тестов система сборки обрабатывает сгенерированные данные и формирует отчет о покрытии кода.Преимущества использования
--sancov- Точное покрытие кода: Предоставляет подробные сведения о том, какие участки кода были исполнены во время тестирования, что позволяет идентифицировать не охваченные тестами части программы.
- Улучшение качества кода: Использование данных о покрытии помогает нацелить усилия разработчиков на улучшение тестов и расширение охвата критически важных участков кода.
- Оптимизация ресурсов: Помогает определить избыточные или неэффективные тесты, сокращая время, затрачиваемое на тестирование, и ускоряя цикл разработки.
- Автоматическое увеличение таймаута тестов: Учитывая дополнительную нагрузку на производительность, вызванную активацией санитайзеров, автоматическое увеличение времени ожидания выполнения тестов на 1.5 раза помогает избежать ложных сбоев из-за превышения времени исполнения.
Использование
--sancovс--outputДля сохранения отчетов о покрытии кода рекомендуется использовать
--sancovсовместно с опцией--output, указывая путь для сохранения результата:ya make -t --sancov --output /path/to/coverage/reportЭта команда запустит процесс тестирования с активацией санитайзеров для сбора данных о покрытии и сохранит полученный отчет в указанной директории.
Важные моменты
- Поддержка санитайзерами: Не все санитайзеры могут поддерживать сбор данных о покрытии кода. Убедитесь, что используемые вами санитайзеры поддерживают эту функциональность.
- Производительность при тестировании: Активация санитайзеров может существенно снизить производительность выполнения программ, поэтому следует учитывать потенциальное увеличение времени тестирования.
- Анализ отчетов о покрытии: Интерпретация данных о покрытии требует внимательности, так как высокий процент покрытия не всегда означает высокое качество тестов.
Использование опции
--sancovявляется ценным инструментом для улучшения тестового покрытия и качества кода на C/C++ при использовании компилятора Clang, позволяя сосредотачиваться на оптимизации тестового набора и повышении надежности разрабатываемого программного обеспечения.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.