Написание, запуск и тестирование кода¶
Чтобы исправить ошибку или реализовать новую функцию, вам потребуется написать новый код.
Чтобы приступить к работе над кодом, убедитесь, что у вас настроена среда разработки и вы работаете над веткой.
У нас есть руководство по стилю написания кода, в котором изложены рекомендации по написанию кода для BeeWare.
Разработка на основе тестирования¶
Хороший способ убедиться, что ваш код будет работать так, как вы ожидаете, — сначала написать тестовый случай для его проверки. Изначально этот тестовый случай должен завершаться сбоем, поскольку тестируемый код ещё не реализован. Затем вы можете внести в код необходимые изменения, чтобы тест прошел успешно, и быть уверенным, что написанный вами код решает именно ту задачу, которую вы от него ожидали.
Запустите свой код¶
После написания кода необходимо убедиться, что он работает. Вам нужно будет вручную запустить код, чтобы проверить, работает ли он так, как вы ожидаете. Если вы ещё этого не сделали, рекомендуется написать тестовый случай для внесенных изменений; как упоминалось выше, этот тест должен завершиться с ошибкой, если код закомментирован или отсутствует.
Вы добавите свой тестовый случай в набор тестов, чтобы его можно было запустить вместе с другими тестами. Следующим шагом будет запуск набора тестов.
Запуск тестов и покрытия¶
BeeWare использует tox для управления
процессом тестирования и pytest для
своего собственного набора тестов.
Команда tox по умолчанию включает в себя выполнение:
- хуки pre-commit
towncrierПроверка примечаний к выпуску-
проверка документации на наличие синтаксических ошибок
-
набор тестов для доступных версий Python
-
отчеты по покрытию кода
По сути, именно это выполняет CI при отправке пул-реквеста.
Чтобы запустить полный набор тестов, выполните команду:
(.venv) $ tox
(.venv) $ tox
(.venv) C:\...>tox
Выполнение полного набора тестов может занять некоторое время. Вы можете
значительно ускорить этот процесс, запустив tox параллельно, то есть запустив
tox p (или tox run-parallel). При параллельном запуске набора тестов вы
будете получать меньше информации о ходе выполнения тестов, но по-прежнему
получите сводку об обнаруженных проблемах по окончании тестирования. Вы должны
увидеть вывод, подтверждающий, что тесты были запущены. Вы можете увидеть
SKIPPED тестов, но ни в коем случае не должны получать результаты тестов
FAIL или ERROR. Мы запускаем полный набор тестов перед слиянием каждого
патча. Если в ходе этого процесса обнаруживаются какие-либо проблемы, мы не
сливаем патч. Если вы обнаружили ошибку или сбой теста, либо в вашей тестовой
среде есть что-то необычное, либо вы нашли крайний случай, с которым мы раньше
не сталкивались — в любом случае, сообщите нам об этом!
Помимо успешного прохождения тестов, это должно обеспечить 100% покрытие тестами.
Выполнение вариантов тестов¶
Запустить тесты для нескольких версий Python¶
По умолчанию многие команды tox будут пытаться запустить набор тестов
несколько раз — по одному разу для каждой версии Python, поддерживаемой BeeWare. Однако для этого каждая из версий Python должна быть установлена
на вашем компьютере и доступна для процесса [обнаружения]tox Python в
(https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). Как
правило, если версия Python доступна через PATH, то tox должна быть в
состоянии найти и использовать её.
Запустить только набор тестов¶
Если вы быстро тестируете новую функцию, вам не нужно запускать полный набор тестов; можно запустить только модульные тесты. Для этого выполните команду:
(.venv) $ tox -e py
(.venv) $ tox -e py
(.venv) C:\...>tox -e py
Запустить поднабор тестов¶
По умолчанию команда tox запускает все тесты из набора модульных тестов. При
разработке нового теста может оказаться полезным запустить только этот один
тест. Для этого в качестве аргумента команды pytest можно передать [любой
спецификатор
(https://docs.pytest.org/en/latest/how-to/usage.html#specifying-which-tests-to-run)]tox.
Эти пути к тестам являются относительными по отношению к каталогу briefcase.
Например, чтобы запустить только тесты из одного файла, выполните команду:
(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py
(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py
(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py
При запуске части набора тестов вы по-прежнему получите отчет о покрытии, однако в результатах будут указаны только те строки кода, которые были выполнены в рамках конкретных запущенных вами тестов.
Запустить набор тестов для конкретной версии Python¶
По умолчанию tox -e py будет запускаться с помощью того интерпретатора,
который на вашем компьютере распознается как python. Если у вас установлено
несколько версий Python и вы хотите протестировать одну из них, вы можете
указать конкретную версию Python для использования. Например, чтобы запустить
набор тестов на Python 3.10, выполните команду:
(.venv) $ tox -e py310
(.venv) $ tox -e py310
(.venv) C:\...>tox -e py310
Подмножество тестов можно запустить, добавив символы -- и
спецификацию теста в командную строку.
Запустить набор тестов без отслеживания покрытия (быстро)¶
По умолчанию команда tox запускает набор тестов pytest в однопоточном режиме.
Вы можете ускорить выполнение набора тестов, запустив его в параллельном режиме.
В этом режиме файлы покрытия не создаются из-за сложностей с отслеживанием
покрытия в запущенных процессах. Чтобы запустить отдельную версию Python в
«быстром» режиме, выполните команду:
(.venv) $ tox -e py-fast
(.venv) $ tox -e py-fast
(.venv) C:\...>tox -e py-fast
Подмножество тестов можно запустить, добавив -- и спецификацию
теста в командную строку; конкретную версию Python можно
использовать, указав версию в целевом объекте теста (например, py310-fast для запуска fast на Python 3.10).
Покрытие кода¶
BeeWare обеспечивает 100% покрытие ветвей в своей кодовой базе. При добавлении или изменении кода в проекте необходимо добавлять тестовый код, чтобы обеспечить покрытие всех внесенных изменений.
Однако BeeWare предназначен для работы на нескольких платформах, а
также с несколькими версиями Python, поэтому полное покрытие невозможно
проверить на одной платформе и в одной версии Python. Чтобы учесть это, в
разделе tool.coverage.coverage_conditional_plugin.rules файла pyproject.toml
определено несколько условно-логических правил покрытия (например,
no-cover-if-is-windows можно использовать для пометки блока кода, который не
будет выполняться при запуске набора тестов в Windows). Эти правила используются
для выявления участков кода, которые покрываются только на определенных
платформах или в определенных версиях Python.
Стоит отметить, что при составлении отчетов о покрытии в разных версиях Python могут возникать некоторые неточности. Например, если файлы покрытия созданы с использованием одной версии Python, а отчет формируется на другой, в отчете могут появиться ложные срабатывания, связанные с пропущенными ветвями. В связи с этим при составлении отчетов о покрытии всегда следует использовать самую старую версию Python, на которой были созданы файлы покрытия.
Понимание результатов покрытия¶
В конце вывода результатов теста покрытия должен появиться отчет с данными о покрытии, которые были собраны:
Название Отчеты Отделение Miss Доля Покрытие Отсутствующие
---------------------------------------------------
ИТОГО 7540 0 1040 0 100,0%
Это говорит о том, что набор тестов прошел все возможные ветвления в коде. Это не является стопроцентной гарантией отсутствия ошибок, но означает, что мы проверяем каждую строку кода в кодовой базе.
Если вы вносите изменения в исходный код, возможно, что в отчете о покрытии
появятся пробелы. В таком случае отчет о покрытии покажет, какие строки не
выполняются. Например, предположим, что мы внесли изменение в
some/interesting_file.py, добавив новую логику. Отчет о покрытии может
выглядеть примерно так:
Имя Stmts Miss Branch BrPart Cover Missing
-------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98,1% 170, 302-307, 320->335
-------------------------------------------------------------------------------
ИТОГО 7540 1 1726 0 99,9%
Это означает, что строка 170, строки 302–307, а также ветвление, переходящее со строки 320 на строку 335, не выполняются набором тестов. Чтобы восстановить покрытие, вам необходимо добавить новые тесты (или изменить существующий тест).
Отчет о поддержке платформы хоста и версии Python¶
Вы можете сгенерировать отчёт о покрытии для вашей платформы и версии Python. Например, чтобы запустить набор тестов и сгенерировать отчёт о покрытии для Python 3.10, выполните команду:
(.venv) $ tox -m test310
(.venv) $ tox -m test310
(.venv) C:\...>tox -m test310
Отчет об охвате для хост-платформы¶
Если для tox доступны все поддерживаемые версии Python, то для получения
отчета о покрытии для хост-платформы можно выполнить следующую команду:
(.venv) $ tox p -m test-platform
(.venv) $ tox p -m test-platform
(.venv) C:\...>tox p -m test-platform
Отчеты об охвате в формате HTML¶
Отчет об охвате HTML можно сгенерировать, добавив -html к любому из имен сред
охвата tox, например:
(.venv) $ tox -e coverage-platform-html
(.venv) $ tox -e coverage-platform-html
(.venv) C:\...>tox -e coverage-platform-html
Дело не только в написании тестов!¶
Хотя мы и следим за тем, чтобы тестировать весь наш код, задача заключается не только в поддержании этого уровня тестирования. Часть задачи состоит в том, чтобы проводить аудит кода по ходу работы. Можно написать исчерпывающий набор тестов для конкретного спасательного жилета… но такой спасательный жилет всё равно будет бесполезен для тех целей, для которых он был предназначен!
При разработке тестов вам следует также проверять, насколько внутренне
согласован основной модуль. Если вы заметили имена методов, которые не
являются внутренне согласованными (например, что-то называется on_select в
одном модуле, но on_selected в другом), или если данные обрабатываются
несогласованно, отметьте это и сообщите нам, создав заявку. Или, если вы
уверены, что знаете, что нужно сделать, создайте пул-реквест, исправляющий
обнаруженную вами проблему.
Как только все будет работать, вы можете отправить запрос на вытягивание со своими изменениями.