pytest插件探索——pytest-xdist

背景

经常做pytest插件开发的话, 一定会看到不少如下代码片段:

def pytest_configure(config):
    ...
    # prevent ... on slave nodes (xdist)
    if not hasattr(config, 'slaveinput'):
        ...

其实这些代码都是为了兼容一个叫pytest-xdist的插件的.简单介绍一下这款插件, pytest-xdist这款插件允许用户将测试并发执行(进程级并发). 主要开发者是pytest目前的核心开发人员Bruno Oliveira, 截至写作时, 该项目已有371个star, 应用于4150个项目. 需要注意的是, 由于插件是动态决定测试用例执行顺序的,为了保证各个测试能在各个独立线程里正确的执行, 用例的作者应该保证测试用例的独立性(这也符合测试用例设计的最佳实践).

流程

这里介绍了插件的执行原理, 我作了简单的翻译并且加了一部分注解.

和大多数的分布式系统相似, xdist里有master和worker的概念.master负责整个测试任务的调度, 测试报告等工作, 而worker则是实际执行测试的宿主进程.

具体的测试执行的流程如下:

1. 在test session的起始阶段, xdist会spawn一个或者多个worker进程. master和worker间的通信基于 execnet 和它的gateways. worker的解释器可以是本地或者远程的.

2. 收集测试项:

   每个worker是个迷你的pytest runner对象. workers这时会执行一个完整test collection过程, 然后将结果发回到master(master本身不做测试收集工作).

3. 测试收集检查:

   master收到这些节点发回的结果后, 执行一些sanity检查以确保所有worker节点都收集到相同的测试项(包括顺序). 当所有的检查都通过后, 再将这些测试项转换为一个简单的索引列表, 每个索引对应一个测试项的在原来测试集中的位置. 这个方案可行的原因是所有的节点都保存着相同的测试集, 并且使用这种方式可以节省带宽, 因为master只需要告知节点需要执行的测试项对应的索引, 而不用告知完整的测试项信息.

   FAQ环节其实提到, 在各个node上单独执行测试收集工作是因为如果在master上执行测试收集,那么就需要作很多序列化处理, 因为worker是进程级的. 这会使问题复杂化, 并且使pytest变得不易于维护.

4. 测试分发:

   • 如果dist-mode是each, 那么这时master只需将完整的列表发送给每个节点.
   • 如果dist-mode是load, 那么这时master会将大约25%的测试项以轮询的方式发往各个worker. 剩余的测试项则会等待workers执行完测试以后分发, 见下文.

   注意: pytest_xdist_make_scheduler 这个hook可以用于实现自定义的分发逻辑.

5. 测试执行:

   workers 重写了 pytest_runtestloop: pytest的默认实现基本上是循环执行所有在session这个对象里面收集到的测试项, 但是在xdist里, workers实际上是等待master为其发送需要执行的测试项的. 当worker收到测试任务, 就顺序执行 pytest_runtest_protocol. 值得注意的一个细节是:workers 必须始终保持至少一个测试项在的任务队列里, 以兼容pytest_runtest_protocol(item, nextitem) hook的参数要求.为了将 nextitem传给hook, worker会在执行最后一个测试项前等待master的更多指令.如果它收到了更多测试项, 那么久可以安全的执行 pytest_runtest_protocol , 因为这时nextitem参数已经可以确定. 如果它收到一个 "shutdown"信号, 那么就将 nextitem 参数设为 None, 然后执行pytest_runtest_protocol .

6. 测试分发(Load模式):

   当测试项在 workers里的开始/结束执行时, 测试结果会发回到master, 这样其他pytest hooks比如pytest_runtest_logstart和 pytest_runtest_logreport就可以正常执行.master (处于load的dist-mode时)在节点执行完一个测试后, 基于测试执行时长以及每个节点剩余测试项综合决定是否向这个节点发送更多的测试项.

7. 测试结束:

   当master没有更多待执行测试项时, 它会发送一个"shutdown"信号给所有workers, worker将剩余的测试项执行完毕并退出进程. master则一直等待workers全部退出, 当然此时任然需要处理诸如pytest_runtest_logreport等事件.

Best Practice

在了解了pytest-xdist的实现原理后, 为了保证开发的插件能够正常与其配合(没办法, 这个插件太流行了), 建议在插件开发时:

• 对于只需在master上执行的代码, 比如report类插件, 通常只需在master节点上初始化一遍并处理各个report对象. 我们可以通过判断 hasattr(config, 'slaveinput')来确定是否为worker节点, 区分处理相逻辑;

• 由于测试执行实际是在各个worker节点上执行的, 在pytest_runtest_makereport等hooks里要避免对象实例化操作, 因为你的实例化对象在序列化时会报错, 比如某些测试使用了下面的conftest.py文件:

  import pytest
  
  
  class SomeThing(object):
      pass
  
  
  @pytest.hookimpl(hookwrapper=True)
  def pytest_runtest_makereport(item, call):
      outcome = yield
      report = outcome.get_result()
      report.something = SomeThing()
  
  
  def pytest_runtest_logreport(report):
      print('something: %r' % report.something)
  

  那么当你使用pytest -n执行时, 就会报类似这样的错误:

  INTERNALERROR> raise DumpError("can't serialize {}".format(tp))
  INTERNALERROR> execnet.gateway_base.DumpError: can't serialize

  正确的做法是, 将需要保存的数据保存到report对象, 比如下面这段代码可以将测试执行的时间戳保存在report对象里, 之后worker便会将report同步给master节点:

  def pytest_runtest_makereport(item, call):
    outcome = yield
    report = outcome.get_result()
    if report.when == "call":
          report.call_start = call.start
          report.call_end = call.stop
  

• 目前发现除了自定义的类以外, 诸如datetime类型也是不能直接序列化的, 遇到这种情况可以考虑将其保存为timestamp, 之后再做类型转换操作.

• 还有一种典型的错误是, 将诸如pytest_runtest_makereport的hook函数写成类的方法, 由于此类hook函数是在worker节点执行的, 如果这个类只在master节点上进行了实例化, 相当于写了个无效的hook函数, 而且这时虽然程序不会报任何错, 这点要特别注意.

总之, 牢记config对象是进程间独立的, 但是report对象之间的值可以互相同步的, 但是要避免同步对象;