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外掛。

• 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()

• 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：首先停止非結果

• 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：首先停止非結果

| 引數： |config（_pytest.config.Config） - pytest配置物件 |

初始化Hook方法

初始化Hook方法呼叫外掛和conftest.py檔案。

pytest_addoption（解析器）[來源]

註冊argparse-style選項和ini-style配置值，在測試執行開始時呼叫一次。
注意
conftest.py由於pytest 在啟動期間發現外掛的方式，此函式應僅在位於測試根目錄的外掛或檔案中 實現。

| 引數： |解析器（_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)

| 引數： |pluginmanager（_pytest.config.PytestPluginManager） - pytest外掛管理器 |
注意
這個鉤子與之不相容hookwrapper=True。

pytest_configure（*config *）[來源]

允許外掛和conftest檔案執行初始配置。
在解析了命令列選項後，為每個外掛和初始conftest檔案呼叫此Hook方法。
之後，在匯入鉤子時會呼叫其他conftest檔案。
注意
這個鉤子與之不相容hookwrapper=True。

| 引數： |config（_pytest.config.Config） - pytest配置物件 |

pytest_unconfigure（*config *）[來源]

在退出測試過程之前呼叫。

| 引數： |config（_pytest.config.Config） - pytest配置物件 |

pytest_sessionstart（會話）[來源]

在Session建立物件之後以及執行收集和進入執行測試迴圈之前呼叫。

| 引數： |session（_pytest.main.Session） - pytest會話物件 |

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

在整個測試執行完成之後呼叫，在將退出狀態返回到系統之前。

| 引數： |

• session（_pytest.main.Session） - pytest會話物件
• exitstatus（int） - pytest將返回系統的狀態
  |

pytest_plugin_registered（外掛，經理）[來源]

一個新的pytest外掛已註冊。

| 引數： |

• 外掛- 外掛模組或例項
• manager（_pytest.config.PytestPluginManager） - pytest外掛管理器
  |
  注意
  這個鉤子與之不相容hookwrapper=True。

測試執行Hook方法

所有與runtest相關的鉤子都會收到一個pytest.Item物件。

pytest_runtestloop（會話）[來源]

要求執行主執行測試迴圈（收集完成後）。
首先停止非結果，請參見firstresult：首先停止非結果

| 引數： |session（_pytest.main.Session） - pytest會話物件 |

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

為給定的測試項實現runtest_setup / call / teardown協議，包括捕獲異常和呼叫報告Hook方法。

| 引數： |

• item- 為其執行執行測試協議的測試專案。
• nextitem- 預定下一個測試專案（如果這是我朋友的結束，則為無）。這個論點被傳遞給了pytest_runtest_teardown()。
  |
  | 返回布林值： |
  如果不應呼叫其他鉤子實現，則為True。
  |
  首先停止非結果，請參見firstresult：首先停止非結果

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

發出執行單個測試專案的訊號。
之前會呼叫此Hook方法pytest_runtest_setup()，pytest_runtest_call()並pytest_runtest_teardown()Hook方法。

| 引數： |

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

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

發出執行單個測試專案的完整訊號。
這個鉤子將在之後呼叫pytest_runtest_setup()，pytest_runtest_call()並pytest_runtest_teardown()Hook方法。

| 引數： |

• 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。

| 引數： |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：首先停止非結果。

| 引數： |session（_pytest.main.Session） - pytest會話物件 |

pytest_ignore_collect（路徑，配置）[來源]

返回True以防止考慮此收集路徑。在呼叫更具體的鉤子之前，會查詢所有檔案和目錄的鉤子。
首先停止非結果，請參見firstresult：首先停止非結果

| 引數： |

• path（str） - 要分析的路徑
• config（_pytest.config.Config） - pytest配置物件
  |

pytest_collect_directory（路徑，父母）[來源]

在遍歷目錄以獲取集合檔案之前呼叫。
首先停止非結果，請參見firstresult：首先停止非結果

| 引數： |path（str） - 要分析的路徑 |

pytest_collect_file（路徑，父母）[來源]

返回集合給定路徑的節點或無。任何新節點都需要將指定parent的父節點作為父節點。

| 引數： |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呼叫將使用的給定的使用者友好字串表示形式。如果鉤子不知道，則返回Noneval。argname如果需要，引數名稱可用。
首先停止非結果，請參見firstresult：首先停止非結果

| 引數： |

• config（_pytest.config.Config） - pytest配置物件
• val- 引數化值
• argname（str） - pytest生成的自動引數名稱

收集完成後，你可以修改專案的順序，刪除或以其他方式修改測試專案：

pytest_collection_modifyitems（會話，配置，專案）[來源]

在執行收集後呼叫，可以就地過濾或重新排序專案。

| 引數： |

• 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（會話）[來源]

在執行和修改集合後呼叫。

| 引數： |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 *）[來源]

返回一個字串或字串列表，以顯示為終端報告的標題資訊。

| 引數： |

• config（_pytest.config.Config） - pytest配置物件
• startdir- 帶起始目錄的py.path物件
  |
  注意
  conftest.py由於pytest 在啟動期間發現外掛的方式，此函式應僅在位於測試根目錄的外掛或檔案中 實現。

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

版本3.2中的新功能。
返回集合成功完成後要顯示的字串或字串列表。
此字串將顯示在標準的“收集的X專案”訊息之後。

| 引數： |

• config（_pytest.config.Config） - pytest配置物件
• startdir- 帶起始目錄的py.path物件
• items- 將要執行的pytest項列表; 此列表不應修改。
  |

pytest_report_teststatus（報告，配置）[來源]

返回結果類別，簡短和冗長的報告單詞。

| 引數： |config（_pytest.config.Config） - pytest配置物件 |
首先停止非結果，請參見firstresult：首先停止非結果

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

在終端摘要報告中新增一個部分。

| 引數： |

• terminalreporter（_pytest.terminal.TerminalReporter） - 內部終端報告物件
• exitstatus（int） - 將報告回作業系統的退出狀態
• config（_pytest.config.Config） - pytest配置物件
  |
  新的4.2版：該config引數。

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

執行夾具設定執行。

| 返回： | 呼叫fixture函式的返回值 |
首先停止非結果，請參見firstresult：首先停止非結果
注意
如果fixture函式返回None，則將根據firstresult的行為繼續呼叫此鉤子函式的其他實現：首先停止非None結果選項。

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

在夾具拆卸後呼叫，但在清除快取之前，fixturedef.cached_result仍然可以訪問夾具結果快取。

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

處理內部pytest warnings外掛捕獲的警告。

| 引數： |

• 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，否則返回字串列表。該字串將通過新行被加入，但任何換行符在字串將被轉義。請注意，除第一行外的所有行都將略微縮排，目的是將第一行作為摘要。

| 引數： |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偵錯程式進入互動模式之前採取特殊操作。

| 引數： |

• config（_pytest.config.Config） - pytest配置物件
• pdb（pdb.Pdb） - Pdb例項