Pytest官方教程-22-API参考-Hooks

目录：

1. 安装及入门
2. 使用和调用方法
3. 原有TestSuite使用方法
4. 断言的编写和报告
5. Pytest fixtures：清晰 模块化 易扩展
6. 使用Marks标记测试用例
7. Monkeypatching/对模块和环境进行Mock
8. 使用tmp目录和文件
9. 捕获stdout及stderr输出
10. 捕获警告信息
11. 模块及测试文件中集成doctest测试
12. skip及xfail: 处理不能成功的测试用例
13. Fixture方法及测试用例的参数化
14. 缓存: 使用跨执行状态
15. unittest.TestCase支持
16. 运行Nose用例
17. 经典xUnit风格的setup/teardown
18. 安装和使用插件
19. 插件编写
20. 编写钩子(hook)方法
21. 运行日志
22. API参考
    1. 方法(Functions)
    2. 标记(Marks)
    3. 钩子(Hooks)
    4. 装置(Fixtures)
    5. 对象(Objects)
    6. 特殊变量(Special Variables)
    7. 环境变量(Environment Variables)
    8. 配置选项(Configuration Options)
23. 优质集成实践
24. 片状测试
25. Pytest导入机制及sys.path/PYTHONPATH
26. 配置选项
27. 示例及自定义技巧
28. Bash自动补全设置

API参考-Hooks

• 钩子(Hooks)
  • 引导钩子
  • 初始化Hook方法
  • 测试运行Hook方法
  • 收藏Hook方法
  • 报告Hook方法
  • 调试/交互Hook方法

钩子(Hooks)

教程：编写插件。
引用可由conftest.py文件和插件实现的所有Hook方法。

引导Hook方法

引导Hook方法要求尽早注册插件（内部和setuptools插件）。

pytest_load_initial_conftests（early_config，parser，*args *）[来源]

