鈎子(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**]) - 在命令行上傳遞的參數列表
- 解析器(_pytest.config.Parser) - 添加命令行選項
pytest_cmdline_preparse(config,args): (不推薦)在選項解析之前修改命令行參數。
此鈎子被認為已棄用,將在未來的pytest版本中刪除。考慮pytest_load_initial_conftests()改用。
注意：不會為
conftest.py文件調用此Hook方法,僅適用於setuptools插件。
參數：
- config(_pytest.config.Config) - pytest配置對象
- args(list**]) - 在命令行上傳遞的參數列表
pytest_cmdline_parse(pluginmanager,args): 返回初始化的配置對象,解析指定的args。
在第一個非空結果處停止,請參見: firstresult：在第一個非空結果處停止
注意：
plugins當使用[pytest.main為傳遞給arg的插件類調用此掛接。
參數：
- pluginmanager(_pytest.config.PytestPluginManager) - pytest插件管理器
- args(list**]) - 在命令行上傳遞的參數列表
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屬性在許多內部對象上傳遞,或者可以作為pytestconfigFixture方法檢索。
注意：這個Hook方法與
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創建對象之后以及執行收集和進入運行測試循環之前調用。
參數：
- session(_pytest.main.Session) - pytest會話對象
pytest_sessionfinish(session,exitstatus): 在整個測試運行完成之后調用,在將退出狀態返回到系統之前。
參數：
- session(_pytest.main.Session) - pytest會話對象
- exitstatus(int) - pytest將返回系統的狀態
pytest_plugin_registered(plugin,manager):一個新的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): 發出運行單個測試項目的信號。
在調用pytest_runtest_setup()Hook方法之前會調用此Hook方法。
參數：
- nodeid(str) - 項目的完整ID
- location- 三倍(filename,linenum,testname)`
pytest_runtest_logfinish(nodeid,location): 發出運行單個測試項目的完整信號。
調用pytest_runtest_setup()Hook方法之后, 調用此Hook方法。
參數：
- nodeid(str) - 項目的完整ID
- location- (filename,linenum,testname)`三者的組合
pytest_runtest_setup(item): 以前稱作pytest_runtest_call(item)。
pytest_runtest_call(item): 調用以執行測試項。
pytest_runtest_teardown(item,nextitem): 在pytest_runtest_call之后調用。
參數：
- nextitem- 計划下一個測試項目(如果沒有安排其他測試項目,則為None)。這個參數可以用來執行精確的拆卸,即調用足夠的終結器,以便nextitem只需要調用setup-functions。
pytest_runtest_makereport(item,call): 返回_pytest.runner.TestReport。
在第一個非空結果處停止,請參見: firstresult：在第一個非空結果處停止
為了更深入地理解,你可以查看這些Hook方法的默認實現,_pytest.runner也可能與其_pytest.pdb進行交互_pytest.capture以及其輸入/輸出捕獲,以便在發生測試失敗時立即進入交互式調試。
在_pytest.terminal具體報告使用報告Hook方法,打印有關測試運行的信息。
pytest_pyfunc_call(pyfuncitem): 調用底層測試函數。
在第一個非空結果處停止,請參見: firstresult：在第一個非空結果處停止
收集用例時的Hook方法
pytest調用以下Hook方法來來收集測試文件及目錄：
pytest_collection(session): 執行給定會話的收集協議。
在第一個非空結果處停止,請參見: firstresult：在第一個非空結果處停止。
參數：
- session(_pytest.main.Session) - pytest會話對象
pytest_ignore_collect(path,config): 返回True以防止考慮此收集路徑。在調用更具體的鈎子之前,會查詢所有文件和目錄的鈎子。
在第一個非空結果處停止,請參見: firstresult：在第一個非空結果處停止
參數：
- path(str) - 要分析的路徑
- config(_pytest.config.Config) - pytest配置對象
pytest_collect_directory(path,parent): 在遍歷目錄以獲取集合文件之前調用。
在第一個非空結果處停止,請參見: firstresult：在第一個非空結果處停止
參數：
- path(str) - 要分析的路徑
pytest_collect_file(path,parent): 返回集合給定路徑的節點或無。任何新節點都需要將指定parent的父節點作為父節點。
參數：
- path(str) - 要收集的路徑
pytest_pycollect_makemodule(路徑,父母): 返回給定路徑的Module收集器或None。將為每個匹配的測試模塊路徑調用此Hook方法。如果要為不匹配的文件創建測試模塊作為測試模塊,則需要使用pytest_collect_fileHook方法。
在第一個非空結果處停止,請參見: firstresult：在第一個非空結果處停止
要影響Python模塊中的對象集合,可以使用以下Hook方法：
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**]) - 項目對象列表
pytest_collection_finish(會話): 在執行和修改集合后調用。
參數：
- session(_pytest.main.Session) - pytest會話對象
生成測試結果時的Hook方法
與會話報告相關的Hook方法：
pytest_collectstart(collector): Collector開始收集。
pytest_make_collect_report(collector): 執行collector.collect()並返回CollectReport。
在第一個非空結果處停止,請參見: firstresult：在第一個非空結果處停止
pytest_itemcollected(item): 我們剛收集了一個測試項目。
pytest_collectreport(report): Collector完成收集。
pytest_deselected(items): 要求通過關鍵字取消選擇的測試項目。
pytest_report_header(config,startdir): 返回一個字符串或字符串列表,以顯示為終端報告的標題信息。
參數：
- config(_pytest.config.Config) - pytest配置對象
- startdir- 帶起始目錄的py.path對象
注意：
conftest.py由於pytest在啟動期間發現插件的方式,此函數應僅在位於測試根目錄的插件或文件中實現。
pytest_report_collectionfinish(config,startdir,items): 返回集合成功完成后要顯示的字符串或字符串列表。
此字符串將顯示在標准的“收集的X項目”消息之后。
版本3.2中的新函數。
參數：
- 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方法設置執行。
返回：調用fixture函數的返回值
在第一個非空結果處停止,請參見: firstresult：在第一個非空結果處停止
注意：如果fixture函數返回None,則將根據firstresult選項。
pytest_fixture_post_finalizer(fixturedef,request): 在Fixture方法拆卸后調用,但在清除緩存之前,fixturedef.cached_result仍然可以訪問Fixture方法結果緩存。
pytest_warning_captured(warning_message,when,item): 處理內部pytest warnings插件捕獲的警告。
參數：
- warning_message(warnings.WarningMessage) - 捕獲的警告。這與生成的對象相同
warnings.catch_warnings(),並且包含與參數相同的屬性warnings.showwarning()。 - when(str) -
指示何時捕獲警告。可能的值："config"：在pytest配置/初始化階段。"collect"：在測試收集期間。"runtest"：在測試執行期間。
- item(pytest.Item None) -
DEPRECATED：此參數與以后版本不兼容pytest-xdist,並且將始終None在以后的版本中接收。
正在執行的項目,如果when是"runtest",否則None。
這是報告測試執行的中心Hook方法：
pytest_runtest_logreport(report): 處理與執行測試的相應階段有關的測試設置/調用/拆除報告。
斷言相關Hook方法：
pytest_assertrepr_compare(config,op,left,right): 返回失敗的斷言表達式中的比較解釋。
如果沒有自定義說明,則返回None,否則返回字符串列表。該字符串將通過新行被加入,但任何換行符在字符串將被轉義。請注意,除第一行外的所有行都將略微縮進,目的是將第一行作為摘要。
參數：
- config(_pytest.config.Config) - pytest配置對象
pytest_assertion_pass(item, lineno, orig, expl): 每當斷言通過時,Hook就會調用。
在傳遞斷言后使用此Hook方法進行一些處理。 原始斷言信息在orig字符串中可用,而pytest內省斷言信息在expl字符串中可用。
必須通過enable_assertion_pass_hook ini-file選項顯式啟用此Hook方法：
[pytest]
enable_assertion_pass_hook=true
啟用此選項時,需要清除項目目錄和解釋器庫中的.pyc文件,因為斷言需要重寫。
參數：
- item(_pytest.nodes.Item) - 當前測試的pytest項目對象
- lineno(int) - 斷言語句的行號
- orig(string) - 帶有原始斷言的字符串
- expl(string) - 帶有斷言解釋的字符串
注意：這個Hook方法是實驗性的,因此它的參數甚至鈎子本身可能會在未來的任何pytest版本中被更改/刪除而不會發出警告。
如果您發現此Hook有用,請分享您的反饋,以解決問題。
調試/交互Hook方法
很少有Hook方法可用於特殊報告或與異常交互：
pytest_internalerror(excrepr,excinfo): 內部出錯時調用。
pytest_keyboard_interrupt(excinfo): 鍵盤中斷時調用。
pytest_exception_interact(節點,呼叫,報告): 在引發異常時調用,可以交互式處理。
只有在引發的異常不是內部異常, 如skip.Exception時才會調用此Hook方法。
pytest_enter_pdb(config,pdb): 調用pdb.set_trace()時,插件可以使用插件在python調試器進入交互模式之前采取特殊操作。
參數：
- config(_pytest.config.Config) - pytest配置對象
- pdb(pdb.Pdb) - Pdb實例