Использование и вызов¶
Вызов pytest
с помощью python -m pytest
¶
Тестирование можно запустить из командной строки интерпретатора Python
, используя команду:
python -m pytest [...]
В отличие от запуска напрямую командой pytest [...]
, запуск через Python
добавит текущий каталог в sys.path
.
Статусы завершения¶
Выполнение pytest
может генерировать один из следующих статусов завершения:
- Exit code 0
Все тесты были собраны и успешно прошли
- Exit code 1
Тесты были собраны и запущены, но некоторые из них упали
- Exit code 2
Выполнение тестов было прервано пользователем
- Exit code 3
Во время выполнения тестов произошла внутренняя ошибка
- Exit code 4
Ошибка запуска
pytest
из командной строки- Exit code 5
Не удалось собрать тесты (тесты не найдены)
Коллекция статусов представлена перечислением _pytest.config.ExitCode. Статусы завершения являются частью публичного API, их можно импортировать и использовать непосредственно:
from pytest import ExitCode
Примечание
Для настройки кода завершения сценария, особенно когда тесты не удалось собрать, можно использовать плагин pytest-custom_exit_code.
Получение помощи по версии, параметрам, переменным окружения¶
pytest --version # показывает версию и место, откуда импортирован ``pytest``
pytest --fixtures # показывает доступные встроенные функции
pytest -h | --help # показывает помощь по командной строке и параметры конфигруационного файла
Остановка после первых N падений¶
Чтобы остановить процесс тестирования после первых N падений, используются параметры:
pytest -x # остановка после первого упавшего теста
pytest --maxfail=2 # остановка после первых двух упавших тестов
Выбор выполняемых тестов¶
pytest
поддерживает несколько способов выбора и запуска тестов из командной строки.
Запуск тестов модуля
pytest test_mod.py
Запуск тестов из директории
pytest testing/
Запуск тестов, удовлетворяющих ключевому выражению
pytest -k "MyClass and not method"
Эта команда запустит тесты, имена которых удовлетворяют заданному строковому выражению
(без учета регистра). Строковые выражения могут включать операторы Python
, которые
используют имена файлов, классов и функций в качестве переменных. В приведенном выше
примере будет запущен тест MyClass.test_something
, но не будет запущен тест
TestMyClass.test_method_simple
.
Запуск тестов по идентификаторам узлов
Каждому собранному тесту присваивается уникальный идентификатор nodeid
,
который состоит из имени файла модуля, за которым следуют спецификаторы,
такие как имена классов, имена функций и параметры из параметризации, разделенные символами ::
:
Чтобы запустить конкретный тест из модуля, выполните:
pytest test_mod.py::test_func
Еще один пример спецификации тестового метода в командной строке:
pytest test_mod.py::TestClass::test_method
Запуск маркированных тестов
pytest -m slow
Будут запущены тесты, помеченные декоратором @pytest.mark.slow
.
Подробнее см. marks.
Запуск тестов из пакетов
pytest --pyargs pkg.testing
Будет импортирован пакет pkg.testing
, и его расположение в файловой системе
будет использовано для поиска и запуска тестов.
Изменение вывода сообщений трассировки¶
Примеры вывода:
pytest --showlocals # показывать локальные переменные в сообщениях
pytest -l # показывать локальные переменные в сообщениях (краткий вариант)
pytest --tb=auto # (по умолчанию) "расширенный" вывод для первого и
# последнего сообщений, и "короткий" для остальных
pytest --tb=long # исчерпывающий, подробный формат сообщений
pytest --tb=short # сокращенный формат сообщений
pytest --tb=line # только одна строка на падение
pytest --tb=native # стандартный формат библиотеки Python
pytest --tb=no # никаких сообщений
Использование --full-trace
приводит к тому, что при ошибке печатаются очень длинные
трассировки (длиннее, чем при --tb=long
). Параметр также гарантирует, что сообщения
трассировки будут напечатаны при прерывании выполнения c клавиатуры с помощью Ctrl+C.
Это очень полезно, если тесты занимают слишком много времени, и вы прерываете их
с клавиатуры с помощью Ctrl+C, чтобы узнать, где они зависли. По умолчанию при прерывании
вывод не будет показан (поскольку исключение KeyboardInterrupt
будет поймано pytest
).
Используя этот параметр, вы можете быть уверены, что увидите трассировку.
Детализация сводного отчета¶
Флаг -r
можно использовать для отображения «краткой сводной информации по тестированию»
в конце тестового сеанса, что упрощает получение четкой картины всех сбоев, пропусков, xfails и т. д.
По умолчанию для списка сбоев и ошибок используется добавочная комбинация fE
.
Пример:
# content of test_example.py
import pytest
@pytest.fixture
def error_fixture():
assert 0
def test_ok():
print("ok")
def test_fail():
assert 0
def test_error(error_fixture):
pass
def test_skip():
pytest.skip("skipping this test")
def test_xfail():
pytest.xfail("xfailing this test")
@pytest.mark.xfail(reason="always xfail")
def test_xpass():
pass
$ pytest -ra
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-5.x.y, py-1.x.y, pluggy-0.x.y
cachedir: $PYTHON_PREFIX/.pytest_cache
rootdir: $REGENDOC_TMPDIR
collected 6 items
test_example.py .FEsxX [100%]
================================== ERRORS ==================================
_______________________ ERROR at setup of test_error _______________________
@pytest.fixture
def error_fixture():
> assert 0
E assert 0
test_example.py:6: AssertionError
================================= FAILURES =================================
________________________________ test_fail _________________________________
def test_fail():
> assert 0
E assert 0
test_example.py:14: AssertionError
========================= short test summary info ==========================
SKIPPED [1] $REGENDOC_TMPDIR/test_example.py:22: skipping this test
XFAIL test_example.py::test_xfail
reason: xfailing this test
XPASS test_example.py::test_xpass always xfail
ERROR test_example.py::test_error - assert 0
FAILED test_example.py::test_fail - assert 0
== 1 failed, 1 passed, 1 skipped, 1 xfailed, 1 xpassed, 1 error in 0.12s ===
Параметр -r
принимает ряд символов после себя. Использованный выше символ а
означает
“все, кроме успешных».
Вот полный список доступных символов, которые можно использовать:
f
- упавшие (добавляет раздел FAILED)
E
- ошибки (добавляет раздел ERROR)
s
- пропущенные (добавляет раздел SKIPPED)
x
- тесты XFAIL (добавляет раздел XFAIL)
X
- тесты XPASS (добавляет раздел XPASS)
p
- успешные (passed)
P
- успешные (passed) с выводом
Есть и специальные символы для пропуска отдельных групп:
a
- выводить все, кромеpP
A
- выводить все
N
- ничего не выводить (может быть полезным, поскольку по умолчанию используется комбинацияfE
).
Можно использовать более одного символа. Например, для того, чтобы увидеть только упавшие и пропущенные тесты, можно выполнить:
$ pytest -rfs
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-5.x.y, py-1.x.y, pluggy-0.x.y
cachedir: $PYTHON_PREFIX/.pytest_cache
rootdir: $REGENDOC_TMPDIR
collected 6 items
test_example.py .FEsxX [100%]
================================== ERRORS ==================================
_______________________ ERROR at setup of test_error _______________________
@pytest.fixture
def error_fixture():
> assert 0
E assert 0
test_example.py:6: AssertionError
================================= FAILURES =================================
________________________________ test_fail _________________________________
def test_fail():
> assert 0
E assert 0
test_example.py:14: AssertionError
========================= short test summary info ==========================
FAILED test_example.py::test_fail - assert 0
SKIPPED [1] $REGENDOC_TMPDIR/test_example.py:22: skipping this test
== 1 failed, 1 passed, 1 skipped, 1 xfailed, 1 xpassed, 1 error in 0.12s ===
Использование p
добавляет в сводный отчет успешные тесты, а P
добавляет
дополнительный раздел «пройдены” (PASSED) для тестов, которые прошли, но перехватили вывод:
$ pytest -rpP
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-5.x.y, py-1.x.y, pluggy-0.x.y
cachedir: $PYTHON_PREFIX/.pytest_cache
rootdir: $REGENDOC_TMPDIR
collected 6 items
test_example.py .FEsxX [100%]
================================== ERRORS ==================================
_______________________ ERROR at setup of test_error _______________________
@pytest.fixture
def error_fixture():
> assert 0
E assert 0
test_example.py:6: AssertionError
================================= FAILURES =================================
________________________________ test_fail _________________________________
def test_fail():
> assert 0
E assert 0
test_example.py:14: AssertionError
================================== PASSES ==================================
_________________________________ test_ok __________________________________
--------------------------- Captured stdout call ---------------------------
ok
========================= short test summary info ==========================
PASSED test_example.py::test_ok
== 1 failed, 1 passed, 1 skipped, 1 xfailed, 1 xpassed, 1 error in 0.12s ===
Запуск отладчика PDB (Python Debugger) при падении тестов¶
python
содержит встроенный отладчик PDB (Python Debugger). pytest
позволяет
запустить отладчик с помощью параметра командной строки:
pytest --pdb
Использование параметра позволяет запускать отладчик при каждом падении теста (или прерывании его с клавиатуры). Часто хочется сделать это для первого же упавшего теста, чтобы понять причину его падения:
pytest -x --pdb # вызывает отладчик при первом падении и завершает тестовую сессию
pytest --pdb --maxfail=3 # вызывает отладчик для первых трех падений
Обратите внимание, что при любом падении информация об исключении сохраняется в
sys.last_value
, sys.last_type
и sys.last_traceback
. При интерактивном использовании
это позволяет перейти к отладке после падения с помощью любого инструмента отладки.
Можно также вручную получить доступ к информации об исключениях, например:
>>> import sys
>>> sys.last_traceback.tb_lineno
42
>>> sys.last_value
AssertionError('assert result == "ok"',)
Запуск отладчика PDB (Python Debugger) в начале теста¶
pytest
позволяет запустить отладчик сразу же при старте каждого теста.
Для этого нужно передать следующий параметр:
pytest --trace
В этом случае отладчик будет вызываться при запуске каждого теста.
Установка точек останова¶
Чтобы установить точку останова, вызовите в коде import pdb;pdb.set_trace()
, и
pytest
автоматически отключит перехват вывода для этого теста, при этом:
на перехват вывода в других тестах это не повлияет;
весь перехваченный ранее вывод будет обработан как есть;
перехват вывода возобновится после завершения отладочной сессии (с помощью команды
continue
).
Использование встроенной функции breakpoint¶
Python 3.7
содержит встроенную функцию breakpoint()
.
pytest
поддерживает использование breakpoint()
следующим образом:
если вызывается
breakpoint()
, и при этом переменнаяPYTHONBREAKPOINT
установлена в значение по умолчанию,pytest
использует расширяемый отладчик PDB вместо системного;когда тестирование будет завершено, система снова будет использовать отладчик
Pdb
по умолчанию;если
pytest
вызывается с опцией--pdb
то расширяемый отладчик PDB используется как для функцииbreakpoint()
, так и для упавших тестов/необработанных исключений;для определения пользовательского класса отладчика можно использовать
--pdbcls
.
Профилирование продолжительности выполнения теста¶
Чтобы получить список 10 самых медленных тестов, выполните:
pytest --durations=10
По умолчанию, pytest
не покажет тесты со слишком маленькой (менее одной сотой секунды)
длительностью выполнения, если в командной строке не будет передан параметр -vv
.
Модуль faulthandler
¶
Стандартный модуль faulthandler
можно использовать для сброса трассировок Python
при ошибке или по истечении времени ожидания.
При запуске pytest
модуль автоматически подключается, если только в командной строке
не используется опция -p no:faulthandler
.
Кроме того, для сброса трассировок всех потоков в случае, когда тест длится более
X
секунд, можно использовать опцию
faulthandler_timeout=X
(для Windows неприменима).
Примечание
Эта функциональность была интегрирована из внешнего плагина pytest-faulthandler с двумя небольшими изменениями:
чтобы ее отключить, используйте
-p no:faulthandler
вместо--no-faulthandler
;опция командной строки
--faulthandler-timeout
превратилась в конфигурационную опцию faulthandler_timeout. Ее по-прежнему можно настроить из команндной строки, используя-o faulthandler_timeout=X
.
Создание файлов формата JUnit¶
Чтобы создать результирующие файлы в формате, понятном Jenkins или другому серверу непрерывной интеграции, используйте вызов:
pytest --junitxml=path
Команда создает xml-файл по указанному пути.
Чтобы задать имя корневого xml-элемента для набора тестов, можно настроить параметр
junit_suite_name
в конфигурационном файле:
[pytest]
junit_suite_name = my_suite
Спецификация JUnit XML, по-видимому, указывает, что атрибут "time"
должен сообщать
об общем времени выполнения теста, включая выполнение setup- и teardown- методов
(1, 2).
Это поведение pytest
по умолчанию. Чтобы вместо этого сообщать только о длительности вызовов,
настройте параметр junit_duration_report
следующим образом:
[pytest]
junit_duration_report = call
record_property¶
Чтобы записать дополнительную информацию для теста, используйте фикстуру record_property
:
def test_function(record_property):
record_property("example_key", 1)
assert True
Такая запись добавит дополнительное свойство example_key="1"
к сгенерированному тегу testcase
:
<testcase classname="test_function" file="test_function.py" line="0" name="test_function" time="0.0009">
<properties>
<property name="example_key" value="1" />
</properties>
</testcase>
Эту функциональность также можно использовать совместно с пользовательскими маркерами:
# content of conftest.py
def pytest_collection_modifyitems(session, config, items):
for item in items:
for marker in item.iter_markers(name="test_id"):
test_id = marker.args[0]
item.user_properties.append(("test_id", test_id))
И в тесте:
# content of test_function.py
import pytest
@pytest.mark.test_id(1501)
def test_function():
assert True
В файле получим:
<testcase classname="test_function" file="test_function.py" line="0" name="test_function" time="0.0009">
<properties>
<property name="test_id" value="1501" />
</properties>
</testcase>
Предупреждение
Пожалуйста, обратите внимание, что использование этой возможности приведет к записи некорректного с точки зрения JUnitXML-схем последних версий файла и может вызывать проблемы при работе с некоторыми серверами непрерывной интеграции.
record_xml_attribute¶
Чтобы добавить дополнительный атрибут в элемент testcase
, можно использовать
фикстуру record_xml_attribute
. Ее также можно использовать для переопределения
существующих значений:
def test_function(record_xml_attribute):
record_xml_attribute("assertions", "REQ-1234")
record_xml_attribute("classname", "custom_classname")
print("hello world")
assert True
В отличие от record_property
, дочерний элемент в данном случае не добавляется.
Вместо этого в элемент testcase
будет добавлен атрибут assertions="REQ-1234"
,
а значение атрибута classname
по умолчанию будет заменено на "classname=custom_classname"
:
<testcase classname="custom_classname" file="test_function.py" line="0" name="test_function" time="0.003" assertions="REQ-1234">
<system-out>
hello world
</system-out>
</testcase>
Предупреждение
record_xml_attribute
пока используется в режиме эксперимента, и в будущем может быть
заменен чем-то более мощным и/или общим. Однако сама функциональность как таковая будет сохранена.
Использование record_xml_attribute
поверх record_xml_property
может быть полезным при
парсинге xml-отчетов средствами непрерывной интеграции. Однако некоторые парсеры допускают
не любые элементы и атрибуты. Многие инструменты (как в примере ниже), используют xsd-схему
для валидации входящих xml. Поэтому убедитесь, что имена атрибутов, которые вы используете,
являются допустимыми для вашего парсера.
Ниже представлена схема, которую использует Jenkins
для валидации xml-отчетов:
<xs:element name="testcase">
<xs:complexType>
<xs:sequence>
<xs:element ref="skipped" minOccurs="0" maxOccurs="1"/>
<xs:element ref="error" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="failure" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="system-out" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="system-err" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required"/>
<xs:attribute name="assertions" type="xs:string" use="optional"/>
<xs:attribute name="time" type="xs:string" use="optional"/>
<xs:attribute name="classname" type="xs:string" use="optional"/>
<xs:attribute name="status" type="xs:string" use="optional"/>
</xs:complexType>
</xs:element>
Предупреждение
Пожалуйста, обратите внимание, что использование этой возможности приведет к записи некорректного с точки зрения JUnitXML-схем последних версий файла и может вызывать проблемы при работе с некоторыми серверами непрерывной интеграции.
Чтобы добавить свойства каждому тесту из набора, можно использовать фикстуру
record_testsuite_property
с параметром scope="session"
(в этом случае она будет
применяться ко всем тестам тестовой сессии).
import pytest
@pytest.fixture(scope="session", autouse=True)
def log_global_env_facts(record_testsuite_property):
record_testsuite_property("ARCH", "PPC")
record_testsuite_property("STORAGE_TYPE", "CEPH")
class TestMe:
def test_foo(self):
assert True
Этой фикстуре передаются имя (name
) и значение (value
) тэга <property>
, который
добавляется на уровне тестового набора для генерируемого xml-файла:
<testsuite errors="0" failures="0" name="pytest" skipped="0" tests="1" time="0.006">
<properties>
<property name="ARCH" value="PPC"/>
<property name="STORAGE_TYPE" value="CEPH"/>
</properties>
<testcase classname="test_me.TestMe" file="test_me.py" line="16" name="test_foo" time="0.000243663787842"/>
</testsuite>
name
должно быть строкой, а value
будет преобразовано в строку
и корректно экранировано.
В отличие от случаев использования record_property и record_xml_attribute
созданный xml-файл будет совместим с последним стандартом xunit
.
Создание файлов в формате resultlog¶
Для создания машиночитаемых логов в формате plain-text
можно выполнить
pytest --resultlog=path
и просмотреть содержимое по указанному пути path
. Эти файлы также используются
ресурсом PyPy-test для отображения результатов тестов после ревизий.
Предупреждение
Поскольку эта возможность редко используется, она запланирована к удалению в pytest 6.0
.
Если вы пользуетесь ею, рассмотрите возможность использования нового плагина pytest-reportlog .
Подробнее см.: the deprecation docs.
Отправка отчетов на сервис pastebin¶
Создание ссылки для каждого упавшего теста:
pytest --pastebin=failed
Эта команда отправит информацию о прохождении теста на удаленный
сервис регистрации и сгенерирует ссылку для каждого падения. Тесты можно отбирать
как обычно, или, например, добавить -x
, если вы хотите отправить данные
по конкретному упавшему тесту.
Создание ссылки для лога тестовой сессии:
pytest --pastebin=all
В настоящее время реализовна регистрация только в сервисе http://bpaste.net.
Изменено в вресии 5.2
Если по каким-то причинам не удалось создать ссылку, вместо падения всего тестового набора генерируется предупреждение.
Подключение плагинов¶
В командной строке можно явно подгрузить какой-либо внутренний или внешний плагин, используя опцию -p
:
pytest -p mypluginmodule
Опция принимает параметр name
, который может быть:
Полным именем модуля, записанным через точку, например
myproject.plugins
. Имя должно быть импортируемым.«Входным» именем плагина, которое передается в
setuptools
при регистрации плагина. К примеру, чтобы подгрузить pytest-cov , нужно использовать:pytest -p pytest_cov
Отключение плагинов¶
Чтобы отключить загрузку определенных плагинов во время вызова, используйте опцию -p
с префиксом no:
.
Пример: чтобы отключить загрузку плагина doctest
, который отвечает за выполнение
тестов из строк «docstring», вызовите pytest
следующим образом:
pytest -p no:doctest
Вызов pytest
из кода Python¶
pytest
можно вызвать прямо в коде Python:
pytest.main()
Такой способ эквивалентен вызову «pytest» из командной строки.
В этом случае вместо исключения SystemExit
возвращается статус завершения.
Можно также передавать параметры и опции:
pytest.main(["-x", "mytestdir"])
Дополнительные плагины можно указать в pytest.main
:
# content of myinvoke.py
import pytest
class MyPlugin:
def pytest_sessionfinish(self):
print("*** test run reporting finishing")
pytest.main(["-qq"], plugins=[MyPlugin()])
Выполнив этот код, увидим, что MyPlugin
был загружен и применен:
$ python myinvoke.py
.FEsxX. [100%]*** test run reporting finishing
================================== ERRORS ==================================
_______________________ ERROR at setup of test_error _______________________
@pytest.fixture
def error_fixture():
> assert 0
E assert 0
test_example.py:6: AssertionError
================================= FAILURES =================================
________________________________ test_fail _________________________________
def test_fail():
> assert 0
E assert 0
test_example.py:14: AssertionError
Примечание
Вызов pytest.main()
приводит к тому, что импортируются не только тесты,
но и все модули, которые они используют. Из-за механизма кэширования импорта
Python
последующие вызовы pytest.main()
из того же процесса не будут учитывать
изменения в файлах, внесенные между вызовами. Поэтому не рекомендуется многократное
использование pytest.main()
в одном и том же процессе (например, при перезапуске тестов).