在命令行选项解析之前实现初始conftest文件的加载。
注意
不会为conftest.py文件调用此Hook方法，仅适用于setuptools插件。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• early_config（_pytest.config.Config） - pytest配置对象
• args（list* [ [str](https://docs.python.org/3/library/stdtypes.html#str "（在Python v3.7中）") ]*） - 在命令行上传递的参数列表
• 解析器（_pytest.config.Parser） - 添加命令行选项
  |

pytest_cmdline_preparse（config，*args *）[来源]

（不推荐）在选项解析之前修改命令行参数。
此钩子被认为已弃用，将在未来的pytest版本中删除。考虑pytest_load_initial_conftests()改用。
注意
不会为conftest.py文件调用此Hook方法，仅适用于setuptools插件。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• config（_pytest.config.Config） - pytest配置对象
• args（list* [ [str](https://docs.python.org/3/library/stdtypes.html#str "（在Python v3.7中）") ]*） - 在命令行上传递的参数列表
  |

pytest_cmdline_parse（pluginmanager，*args *）[来源]

返回初始化的配置对象，解析指定的args。
首先停止非结果，请参见firstresult：首先停止非结果
注意
plugins当使用pytest.main执行进程内测试运行时，只会为传递给arg的插件类调用此挂接。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• pluginmanager（_pytest.config.PytestPluginManager） - pytest插件管理器
• args（list* [ [str](https://docs.python.org/3/library/stdtypes.html#str "（在Python v3.7中）") ]*） - 在命令行上传递的参数列表
  |

pytest_cmdline_main（*config *）[来源]

要求执行主命令行动作。默认实现将调用configure hooks和runtest_mainloop。
注意
不会为conftest.py文件调用此Hook方法，仅适用于setuptools插件。
首先停止非结果，请参见firstresult：首先停止非结果
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | config（_pytest.config.Config） - pytest配置对象 |

初始化Hook方法

初始化Hook方法调用插件和conftest.py文件。

pytest_addoption（解析器）[来源]

注册argparse-style选项和ini-style配置值，在测试运行开始时调用一次。
注意
conftest.py 由于pytest 在启动期间发现插件的方式，此函数应仅在位于测试根目录的插件或文件中 实现。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | 解析器（_pytest.config.Parser） - 要添加命令行选项，请调用parser.addoption(...)。添加ini文件值调用parser.addini(...)。 |
以后可以config分别通过对象访问选项 ：

• config.getoption(name) 检索命令行选项的值。
• config.getini(name) 检索从ini样式文件中读取的值。
  配置对象通过.config 属性在许多内部对象上传递，或者可以作为pytestconfig夹具检索。
  注意
  这个钩子与之不相容hookwrapper=True。

pytest_addhooks（*pluginmanager *）[来源]

在插件注册时调用，允许通过调用添加新的Hook方法 。pluginmanager.add_hookspecs(module_or_class, prefix)
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | pluginmanager（_pytest.config.PytestPluginManager） - pytest插件管理器 |
注意
这个钩子与之不相容hookwrapper=True。

pytest_configure（*config *）[来源]

允许插件和conftest文件执行初始配置。
在解析了命令行选项后，为每个插件和初始conftest文件调用此Hook方法。
之后，在导入钩子时会调用其他conftest文件。
注意
这个钩子与之不相容hookwrapper=True。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | config（_pytest.config.Config） - pytest配置对象 |

pytest_unconfigure（*config *）[来源]

在退出测试过程之前调用。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | config（_pytest.config.Config） - pytest配置对象 |

pytest_sessionstart（会话）[来源]

在Session创建对象之后以及执行收集和进入运行测试循环之前调用。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | session（_pytest.main.Session） - pytest会话对象 |

pytest_sessionfinish（session，*exitstatus *）[来源]

在整个测试运行完成之后调用，在将退出状态返回到系统之前。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• session（_pytest.main.Session） - pytest会话对象
• exitstatus（int） - pytest将返回系统的状态
  |

pytest_plugin_registered（插件，经理）[来源]

一个新的pytest插件已注册。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• 插件 - 插件模块或实例
• manager（_pytest.config.PytestPluginManager） - pytest插件管理器
  |
  注意
  这个钩子与之不相容hookwrapper=True。

测试运行Hook方法

所有与runtest相关的钩子都会收到一个pytest.Item对象。

pytest_runtestloop（会话）[来源]

要求执行主运行测试循环（收集完成后）。
首先停止非结果，请参见firstresult：首先停止非结果
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | session（_pytest.main.Session） - pytest会话对象 |

pytest_runtest_protocol（item，*nextitem *）[来源]

为给定的测试项实现runtest_setup / call / teardown协议，包括捕获异常和调用报告Hook方法。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• item - 为其执行运行测试协议的测试项目。
• nextitem - 预定下一个测试项目（如果这是我朋友的结束，则为无）。这个论点被传递给了 pytest_runtest_teardown()。
  |
  | 返回布尔值： |
  如果不应调用其他钩子实现，则为True。
  |
  首先停止非结果，请参见firstresult：首先停止非结果

pytest_runtest_logstart（nodeid，*location *）[来源]

发出运行单个测试项目的信号。
之前 会调用此Hook方法pytest_runtest_setup()，pytest_runtest_call()并pytest_runtest_teardown()Hook方法。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• nodeid（str） - 项目的完整ID
• 位置 - 三倍(filename, linenum, testname)
  |

pytest_runtest_logfinish（nodeid，*location *）[来源]

发出运行单个测试项目的完整信号。
这个钩子将在之后 调用pytest_runtest_setup()，pytest_runtest_call()并pytest_runtest_teardown()Hook方法。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• nodeid（str） - 项目的完整ID
• 位置 - 三倍(filename, linenum, testname)

pytest_runtest_setup（项目）[来源]

以前叫过pytest_runtest_call(item)。

pytest_runtest_call（项目）[来源]

叫做执行测试item。

pytest_runtest_teardown（item，*nextitem *）[来源]

叫之后pytest_runtest_call。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | nextitem - 计划下一个测试项目（如果没有安排其他测试项目，则为None）。这个参数可以用来执行精确的拆卸，即调用足够的终结器，以便nextitem只需要调用setup-functions。 |

pytest_runtest_makereport（项目，电话）[来源]

返回_pytest.runner.TestReport给定pytest.Item和 的对象_pytest.runner.CallInfo。
首先停止非结果，请参见firstresult：首先停止非结果

为了更深入地理解，你可以查看这些钩子的默认实现，_pytest.runner也可能 与其_pytest.pdb进行交互_pytest.capture以及其输入/输出捕获，以便在发生测试失败时立即进入交互式调试。
在_pytest.terminal具体报告使用报告Hook方法，打印有关测试运行的信息。

pytest_pyfunc_call（*pyfuncitem *）[来源]

调用底层测试功能。
首先停止非结果，请参见firstresult：首先停止非结果

集合Hook方法

pytest 调用以下钩子来收集文件和目录：

pytest_collection（会话）[来源]

执行给定会话的收集协议。
首先停止非结果，请参见firstresult：首先停止非结果。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | session（_pytest.main.Session） - pytest会话对象 |

pytest_ignore_collect（路径，配置）[来源]

返回True以防止考虑此收集路径。在调用更具体的钩子之前，会查询所有文件和目录的钩子。
首先停止非结果，请参见firstresult：首先停止非结果
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• path（str） - 要分析的路径
• config（_pytest.config.Config） - pytest配置对象
  |

pytest_collect_directory（路径，父母）[来源]

在遍历目录以获取集合文件之前调用。
首先停止非结果，请参见firstresult：首先停止非结果
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | path（str） - 要分析的路径 |

pytest_collect_file（路径，父母）[来源]

返回集合给定路径的节点或无。任何新节点都需要将指定parent的父节点作为父节点。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | path（str） - 要收集的路径 |

pytest_pycollect_makemodule（路径，父母）[来源]

返回给定路径的Module收集器或None。将为每个匹配的测试模块路径调用此Hook方法。如果要为不匹配的文件创建测试模块作为测试模块，则需要使用pytest_collect_fileHook方法。
首先停止非结果，请参见firstresult：首先停止非结果

要影响Python模块中的对象集合，可以使用以下钩子：

pytest_pycollect_makeitem（收藏家，名字，*obj *）[来源]

返回模块中python对象的自定义项/收集器，或者无。
首先停止非结果，请参见firstresult：首先停止非结果

pytest_generate_tests（*metafunc *）[来源]

生成（多个）参数化调用到测试函数。

pytest_make_parametrize_id（config，val，*argname *）[来源]

返回val@ pytest.mark.parametrize调用将使用的给定的用户友好字符串表示形式。如果钩子不知道，则返回None val。argname如果需要，参数名称可用。
首先停止非结果，请参见firstresult：首先停止非结果
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• config（_pytest.config.Config） - pytest配置对象
• val - 参数化值
• argname（str） - pytest生成的自动参数名称

收集完成后，你可以修改项目的顺序，删除或以其他方式修改测试项目：

pytest_collection_modifyitems（会话，配置，项目）[来源]

在执行收集后调用，可以就地过滤或重新排序项目。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• session（_pytest.main.Session） - pytest会话对象
• config（_pytest.config.Config） - pytest配置对象
• items（List [ [_pytest.nodes.Item](https://docs.pytest.org/en/latest/reference.html#_pytest.nodes.Item "_pytest.nodes.Item") ]） - 项目对象列表
  |

pytest_collection_finish（会话）[来源]

在执行和修改集合后调用。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | session（_pytest.main.Session） - pytest会话对象 |

报告Hook方法

与会话相关的报告Hook方法：

pytest_collectstart（收藏家）[来源]

Collector开始收集。

pytest_make_collect_report（收藏家）[来源]

执行collector.collect()并返回CollectReport。
首先停止非结果，请参见firstresult：首先停止非结果

pytest_itemcollected（项目）[来源]

我们刚收集了一个测试项目。

pytest_collectreport（报告）[来源]

Collector完成收集。

pytest_deselected（项目）[来源]

要求通过关键字取消选择的测试项目。

pytest_report_header（config，*startdir *）[来源]

返回一个字符串或字符串列表，以显示为终端报告的标题信息。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• config（_pytest.config.Config） - pytest配置对象
• startdir - 带起始目录的py.path对象
  |
  注意
  conftest.py 由于pytest 在启动期间发现插件的方式，此函数应仅在位于测试根目录的插件或文件中 实现。

pytest_report_collectionfinish（config，startdir，*items *）[来源]

版本3.2中的新功能。
返回集合成功完成后要显示的字符串或字符串列表。
此字符串将显示在标准的“收集的X项目”消息之后。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• config（_pytest.config.Config） - pytest配置对象
• startdir - 带起始目录的py.path对象
• items - 将要执行的pytest项列表; 此列表不应修改。
  |

pytest_report_teststatus（报告，配置）[来源]

返回结果类别，简短和冗长的报告单词。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | config（_pytest.config.Config） - pytest配置对象 |
首先停止非结果，请参见firstresult：首先停止非结果

pytest_terminal_summary（terminalreporter，exitstatus，*config *）[来源]

在终端摘要报告中添加一个部分。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• terminalreporter（_pytest.terminal.TerminalReporter） - 内部终端报告对象
• exitstatus（int） - 将报告回操作系统的退出状态
• config（_pytest.config.Config） - pytest配置对象
  |
  新的4.2版：该config参数。

pytest_fixture_setup（fixturedef，*request *）[来源]

执行夹具设置执行。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 返回： | 调用fixture函数的返回值 |
首先停止非结果，请参见firstresult：首先停止非结果
注意
如果fixture函数返回None，则将根据firstresult的行为继续调用此钩子函数的其他实现：首先停止非None结果选项。

pytest_fixture_post_finalizer（fixturedef，*request *）[来源]

在夹具拆卸后调用，但在清除缓存之前，fixturedef.cached_result仍然可以访问夹具结果缓存。

pytest_warning_captured（warning_message，when，*item *）[来源]

处理内部pytest warnings插件捕获的警告。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• warning_message（warnings.WarningMessage） - 捕获的警告。这与生成的对象相同warnings.catch_warnings()，并且包含与参数相同的属性warnings.showwarning()。
• 什么时候（str） -
  指示何时捕获警告。可能的值：
  • "config"：在pytest配置/初始化阶段。
  • "collect"：在测试收集期间。
  • "runtest"：在测试执行期间。
• item（pytest.Item | None） -
  DEPRECATED：此参数与 以后版本不兼容pytest-xdist，并且将始终None在以后的版本中接收。
  正在执行的项目，如果when是"runtest"，否则None。
  |

这是报告测试执行的中心钩子：

pytest_runtest_logreport（报告）[来源]

处理与执行测试的相应阶段有关的测试设置/调用/拆除报告。

你还可以使用此Hook方法来自定义某些类型的断言表示：

pytest_assertrepr_compare（config，op，left，*right *）[来源]

返回失败的断言表达式中的比较解释。
如果没有自定义说明，则返回None，否则返回字符串列表。该字符串将通过新行被加入，但任何换行符 在字符串将被转义。请注意，除第一行外的所有行都将略微缩进，目的是将第一行作为摘要。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： | config（_pytest.config.Config） - pytest配置对象 |

调试/交互Hook方法

很少有钩子可用于特殊报告或与异常交互：

pytest_internalerror（excrepr，*excinfo *）[来源]

要求内部错误。

pytest_keyboard_interrupt（*excinfo *）[来源]

要求键盘中断。

pytest_exception_interact（节点，呼叫，报告）[来源]

在引发异常时调用，可以交互式处理。
只有在引发的异常不是内部异常时才会调用此钩子skip.Exception。

pytest_enter_pdb（config，*pdb *）[来源]

调用pdb.set_trace（）时，插件可以使用插件在python调试器进入交互模式之前采取特殊操作。
<colgroup><col class="field-name" style="hyphens: manual;"><col class="field-body"></colgroup>
| 参数： |

• config（_pytest.config.Config） - pytest配置对象
• pdb（pdb.Pdb） - Pdb实例