13.2 【代码测试】pytest 的使用 ============================== 转载自：http://kuanghy.github.io/2018/05/08/pytest ``Pytest`` 是一个比较成熟且功能完备的 Python 测试框架。其提供完善的在线文档，并有着大量的第三方插件和内置帮助，适用于许多小型或大型项目。Pytest 灵活易学，打印调试和测试执行期间可以捕获标准输出，适合简单的单元测试到复杂的功能测试。还可以执行 nose, unittest 和 doctest 风格的测试用例，甚至 Django 和 trial。支持良好的集成实践， 支持扩展的 xUnit 风格 setup，支持非 python 测试。支持生成测试覆盖率报告，支持 PEP8 兼容的编码风格。 1. 基本使用 ----------- :: usage: py.test [options] [file_or_dir] [file_or_dir] [...] 用例查找规则 ~~~~~~~~~~~~ 如果不带参数运行 pytest，那么其先从配置文件(pytest.ini，tox.ini，setup.cfg)中查找配置项 ``testpaths`` 指定的路径中的 test case，如果没有则从当前目录开始查找，否者，命令行参数就用于目录、文件查找。查找的规则如下： - 查找指定目录中以 ``test`` 开头的目录 - 递归遍历目录，除非目录指定了不同递归 - 查找文件名以 ``test_`` 开头的文件 - 查找以 ``Test`` 开头的类(该类不能有 init 方法) - 查找以 ``test_`` 开头的函数和方法并进行测试 如果要从默认的查找规则中忽略查找路径，可以加上 ``--ingore`` 参数，例如： .. code:: shell $ pytest –ignore=tests/test_foobar.py 调用 pytest ~~~~~~~~~~~ - py.test： Pytest 提供直接调用的命令行工具，即 ``py.test``\ ，最新版本 ``pytest`` 和 ``py.test`` 两个命令行工具都可用 - python -m pytest： 效果和 ``py.test`` 一样, 这种调用方式在多 Python 版本测试的时候是有用的, 例如测试 Python3： .. code:: shell $ python3 -m pytest […] 部分参数介绍 ~~~~~~~~~~~~ :: py.test --version 查看版本 py.test --fixtures, --funcargs 查看可用的 fixtures pytest --markers 查看可用的 markers py.test -h, --help 命令行和配置文件帮助 # 失败后停止 py.test -x 首次失败后停止执行 py.test --maxfail=2 两次失败之后停止执行 # 调试输出 py.test -l, --showlocals 在 traceback 中显示本地变量 py.test -q, --quiet 静默模式输出 py.test -v, --verbose 输出更详细的信息 py.test -s 捕获输出, 例如显示 print 函数的输出 py.test -r char 显示指定测试类型的额外摘要信息 py.test --tb=style 错误信息输出格式 - long 默认的traceback信息格式化形式 - native 标准库格式化形式 - short 更短的格式 - line 每个错误一行 # 运行指定 marker 的测试 pytest -m MARKEXPR # 运行匹配的测试 py.test -k stringexpr # 只收集并显示可用的测试用例，但不运行测试用例 py.test --collect-only # 失败时调用 PDB py.test --pdb 执行选择用例 ~~~~~~~~~~~~ - 执行单个模块中的全部用例: .. code:: shell $ py.test test_mod.py - 执行指定路径下的全部用例: .. code:: shell $ py.test somepath - 执行字符串表达式中的用例: .. code:: shell $ py.test -k stringexpr 比如 “MyClass?and not method”，选择 TestMyClass.test_something，排除了TestMyClass.test_method_simple。 - 导入 package，使用其文件系统位置来查找和执行用例。执行 pkg 目录下的所有用例: .. code:: shell $ py.test –pyargs pkg - 运行指定模块中的某个用例，如运行 test_mod.py 模块中的 test_func 测试函数: .. code:: shell $ pytest test_mod.py::test_func - 运行某个类下的某个用例，如运行 TestClass 类下的 test_method 测试方法: .. code:: shell $ pytest test_mod.py::TestClass::test_method 2. 断言 ------- 通常情况下使用 ``assert`` 语句就能对大多数测试进行断言。对于异常断言，可以使用上下文管理器 ``pytest.raises``\ ： .. code:: python def test_zero_division(): with pytest.raises(ZeroDivisionError): 1 / 0 # 还可以捕获异常信息 def test_zero_division(): with pytest.raises(ZeroDivisionError, message='integer division or modulo by zero'): 1 / 0 对于警告断言，可以使用上下文管理器 ``pytest. warns``\ ： .. code:: python with pytest.warns(RuntimeWarning): warnings.warn("my warning", RuntimeWarning) with warns(UserWarning, match='must be 0 or None'): warnings.warn("value must be 0 or None", UserWarning) with warns(UserWarning, match=r'must be \d+$'): warnings.warn("value must be 42", UserWarning) 如果仅需断言 ``DeprecationWarning`` 或者 ``PendingDeprecationWarning`` 警告，可以使用 ``pytest.deprecated_call``\ ： .. code:: python def api_call_v2(): warnings.warn('use v3 of this api', DeprecationWarning) return 200 def test(): with pytest.deprecated_call(): assert api_call_v2() == 200 对于自定义类型的 assert 比较断言，可以通过在 ``conftest.py`` 文件中实现\ ``pytest_assertrepr_compare`` 函数来实现： .. code:: python # content of test_foocompare.py class Foo: def __init__(self, val): self.val = val def __eq__(self, other): return self.val == other.val def test(): assert 1 == 1 def test_compare(): f1 = Foo(1) f2 = Foo(2) f3 = Foo(1) assert f1 == f3 assert f1 == f2 # content of conftest.py def pytest_assertrepr_compare(op, left, right): from test_foocompare import Foo if isinstance(left, Foo) and isinstance(right, Foo) and op == "==": return ['Comparing Foo instances:', 'vals: %s != %s' % (left.val, right.val)] 如果需要手动设置失败原因，可以使用 ``pytest.fail``: .. code:: python def test_sys_version(): if sys.version_info[0] == 2: pytest.fail("python2 not supported") 使用 ``pytest.skip`` 和 ``pytest.xfail`` 能够实现跳过测试的功能，skip 表示直接跳过测试，而 xfail 则表示存在预期的失败，但两者的效果差不多： .. code:: python def test_skip_and_xfail(): if sys.version_info[0] < 3: pytest.skip('only support python3') print("--- start") try: 1/0 except Exception as e: pytest.xfail("division by zero: {}".format(e)) print("--- end") ``pytest.importorskip`` 可以在导入失败的时候跳过测试，还可以要求导入的包要满足特定的版本： :: docutils = pytest.importorskip("docutils") docutils = pytest.importorskip("docutils", minversion = "0.3") 断言近似相等可以使用 ``pytest.approx``\ ： :: assert 2.2 == pytest.approx(2.3) assert 2.2 == pytest.approx(2.3, 0.1) assert pytest.approx(2.3, 0.1) == 2.2 3. conftest.py -------------- 从广义理解，\ ``conftest.py`` 是一个本地的 ``per-directory`` 插件，在该文件中可以定义目录特定的 hooks 和 fixtures。\ ``py.test`` 框架会在它测试的项目中寻找 conftest.py 文件，然后在这个文件中寻找针对整个目录的测试选项，比如是否检测并运行 doctest 以及应该使用哪种模式检测测试文件和函数。 总结起来，\ ``conftest.py`` 文件大致有如下几种功能： - **Fixtures:** 用于给测试用例提供静态的测试数据，其可以被所有的测试用于访问，除非指定了范围 - **加载插件:** 用于导入外部插件或模块: :: pytest_plugins ="myapp.testsupport.myplugin" - **定义钩子:** 用于配置钩子(hook)，如 pytest_runtest_setup、pytest_runtest_teardown、pytest_config 等： :: def pytest_runtest_setup(item): """called before `pytest_runtest_call(item)`""" pass 再比如添加命令行选项的钩子： :: # content of conftest.py import pytest def pytest_addoption(parser): parser.addoption("--full", action="store_ture", help="run full test") # content of test.py @pytest.mark.skipif(not pytest.config.getoption("--runslow")) def test_func_slow_1(): """当在命令行执行 --runslow 参数时才执行该测试""" print 'skip slow' - **测试根路径:** 如果将 conftest.py 文件放在项目根路径中，则 pytest 会自己搜索项目根目录下的子模块，并加入到 sys.path 中，这样便可以对项目中的所有模块进行测试，而不用设置 PYTHONPATH 来指定项目模块的位置。 可以有多个 ``conftest.py`` 文件同时存在，其作用范围是目录。例如测试非常复杂时，可以为特定的一组测试创建子目录，并在该目录中创建 conftest.py 文件，并定义一个 futures 或 hooks。就像如下的结构： :: tests ├── conftest.py ├── mod │ └── conftest.py ├── mod2 │ └── conftest.py └── mod3 └── conftest.py 4. Fixtures ----------- ``fixture`` 是 pytest 特有的功能，它用 pytest.fixture 标识，定义在函数前面。在编写测试函数的时候，可以将此函数名称做为传入参数，pytest 将会以依赖注入方式，将该函数的返回值作为测试函数的传入参数。 :: pytest.fixture(scope='function', params=None, autouse=False, ids=None) 作为参数 ~~~~~~~~ ``fixture`` 可以作为其他测试函数的参数被使用，前提是其必须返回一个值： :: @pytest.fixture() def hello(): return "hello" def test_string(hello): assert hello == "hello", "fixture should return hello" 一个更加实用的例子： :: @pytest.fixture def smtp(): import smtplib return smtplib.SMTP("smtp.gmail.com") def test_ehlo(smtp): response, msg = smtp.ehlo() assert response == 250 assert 0 # for demo purposes 作为 setup ~~~~~~~~~~ ``fixture`` 也可以不返回值，这样可以用于在测试方法运行前运行一段代码： :: @pytest.fixture() # 默认参数，每个测试方法前调用 def before(): print('before each test') def test_1(before): print('test_1()') @pytest.mark.usefixtures("before") def test_2(): print('test_2()') 这种方式与 setup_method、setup_module 等的用法相同，其实它们也是特殊的 fixture。 在上例中，有一个测试用了 ``pytest.mark.usefixtures`` 装饰器来标记使用哪个 fixture，这中用法表示在开始测试前应用该 fixture 函数但不需要其返回值。使用这种用法时，通过 ``addfinallizer`` 注册释放函数，以此来做一些“善后”工作，这类似于 teardown_function、teardown_module 等用法。示例： :: @pytest.fixture() def smtp(request): import smtplib smtp = smtplib.SMTP("smtp.gmail.com") def fin(): print ("teardown smtp") smtp.close() request.addfinalizer(fin) return smtp # provide the fixture value 作用范围 ~~~~~~~~ ``fixtrue`` 可以通过设置 scope 参数来控制其作用域（同时也控制了调用的频率）。如果 ``scope='module'``\ ，那么 fixture 就是模块级的，这个 fixture 函数只会在每次相同模块加载的时候执行。这样就可以复用一些需要时间进行创建的对象。fixture 提供三种作用域，用于指定 fixture 初始化的规则： - function：每个测试函数之前执行一次，默认 - module：每个模块加载之前执行一次 - session：每次 session 之前执行一次，即每次测试执行一次 反向请求 ~~~~~~~~ ``fixture`` 函数可以通过接受 ``request`` 对象来反向获取请求中的测试函数、类或模块上下文。例如： :: @pytest.fixture(scope="module") def smtp(request): import smtplib server = getattr(request.module, "smtpserver", "smtp.qq.com") smtp = smtplib.SMTP(server, 587, timeout=5) yield smtp smtp.close() 有时需要全面测试多种不同条件下的一个对象，功能是否符合预期。可以通过设置 fixture 的 params 参数，然后通过 request 获取设置的值： :: class Foo(object): def __init__(self, a, b, c): self.a = a self.b = b self.c = c def echo(self): print self.a, self.b, self.c return True @pytest.fixture(params=[["1", "2", "3"], ["x", "y", "z"]]) def foo(request): return Foo(*request.param) def test_foo(foo): assert foo.echo() 设置 params 参数后，运行 test 时将生成不同的测试 id，可以通过 ids 自定义 id： :: @pytest.fixture(params=[1, 2, 4, 8], ids=["a", "b", "c", "d"]) def param_a(request): return request.param def test_param_a(param_a): print param_a 运行以上实例会有如下结果： :: test_fixture.py::test_param_a[a] 1 PASSED test_fixture.py::test_param_a[b] 2 PASSED test_fixture.py::test_param_a[c] 4 PASSED test_fixture.py::test_param_a[d] 8 PASSED 自动执行 ~~~~~~~~ 有时候需要某些 fixture 在全局自动执行，如某些全局变量的初始化工作，亦或一些全局化的清理或者初始化函数。这时可以通过设置 fixture 的 autouse 参数来让 fixture 自动执行。设置为 autouse=True 即可使得函数默认执行。以下例子会在开始测试前清理可能残留的文件，接着将程序目录设置为该目录，： :: work_dir = "/tmp/app" @pytest.fixture(scope="session", autouse=True) def clean_workdir(): shutil.rmtree(work_dir) os.mkdir(work_dir) os.chrdir(work_dir) 5. setup/teardown ----------------- ``setup/teardown`` 是指在模块、函数、类开始运行以及结束运行时执行一些动作。比如在一个函数中测试一个数据库应用，测需要在函数开始前连接数据库，在函数运行结束后断开与数据库的连接。setup/teardown 是特殊的 fixture，其可以有一下几种实现方式： :: # 模块级别 def setup_module(module): pass def teardown_module(module): pass # 类级别 @classmethod def setup_class(cls): pass @classmethod def teardown_class(cls): pass # 方法级别 def setup_method(self, method): pass def teardown_method(self, method): pass # 函数级别 def setup_function(function): pass def teardown_function(function): pass 有时候，还希望有全局的 setup 或 teardown，以便在测试开始时做一些准备工作，或者在测试结束之后做一些清理工作。这可以用 hook 来实现： :: def pytest_sessionstart(session): # setup_stuff def pytest_sessionfinish(session, exitstatus): # teardown_stuff 也可以用 fixture 的方式实现： :: @fixture(scope='session', autouse=True) def my_fixture(): # setup_stuff yield # teardown_stuff 6. Markers ---------- ``marker`` 的作用是，用来标记测试，以便于选择性的执行测试用例。Pytest 提供了一些内建的 marker： :: # 跳过测试 @pytest.mark.skip(reason=None) # 满足某个条件时跳过该测试 @pytest.mark.skipif(condition) # 预期该测试是失败的 @pytest.mark.xfail(condition, reason=None, run=True, raises=None, strict=False) # 参数化测试函数。给测试用例添加参数，供运行时填充到测试中 # 如果 parametrize 的参数名称与 fixture 名冲突，则会覆盖掉 fixture @pytest.mark.parametrize(argnames, argvalues) # 对给定测试执行给定的 fixtures # 这种用法与直接用 fixture 效果相同 # 只不过不需要把 fixture 名称作为参数放在方法声明当中 @pytest.mark.usefixtures(fixturename1, fixturename2, ...) # 让测试尽早地被执行 @pytest.mark.tryfirst # 让测试尽量晚执行 @pytest.mark.trylast 例如一个使用参数化测试的例子： :: @pytest.mark.parametrize(("n", "expected"), [ (1, 2), (2, 3), ]) def test_increment(n, expected): assert n + 1 == expected 除了内建的 markers 外，pytest 还支持没有实现定义的 markers，如： :: @pytest.mark.old_test def test_one(): assert False @pytest.mark.new_test def test_two(): assert False @pytest.mark.windows_only def test_three(): assert False 通过使用 ``-m`` 参数可以让 pytest 选择性的执行部分测试： :: $ pytest test.py -m 'not windows_only' ... collected 3 items / 1 deselected test_marker.py::test_one FAILED 更详细的关于 marker 的说明可以参考官方文档： - https://docs.pytest.org/en/latest/mark.html - https://docs.pytest.org/en/latest/example/markers.html 7. 第三方插件 ------------- - pytest-randomly: 测试顺序随机 - pytest-xdist: 分布式测试 - pytest-cov: 生成测试覆盖率报告 - pytest-pep8: 检测代码是否符合 PEP8 规范 - pytest-flakes: 检测代码风格 - pytest-html: 生成 html 报告 - pytest-rerunfailures: 失败重试 - pytest-timeout: 超时测试 8. 参考资料 ----------- - https://docs.pytest.org/en/latest/example/ - https://docs.pytest.org/en/latest/assert.html - https://docs.pytest.org/en/latest/reference.html - http://doc.pytest.org/en/latest/xunit_setup.html - https://docs.pytest.org/en/latest/skipping.html - https://docs.pytest.org/en/latest/fixture.html - http://senarukana.github.io/2015/05/29/pytest-fixture/ - https://docs.pytest.org/en/latest/parametrize.html - https://docs.pytest.org/en/latest/plugins.html