：pytest、快照測試與 FastAPI 路由鑒權(quán) Mock 指南)
AutoGPT Platform 后端測試實戰(zhàn)pytest、快照測試與 FastAPI 路由鑒權(quán) Mock 指南【免費(fèi)下載鏈接】AutoGPTAutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.項目地址: https://gitcode.com/GitHub_Trending/au/AutoGPT本文基于 AutoGPT Platform 后端官方測試指南 TESTING.md 整理完整覆蓋其測試運(yùn)行方式、pytest-snapshot 快照測試原理、FastAPI 路由測試寫法與 JWT 鑒權(quán) Mock 策略并結(jié)合當(dāng)前倉庫中的 pyproject.toml、run_tests.py、兩層 conftest.py 與真實快照文件把每一條命令、每一個 fixture 落實到可驗證的源碼證據(jù)上。讀完本文你可以直接在本地跑起 Platform 后端完整測試套件、理解其獨(dú)立測試數(shù)據(jù)庫的隔離機(jī)制并掌握為新增 API 路由編寫帶鑒權(quán) Mock 與快照斷言的測試的完整套路。測試技術(shù)棧與依賴配置官方指南明確 Platform 后端以pytest為核心測試框架配套四個關(guān)鍵庫pytest— 測試框架本體pytest-asyncio— 異步測試支持pytest-mock— Mock 支持提供mockerfixturepytest-snapshot— 針對 API 響應(yīng)的快照測試。這些依賴在 pyproject.toml 中可以直接核對pytest ^8.4.1、pytest-asyncio ^1.1.0、pytest-snapshot ^0.9.0聲明在[tool.poetry.dependencies]中而pytest-mock ^3.15.1、pytest-cov ^7.1.0位于 dev 依賴組[tool.poetry.group.dev.dependencies]。此外倉庫還引入了poethepoet作為任務(wù)運(yùn)行器并通過[tool.poetry.scripts]把test命令注冊為指向scripts.run_tests:test的可執(zhí)行入口——這正是下一節(jié)poetry run test背后的實現(xiàn)。pytest 全局配置pyproject.toml 的[tool.pytest.ini_options]中還包含若干對測試行為有實質(zhì)影響的全局配置值得在寫測試前了解[tool.pytest.ini_options] asyncio_mode auto asyncio_default_fixture_loop_scope session # 禁用 syrupy 插件避免與 pytest-snapshot 沖突 # 兩者都提供 --snapshot-update 參數(shù)會引發(fā) ArgumentError addopts -p no:syrupy # 單個測試超過 5 分鐘時 dump 所有線程棧不中斷運(yùn)行讓掛起自我暴露 faulthandler_timeout 300 markers [ supplementary: tests kept for coverage but superseded by integration tests, integration: end-to-end tests that require a live database (skipped in CI), slow: tests that take more than a few seconds (e.g. spin up an isolated docker stack), ]幾個要點asyncio_mode auto意味著async def測試無需手動加pytest.mark.asyncio即可被識別但官方指南仍建議直接測試異步函數(shù)時顯式使用該標(biāo)記-p no:syrupy是硬性要求syrupy 與 pytest-snapshot 都注冊了--snapshot-update參數(shù)共存會直接導(dǎo)致 pytest 啟動失敗faulthandler_timeout 300是一道防掛起保險配置注釋中記錄了真實案例——某單元測試觸發(fā)了一個永不返回的 DatabaseManager 套接字讀最終靠線程棧 dump 定位三個 markersupplementary/integration/slow用于區(qū)分測試性質(zhì)其中integration標(biāo)記的測試需要真實數(shù)據(jù)庫在 CI 中會被跳過。運(yùn)行測試命令與底層流程常用命令官方指南給出的日常命令如下均在autogpt_platform/backend目錄下執(zhí)行# 運(yùn)行全部測試 poetry run test # 運(yùn)行指定測試文件 poetry run pytest path/to/test_file.py # 詳細(xì)輸出 poetry run pytest -v # 帶覆蓋率 poetry run pytest --covbackendpoetry run test到底做了什么poetry run test并非直接調(diào)用 pytest而是執(zhí)行 scripts/run_tests.py 中的test()函數(shù)。閱讀源碼可以看到完整的編排流程拉起測試基礎(chǔ)設(shè)施執(zhí)行docker compose -f docker-compose.test.yaml --env-file ../.env up -d。docker-compose.test.yaml 定義了四類服務(wù)dbPostgreSQL復(fù)用 db/docker 中 Supabase 的 db 定義并直接暴露 5432 端口、redis、rabbitmq和clamav為需要消息隊列與文件掃描的測試提供本地依賴。等待數(shù)據(jù)庫就緒wait_for_postgres()循環(huán)調(diào)用容器內(nèi)pg_isready最多重試 5 次、每次間隔 5 秒。強(qiáng)制切換到獨(dú)立測試庫關(guān)鍵隔離設(shè)計源碼注釋明確指出這是load-bearing步驟——測試庫容器與開發(fā)用 Supabase 數(shù)據(jù)庫共享數(shù)據(jù)目錄而 Supabase 的默認(rèn)search_path是$user, platform, public如果直接用無 schema 限定連接串prisma migrate reset --force會命中線上的platformschema。因此腳本會先執(zhí)行CREATE DATABASE agpt_test再顯式設(shè)置環(huán)境變量test_db_name agpt_test test_env[DATABASE_URL] fpostgresql://{db_user}:{db_pass}localhost:{db_port}/{test_db_name} test_env[DIRECT_URL] test_env[DATABASE_URL]這樣prisma migrate reset --force --skip-seed與后續(xù)prisma migrate deploy都只作用于獨(dú)立的agpt_test數(shù)據(jù)庫開發(fā)數(shù)據(jù)不受影響。執(zhí)行測試subprocess.run([pytest] sys.argv[1:], envtest_env)—— 注意sys.argv[1:]會把額外參數(shù)透傳給 pytest因此poetry run test path/to/test.py這類用法是可行的。清理無論測試成敗最后執(zhí)行docker compose -f docker-compose.test.yaml down拆掉容器并以 pytest 的返回碼作為整個命令的退出碼。手動等價流程如果想理解每一步也可以手動復(fù)現(xiàn)cd autogpt_platform/backend docker compose -f docker-compose.test.yaml --env-file ../.env up -d # 創(chuàng)建獨(dú)立測試庫 docker compose -f docker-compose.test.yaml exec -T db psql -U postgres -d postgres \ -c CREATE DATABASE agpt_test # 設(shè)置 DATABASE_URL / DIRECT_URL 指向 agpt_test 后執(zhí)行遷移 prisma migrate reset --force --skip-seed prisma migrate deploy # 運(yùn)行測試 pytest docker compose -f docker-compose.test.yaml down快照測試原理、更新與最佳實踐工作原理官方指南對快照測試的描述是首次運(yùn)行時在snapshots/目錄創(chuàng)建快照文件后續(xù)運(yùn)行將輸出與已保存快照比對一旦檢測到差異測試即失敗。倉庫中真實存在這一層結(jié)構(gòu)——autogpt_platform/backend/snapshots/目錄提交了 80 余個快照文件如agts_search、grph_struct、otto_ok、admin_add_credits_success等它們隨代碼一起進(jìn)入版本庫是 CI 比對的基礎(chǔ)。例如 snapshots/otto_ok 的內(nèi)容就是 Otto 端點一次成功響應(yīng)的規(guī)范化 JSON{ answer: This is Ottos response to your query., documents: [ { relevance_score: 0.95, url: https://example.com/doc1 }, { relevance_score: 0.87, url: https://example.com/doc2 } ], success: true }從結(jié)構(gòu)看該文件正是json.dumps(..., indent2, sort_keysTrue)的產(chǎn)物鍵已排序、縮進(jìn)為 2diff 可讀性好。創(chuàng)建與更新快照首次編寫測試、或預(yù)期輸出發(fā)生合法變化時使用--snapshot-update參數(shù)重建快照poetry run pytest path/to/test.py --snapshot-update官方指南在此處有明確警示提交前務(wù)必審查快照變更用git diff確認(rèn)變化是預(yù)期的——快照文件是黃金基線誤更新會掩蓋真實回歸。快照測試示例指南給出的標(biāo)準(zhǔn)寫法如下import json from pytest_snapshot.plugin import Snapshot def test_api_endpoint(snapshot: Snapshot): response client.get(/api/endpoint) # Snapshot the response snapshot.snapshot_dir snapshots snapshot.assert_match( json.dumps(response.json(), indent2, sort_keysTrue), endpoint_response )快照最佳實踐官方指南歸納了四條規(guī)則每一條都對應(yīng)快照穩(wěn)定性問題使用描述性名稱user_list_response而非response1排序 JSON 鍵sort_keysTrue保證字典順序不影響比對結(jié)果格式化 JSONindent2讓 diff 更易讀剔除動態(tài)數(shù)據(jù)移除時間戳、ID 等每次運(yùn)行都會變化的字段。針對第 4 點指南給出了剔除動態(tài)字段的完整示例response_data response.json() # Remove dynamic fields for snapshot response_data.pop(created_at, None) response_data.pop(id, None) snapshot.snapshot_dir snapshots snapshot.assert_match( json.dumps(response_data, indent2, sort_keysTrue), static_response_data )為 API 路由編寫測試基本結(jié)構(gòu)Platform 后端的 API 路由測試遵循獨(dú)立 FastAPI 實例 TestClient的輕量模式只掛載被測 router不啟動完整應(yīng)用。指南中的標(biāo)準(zhǔn)骨架import json import fastapi import fastapi.testclient import pytest from pytest_snapshot.plugin import Snapshot from backend.api.features.myroute import router app fastapi.FastAPI() app.include_router(router) client fastapi.testclient.TestClient(app) def test_endpoint_success(snapshot: Snapshot): response client.get(/endpoint) assert response.status_code 200 # Test specific fields data response.json() assert data[status] success # Snapshot the full response snapshot.snapshot_dir snapshots snapshot.assert_match( json.dumps(data, indent2, sort_keysTrue), endpoint_success_response )這種模式在真實測試中大量使用。例如 backend/api/features/home/routes_test.py 就是標(biāo)準(zhǔn)寫法模塊頂部app fastapi.FastAPI(); app.include_router(router); client fastapi.testclient.TestClient(app)測試函數(shù)中同時使用精確斷言校驗特定字段與快照斷言校驗整體響應(yīng)形態(tài)。鑒權(quán)測試Mockget_jwt_payload這是指南中最具實戰(zhàn)價值的一節(jié)。主 API 路由的 JWT 鑒權(quán)由autogpt_libs.auth模塊提供官方推薦的做法是mock 最底層的get_jwt_payload函數(shù)——所有高層鑒權(quán)函數(shù)requires_user、requires_admin_user、get_user_id都建立在它之上mock 一處即可覆蓋全部。反之若測試并不真正消費(fèi)user_id則可以不做任何 mock測試環(huán)境下鑒權(quán)本來就是關(guān)閉的見 conftest.py 的會話級 fixture 機(jī)制。全局鑒權(quán) fixturesbackend/api/conftest.py倉庫內(nèi)實際路徑為 backend/api/conftest.py提供兩個全局鑒權(quán) fixturemock_jwt_user—— 普通用戶mock_jwt_admin—— 管理員用戶。用法是通過 FastAPI 的dependency_overrides把 mock payload 注入到被測 appimport fastapi import fastapi.testclient import pytest from backend.api.features.myroute import router app fastapi.FastAPI() app.include_router(router) client fastapi.testclient.TestClient(app) pytest.fixture(autouseTrue) def setup_app_auth(mock_jwt_user): Setup auth overrides for all tests in this module from autogpt_libs.auth.jwt_utils import get_jwt_payload app.dependency_overrides[get_jwt_payload] mock_jwt_user[get_jwt_payload] yield app.dependency_overrides.clear()管理員端點則換成mock_jwt_adminpytest.fixture(autouseTrue) def setup_app_auth(mock_jwt_admin): Setup auth overrides for admin tests from autogpt_libs.auth.jwt_utils import get_jwt_payload app.dependency_overrides[get_jwt_payload] mock_jwt_admin[get_jwt_payload] yield app.dependency_overrides.clear()結(jié)合當(dāng)前源碼可以補(bǔ)充幾個細(xì)節(jié)讓上述模式更完整fixture 的真實返回內(nèi)容。backend/api/conftest.py 中mock_jwt_user返回{sub: test_user_id, role: user, email: testexample.com}mock_jwt_admin返回role: admin、email: test-adminexample.com。需要說明的是指南中把 ID 描述為test-user-id/admin-user-id而從源碼看這些 fixture 底層依賴test_user_id/admin_user_id其真實取值是固定的 UUID定義在 backend/conftest.py 中例如test_user_id為3e53486c-cf57-477e-ba2a-cb02dc828e1a指南中的字符串可視為示意值。組織/團(tuán)隊上下文也需一并 override。當(dāng)前版本新增了RequestContext組織、團(tuán)隊、席位狀態(tài)mock fixture 同時提供get_request_context。以 home/routes_test.py 為例生產(chǎn)中的標(biāo)準(zhǔn)寫法同時覆蓋兩個依賴pytest.fixture(autouseTrue) def setup_app_auth(mock_jwt_user): from autogpt_libs.auth import get_request_context from autogpt_libs.auth.jwt_utils import get_jwt_payload app.dependency_overrides[get_jwt_payload] mock_jwt_user[get_jwt_payload] app.dependency_overrides[get_request_context] mock_jwt_user[get_request_context] yield app.dependency_overrides.clear()獨(dú)立 ID fixtures。test_user_id、admin_user_id、target_user_id用于管理員對普通用戶的操作場景均可單獨(dú)注入此外 backend/conftest.py 還提供setup_test_user/setup_admin_user異步 fixture在需要真實數(shù)據(jù)庫用戶記錄如subemailuser_metadata時使用并內(nèi)置了對Event loop is closed瞬態(tài)錯誤的重試邏輯。支付墻自動旁路。從源碼結(jié)構(gòu)看backend/api/conftest.py中還有一個autouse的_bypass_paywallfixture它把backend.copilot.rate_limit.is_user_paywalled與backend.executor.utils.is_user_paywalled都 Mock 為返回False因為測試環(huán)境沒有真實 Supabase 用戶行支撐 JWT若不旁路所有付費(fèi)墻路由會因 tier 查詢失敗而 503。專門測試付費(fèi)墻行為的用例則直接 patch_fetch_user_tier繞開該旁路。快照配置復(fù)用configured_snapshot指南提到backend/api/conftest.py還提供configured_snapshotfixture。從源碼看它只是預(yù)置了snapshot.snapshot_dir snapshots再返回原生snapshotpytest.fixture def configured_snapshot(snapshot: Snapshot) - Snapshot: Pre-configured snapshot fixture with standard settings. snapshot.snapshot_dir snapshots return snapshot使用它可省去每次手動設(shè)置snapshot_dir的樣板代碼。Mock 外部服務(wù)對于依賴第三方 API 的路由指南推薦用pytest-mock的mockerfixture 打補(bǔ)丁再對響應(yīng)做快照def test_external_api_call(mocker, snapshot): # Mock external service mock_response {external: data} mocker.patch( backend.services.external_api.call, return_valuemock_response ) response client.post(/api/process) assert response.status_code 200 snapshot.snapshot_dir snapshots snapshot.assert_match( json.dumps(response.json(), indent2, sort_keysTrue), process_with_external_response )異步外部調(diào)用則遵循指南Troubleshooting一節(jié)的建議使用AsyncMock對異步函數(shù)打補(bǔ)丁FastAPI TestClient 會自行處理事件循環(huán)路由測試用普通def即可。測試組織、隔離與最佳實踐測試組織規(guī)范官方指南的組織原則測試與代碼同置routes.py→routes_test.py當(dāng)前倉庫大量測試文件遵循該命名如backend/api/features/store/routes_test.py描述性測試名如test_create_user_with_invalid_email相關(guān)測試按需用 class 分組覆蓋維度happy path 與錯誤路徑都要測邊界情況空數(shù)據(jù)、非法格式要測鑒權(quán)與授權(quán)要測。測試隔離指南要求所有測試通過 fixture 保證隔離具體到源碼層面鑒權(quán) override 自動清理setup_app_authfixture 在yield之后調(diào)用app.dependency_overrides.clear()確保不串到下一個測試數(shù)據(jù)庫連接妥善管理根級 conftest.py 提供server會話級 fixture基于backend.util.test.SpinTestServer并有 autouse 的graph_cleanupfixture——它包裝test_create_graph記錄所有測試創(chuàng)建的 graph測試結(jié)束后逐個刪除并斷言確實被刪掉防止測試數(shù)據(jù)在agpt_test庫中累積Mock 對象自動重置mockerfixture 為函數(shù)級作用域patch 隨測試結(jié)束自動還原。自定義 fixture指南同時鼓勵把常見測試數(shù)據(jù)抽成 fixture例如pytest.fixture def sample_user(): return { email: testexample.com, name: Test User } def test_create_user(sample_user, snapshot): response client.post(/users, jsonsample_user) # ... test implementation異步測試準(zhǔn)則FastAPI TestClient 測試用普通def客戶端內(nèi)部處理異步直接測試異步函數(shù)用async defpytest.mark.asyncio由于asyncio_mode autoasync def測試開箱即跑但顯式標(biāo)記仍有助于可讀性。CI/CD 集成與按需觸發(fā)自動觸發(fā)與路徑過濾官方指南說明GitHub Actions 工作流會在 pull request 與 main 分支 push 時自動運(yùn)行測試快照測試在 CI 中依賴三個前提快照文件已提交入庫、CI 與已提交快照比對、不一致即失敗——這與倉庫中snapshots/目錄被整體納入版本管理的事實一致。指南還特別指出自動觸發(fā)是路徑過濾的只有當(dāng)變更觸及autogpt_platform/backend/**、autogpt_platform/autogpt_libs/**、工作流文件本身或 lockfile 腳本時才會觸發(fā)。只改前端/文檔的分支永遠(yuǎn)不會跑后端 CI。手動觸發(fā)完整后端 CI后端 CI 工作流指南中給出的文件名為platform-backend-ci.yml支持workflow_dispatch手動觸發(fā)可以對任意分支跑完整的 lint / type-check / test coverage 流程gh workflow run platform-backend-ci.yml --ref branch手動運(yùn)行的價值在于突破路徑過濾限制讓只改前端/文檔的分支也能驗證后端套件為一條未觸發(fā)過后端 CI 的長生命周期分支生成一份新鮮的 coverage 上報上傳至該分支 HEAD commit 的 Codecov。刷新已開 PR 的覆蓋率狀態(tài)如果目標(biāo)分支已有打開的 PR可通過傳入pr_number讓 coverage 上報掛到該 PR 上觸發(fā) Codecov 以 PR base 為參照重新評估codecov/project/platform-backend狀態(tài)gh workflow run platform-backend-ci.yml --ref pr-head-branch -f pr_numberPR#典型場景某 PR 的codecov/project/platform-backendcheck 為紅僅僅是因為該分支從未觸發(fā)過后端 CICodecov 在拿陳舊的 carried-forward 覆蓋率做比較。帶pr_number的 dispatch 會為 PR head 生成當(dāng)前覆蓋率并刷新該 check。內(nèi)部實現(xiàn)上這會把 Codecov action 的override_pr設(shè)為該 PR 號對自動事件則保持為空不影響常規(guī)的 PR/commit 自動檢測。指南還附了一條時序約束workflow_dispatch觸發(fā)器必須先存在于倉庫默認(rèn)分支master上才能被--ref使用因此pr_number/override_pr的刷新路徑要等該變更合入master后才能完整驗證——建議用一次真實 dispatch 做驗證。故障排查指南的 Troubleshooting 部分給出三類常見問題這里完整繼承并結(jié)合源碼補(bǔ)充快照不匹配Snapshot Mismatches仔細(xì)審查 diff若變化是預(yù)期的poetry run pytest --snapshot-update若非預(yù)期修復(fù)產(chǎn)生差異的代碼而不是更新快照。異步測試問題Async Test Issues異步函數(shù)測試確保使用pytest.mark.asyncioasyncio_mode auto下為雙保險Mock 異步函數(shù)時用AsyncMockFastAPI TestClient 會自動處理異步路由。另一個從配置中可得的隱性線索若某測試卡住超過 5 分鐘faulthandler_timeout 300會自動 dump 所有線程棧此時應(yīng)從棧中找誰在等一個永不返回的調(diào)用而不是盲目懷疑測試本身慢。導(dǎo)入錯誤Import Errors確認(rèn)依賴已寫入 pyproject.toml注意倉庫注釋要求新依賴按字母序插入執(zhí)行poetry install保證依賴已安裝核對 import 路徑。小結(jié)AutoGPT Platform 后端的測試體系可以概括為三層pytest全棧含異步與 mock負(fù)責(zé)框架pytest-snapshot負(fù)責(zé) API 響應(yīng)的回歸基線兩層conftest.py根級 backend/conftest.py 管數(shù)據(jù)庫與用戶 fixture、backend/api/conftest.py 管鑒權(quán)與快照 fixture負(fù)責(zé)隔離與復(fù)用?？煺諟y試為 API 響應(yīng)提供了一致性護(hù)欄與傳統(tǒng)精確斷言組合后既能快速捕獲回歸又保持了測試的可維護(hù)性。對貢獻(xiàn)者而言最實用的三條紀(jì)律是新增路由測試時同步--snapshot-update并在提交前git diff審查快照、鑒權(quán)相關(guān)測試統(tǒng)一 overrideget_jwt_payload、數(shù)據(jù)庫相關(guān)操作始終經(jīng)由poetry run test走獨(dú)立的agpt_test庫。正如指南結(jié)尾所言好的測試和好的代碼同等重要。【免費(fèi)下載鏈接】AutoGPTAutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.項目地址: https://gitcode.com/GitHub_Trending/au/AutoGPT創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 AutoGPT Platform 后端測試實戰(zhàn)：pytest、快照測試與 FastAPI 路由鑒權(quán) Mock 指南
AutoGPT Platform 后端測試實戰(zhàn)pytest、快照測試與 FastAPI 路由鑒權(quán) Mock 指南【免費(fèi)下載鏈接】AutoGPTAutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.項目地址: https://gitcode.com/GitHub_Trending/au/AutoGPT本文基于 AutoGPT Platform 后端官方測試指南 TESTING.md 整理完整覆蓋其測試運(yùn)行方式、pytest-snapshot 快照測試原理、FastAPI 路由測試寫法與 JWT 鑒權(quán) Mock 策略并結(jié)合當(dāng)前倉庫中的 pyproject.toml、run_tests.py、兩層 conftest.py 與真實快照文件把每一條命令、每一個 fixture 落實到可驗證的源碼證據(jù)上。讀完本文你可以直接在本地跑起 Platform 后端完整測試套件、理解其獨(dú)立測試數(shù)據(jù)庫的隔離機(jī)制并掌握為新增 API 路由編寫帶鑒權(quán) Mock 與快照斷言的測試的完整套路。測試技術(shù)棧與依賴配置官方指南明確 Platform 后端以pytest為核心測試框架配套四個關(guān)鍵庫pytest— 測試框架本體pytest-asyncio— 異步測試支持pytest-mock— Mock 支持提供mockerfixturepytest-snapshot— 針對 API 響應(yīng)的快照測試。這些依賴在 pyproject.toml 中可以直接核對pytest ^8.4.1、pytest-asyncio ^1.1.0、pytest-snapshot ^0.9.0聲明在[tool.poetry.dependencies]中而pytest-mock ^3.15.1、pytest-cov ^7.1.0位于 dev 依賴組[tool.poetry.group.dev.dependencies]。此外倉庫還引入了poethepoet作為任務(wù)運(yùn)行器并通過[tool.poetry.scripts]把test命令注冊為指向scripts.run_tests:test的可執(zhí)行入口——這正是下一節(jié)poetry run test背后的實現(xiàn)。pytest 全局配置pyproject.toml 的[tool.pytest.ini_options]中還包含若干對測試行為有實質(zhì)影響的全局配置值得在寫測試前了解[tool.pytest.ini_options] asyncio_mode auto asyncio_default_fixture_loop_scope session # 禁用 syrupy 插件避免與 pytest-snapshot 沖突 # 兩者都提供 --snapshot-update 參數(shù)會引發(fā) ArgumentError addopts -p no:syrupy # 單個測試超過 5 分鐘時 dump 所有線程棧不中斷運(yùn)行讓掛起自我暴露 faulthandler_timeout 300 markers [ supplementary: tests kept for coverage but superseded by integration tests, integration: end-to-end tests that require a live database (skipped in CI), slow: tests that take more than a few seconds (e.g. spin up an isolated docker stack), ]幾個要點asyncio_mode auto意味著async def測試無需手動加pytest.mark.asyncio即可被識別但官方指南仍建議直接測試異步函數(shù)時顯式使用該標(biāo)記-p no:syrupy是硬性要求syrupy 與 pytest-snapshot 都注冊了--snapshot-update參數(shù)共存會直接導(dǎo)致 pytest 啟動失敗faulthandler_timeout 300是一道防掛起保險配置注釋中記錄了真實案例——某單元測試觸發(fā)了一個永不返回的 DatabaseManager 套接字讀最終靠線程棧 dump 定位三個 markersupplementary/integration/slow用于區(qū)分測試性質(zhì)其中integration標(biāo)記的測試需要真實數(shù)據(jù)庫在 CI 中會被跳過。運(yùn)行測試命令與底層流程常用命令官方指南給出的日常命令如下均在autogpt_platform/backend目錄下執(zhí)行# 運(yùn)行全部測試 poetry run test # 運(yùn)行指定測試文件 poetry run pytest path/to/test_file.py # 詳細(xì)輸出 poetry run pytest -v # 帶覆蓋率 poetry run pytest --covbackendpoetry run test到底做了什么poetry run test并非直接調(diào)用 pytest而是執(zhí)行 scripts/run_tests.py 中的test()函數(shù)。閱讀源碼可以看到完整的編排流程拉起測試基礎(chǔ)設(shè)施執(zhí)行docker compose -f docker-compose.test.yaml --env-file ../.env up -d。docker-compose.test.yaml 定義了四類服務(wù)dbPostgreSQL復(fù)用 db/docker 中 Supabase 的 db 定義并直接暴露 5432 端口、redis、rabbitmq和clamav為需要消息隊列與文件掃描的測試提供本地依賴。等待數(shù)據(jù)庫就緒wait_for_postgres()循環(huán)調(diào)用容器內(nèi)pg_isready最多重試 5 次、每次間隔 5 秒。強(qiáng)制切換到獨(dú)立測試庫關(guān)鍵隔離設(shè)計源碼注釋明確指出這是load-bearing步驟——測試庫容器與開發(fā)用 Supabase 數(shù)據(jù)庫共享數(shù)據(jù)目錄而 Supabase 的默認(rèn)search_path是$user, platform, public如果直接用無 schema 限定連接串prisma migrate reset --force會命中線上的platformschema。因此腳本會先執(zhí)行CREATE DATABASE agpt_test再顯式設(shè)置環(huán)境變量test_db_name agpt_test test_env[DATABASE_URL] fpostgresql://{db_user}:{db_pass}localhost:{db_port}/{test_db_name} test_env[DIRECT_URL] test_env[DATABASE_URL]這樣prisma migrate reset --force --skip-seed與后續(xù)prisma migrate deploy都只作用于獨(dú)立的agpt_test數(shù)據(jù)庫開發(fā)數(shù)據(jù)不受影響。執(zhí)行測試subprocess.run([pytest] sys.argv[1:], envtest_env)—— 注意sys.argv[1:]會把額外參數(shù)透傳給 pytest因此poetry run test path/to/test.py這類用法是可行的。清理無論測試成敗最后執(zhí)行docker compose -f docker-compose.test.yaml down拆掉容器并以 pytest 的返回碼作為整個命令的退出碼。手動等價流程如果想理解每一步也可以手動復(fù)現(xiàn)cd autogpt_platform/backend docker compose -f docker-compose.test.yaml --env-file ../.env up -d # 創(chuàng)建獨(dú)立測試庫 docker compose -f docker-compose.test.yaml exec -T db psql -U postgres -d postgres \ -c CREATE DATABASE agpt_test # 設(shè)置 DATABASE_URL / DIRECT_URL 指向 agpt_test 后執(zhí)行遷移 prisma migrate reset --force --skip-seed prisma migrate deploy # 運(yùn)行測試 pytest docker compose -f docker-compose.test.yaml down快照測試原理、更新與最佳實踐工作原理官方指南對快照測試的描述是首次運(yùn)行時在snapshots/目錄創(chuàng)建快照文件后續(xù)運(yùn)行將輸出與已保存快照比對一旦檢測到差異測試即失敗。倉庫中真實存在這一層結(jié)構(gòu)——autogpt_platform/backend/snapshots/目錄提交了 80 余個快照文件如agts_search、grph_struct、otto_ok、admin_add_credits_success等它們隨代碼一起進(jìn)入版本庫是 CI 比對的基礎(chǔ)。例如 snapshots/otto_ok 的內(nèi)容就是 Otto 端點一次成功響應(yīng)的規(guī)范化 JSON{ answer: This is Ottos response to your query., documents: [ { relevance_score: 0.95, url: https://example.com/doc1 }, { relevance_score: 0.87, url: https://example.com/doc2 } ], success: true }從結(jié)構(gòu)看該文件正是json.dumps(..., indent2, sort_keysTrue)的產(chǎn)物鍵已排序、縮進(jìn)為 2diff 可讀性好。創(chuàng)建與更新快照首次編寫測試、或預(yù)期輸出發(fā)生合法變化時使用--snapshot-update參數(shù)重建快照poetry run pytest path/to/test.py --snapshot-update官方指南在此處有明確警示提交前務(wù)必審查快照變更用git diff確認(rèn)變化是預(yù)期的——快照文件是黃金基線誤更新會掩蓋真實回歸。快照測試示例指南給出的標(biāo)準(zhǔn)寫法如下import json from pytest_snapshot.plugin import Snapshot def test_api_endpoint(snapshot: Snapshot): response client.get(/api/endpoint) # Snapshot the response snapshot.snapshot_dir snapshots snapshot.assert_match( json.dumps(response.json(), indent2, sort_keysTrue), endpoint_response )快照最佳實踐官方指南歸納了四條規(guī)則每一條都對應(yīng)快照穩(wěn)定性問題使用描述性名稱user_list_response而非response1排序 JSON 鍵sort_keysTrue保證字典順序不影響比對結(jié)果格式化 JSONindent2讓 diff 更易讀剔除動態(tài)數(shù)據(jù)移除時間戳、ID 等每次運(yùn)行都會變化的字段。針對第 4 點指南給出了剔除動態(tài)字段的完整示例response_data response.json() # Remove dynamic fields for snapshot response_data.pop(created_at, None) response_data.pop(id, None) snapshot.snapshot_dir snapshots snapshot.assert_match( json.dumps(response_data, indent2, sort_keysTrue), static_response_data )為 API 路由編寫測試基本結(jié)構(gòu)Platform 后端的 API 路由測試遵循獨(dú)立 FastAPI 實例 TestClient的輕量模式只掛載被測 router不啟動完整應(yīng)用。指南中的標(biāo)準(zhǔn)骨架import json import fastapi import fastapi.testclient import pytest from pytest_snapshot.plugin import Snapshot from backend.api.features.myroute import router app fastapi.FastAPI() app.include_router(router) client fastapi.testclient.TestClient(app) def test_endpoint_success(snapshot: Snapshot): response client.get(/endpoint) assert response.status_code 200 # Test specific fields data response.json() assert data[status] success # Snapshot the full response snapshot.snapshot_dir snapshots snapshot.assert_match( json.dumps(data, indent2, sort_keysTrue), endpoint_success_response )這種模式在真實測試中大量使用。例如 backend/api/features/home/routes_test.py 就是標(biāo)準(zhǔn)寫法模塊頂部app fastapi.FastAPI(); app.include_router(router); client fastapi.testclient.TestClient(app)測試函數(shù)中同時使用精確斷言校驗特定字段與快照斷言校驗整體響應(yīng)形態(tài)。鑒權(quán)測試Mockget_jwt_payload這是指南中最具實戰(zhàn)價值的一節(jié)。主 API 路由的 JWT 鑒權(quán)由autogpt_libs.auth模塊提供官方推薦的做法是mock 最底層的get_jwt_payload函數(shù)——所有高層鑒權(quán)函數(shù)requires_user、requires_admin_user、get_user_id都建立在它之上mock 一處即可覆蓋全部。反之若測試并不真正消費(fèi)user_id則可以不做任何 mock測試環(huán)境下鑒權(quán)本來就是關(guān)閉的見 conftest.py 的會話級 fixture 機(jī)制。全局鑒權(quán) fixturesbackend/api/conftest.py倉庫內(nèi)實際路徑為 backend/api/conftest.py提供兩個全局鑒權(quán) fixturemock_jwt_user—— 普通用戶mock_jwt_admin—— 管理員用戶。用法是通過 FastAPI 的dependency_overrides把 mock payload 注入到被測 appimport fastapi import fastapi.testclient import pytest from backend.api.features.myroute import router app fastapi.FastAPI() app.include_router(router) client fastapi.testclient.TestClient(app) pytest.fixture(autouseTrue) def setup_app_auth(mock_jwt_user): Setup auth overrides for all tests in this module from autogpt_libs.auth.jwt_utils import get_jwt_payload app.dependency_overrides[get_jwt_payload] mock_jwt_user[get_jwt_payload] yield app.dependency_overrides.clear()管理員端點則換成mock_jwt_adminpytest.fixture(autouseTrue) def setup_app_auth(mock_jwt_admin): Setup auth overrides for admin tests from autogpt_libs.auth.jwt_utils import get_jwt_payload app.dependency_overrides[get_jwt_payload] mock_jwt_admin[get_jwt_payload] yield app.dependency_overrides.clear()結(jié)合當(dāng)前源碼可以補(bǔ)充幾個細(xì)節(jié)讓上述模式更完整fixture 的真實返回內(nèi)容。backend/api/conftest.py 中mock_jwt_user返回{sub: test_user_id, role: user, email: testexample.com}mock_jwt_admin返回role: admin、email: test-adminexample.com。需要說明的是指南中把 ID 描述為test-user-id/admin-user-id而從源碼看這些 fixture 底層依賴test_user_id/admin_user_id其真實取值是固定的 UUID定義在 backend/conftest.py 中例如test_user_id為3e53486c-cf57-477e-ba2a-cb02dc828e1a指南中的字符串可視為示意值。組織/團(tuán)隊上下文也需一并 override。當(dāng)前版本新增了RequestContext組織、團(tuán)隊、席位狀態(tài)mock fixture 同時提供get_request_context。以 home/routes_test.py 為例生產(chǎn)中的標(biāo)準(zhǔn)寫法同時覆蓋兩個依賴pytest.fixture(autouseTrue) def setup_app_auth(mock_jwt_user): from autogpt_libs.auth import get_request_context from autogpt_libs.auth.jwt_utils import get_jwt_payload app.dependency_overrides[get_jwt_payload] mock_jwt_user[get_jwt_payload] app.dependency_overrides[get_request_context] mock_jwt_user[get_request_context] yield app.dependency_overrides.clear()獨(dú)立 ID fixtures。test_user_id、admin_user_id、target_user_id用于管理員對普通用戶的操作場景均可單獨(dú)注入此外 backend/conftest.py 還提供setup_test_user/setup_admin_user異步 fixture在需要真實數(shù)據(jù)庫用戶記錄如subemailuser_metadata時使用并內(nèi)置了對Event loop is closed瞬態(tài)錯誤的重試邏輯。支付墻自動旁路。從源碼結(jié)構(gòu)看backend/api/conftest.py中還有一個autouse的_bypass_paywallfixture它把backend.copilot.rate_limit.is_user_paywalled與backend.executor.utils.is_user_paywalled都 Mock 為返回False因為測試環(huán)境沒有真實 Supabase 用戶行支撐 JWT若不旁路所有付費(fèi)墻路由會因 tier 查詢失敗而 503。專門測試付費(fèi)墻行為的用例則直接 patch_fetch_user_tier繞開該旁路。快照配置復(fù)用configured_snapshot指南提到backend/api/conftest.py還提供configured_snapshotfixture。從源碼看它只是預(yù)置了snapshot.snapshot_dir snapshots再返回原生snapshotpytest.fixture def configured_snapshot(snapshot: Snapshot) - Snapshot: Pre-configured snapshot fixture with standard settings. snapshot.snapshot_dir snapshots return snapshot使用它可省去每次手動設(shè)置snapshot_dir的樣板代碼。Mock 外部服務(wù)對于依賴第三方 API 的路由指南推薦用pytest-mock的mockerfixture 打補(bǔ)丁再對響應(yīng)做快照def test_external_api_call(mocker, snapshot): # Mock external service mock_response {external: data} mocker.patch( backend.services.external_api.call, return_valuemock_response ) response client.post(/api/process) assert response.status_code 200 snapshot.snapshot_dir snapshots snapshot.assert_match( json.dumps(response.json(), indent2, sort_keysTrue), process_with_external_response )異步外部調(diào)用則遵循指南Troubleshooting一節(jié)的建議使用AsyncMock對異步函數(shù)打補(bǔ)丁FastAPI TestClient 會自行處理事件循環(huán)路由測試用普通def即可。測試組織、隔離與最佳實踐測試組織規(guī)范官方指南的組織原則測試與代碼同置routes.py→routes_test.py當(dāng)前倉庫大量測試文件遵循該命名如backend/api/features/store/routes_test.py描述性測試名如test_create_user_with_invalid_email相關(guān)測試按需用 class 分組覆蓋維度happy path 與錯誤路徑都要測邊界情況空數(shù)據(jù)、非法格式要測鑒權(quán)與授權(quán)要測。測試隔離指南要求所有測試通過 fixture 保證隔離具體到源碼層面鑒權(quán) override 自動清理setup_app_authfixture 在yield之后調(diào)用app.dependency_overrides.clear()確保不串到下一個測試數(shù)據(jù)庫連接妥善管理根級 conftest.py 提供server會話級 fixture基于backend.util.test.SpinTestServer并有 autouse 的graph_cleanupfixture——它包裝test_create_graph記錄所有測試創(chuàng)建的 graph測試結(jié)束后逐個刪除并斷言確實被刪掉防止測試數(shù)據(jù)在agpt_test庫中累積Mock 對象自動重置mockerfixture 為函數(shù)級作用域patch 隨測試結(jié)束自動還原。自定義 fixture指南同時鼓勵把常見測試數(shù)據(jù)抽成 fixture例如pytest.fixture def sample_user(): return { email: testexample.com, name: Test User } def test_create_user(sample_user, snapshot): response client.post(/users, jsonsample_user) # ... test implementation異步測試準(zhǔn)則FastAPI TestClient 測試用普通def客戶端內(nèi)部處理異步直接測試異步函數(shù)用async defpytest.mark.asyncio由于asyncio_mode autoasync def測試開箱即跑但顯式標(biāo)記仍有助于可讀性。CI/CD 集成與按需觸發(fā)自動觸發(fā)與路徑過濾官方指南說明GitHub Actions 工作流會在 pull request 與 main 分支 push 時自動運(yùn)行測試快照測試在 CI 中依賴三個前提快照文件已提交入庫、CI 與已提交快照比對、不一致即失敗——這與倉庫中snapshots/目錄被整體納入版本管理的事實一致。指南還特別指出自動觸發(fā)是路徑過濾的只有當(dāng)變更觸及autogpt_platform/backend/**、autogpt_platform/autogpt_libs/**、工作流文件本身或 lockfile 腳本時才會觸發(fā)。只改前端/文檔的分支永遠(yuǎn)不會跑后端 CI。手動觸發(fā)完整后端 CI后端 CI 工作流指南中給出的文件名為platform-backend-ci.yml支持workflow_dispatch手動觸發(fā)可以對任意分支跑完整的 lint / type-check / test coverage 流程gh workflow run platform-backend-ci.yml --ref branch手動運(yùn)行的價值在于突破路徑過濾限制讓只改前端/文檔的分支也能驗證后端套件為一條未觸發(fā)過后端 CI 的長生命周期分支生成一份新鮮的 coverage 上報上傳至該分支 HEAD commit 的 Codecov。刷新已開 PR 的覆蓋率狀態(tài)如果目標(biāo)分支已有打開的 PR可通過傳入pr_number讓 coverage 上報掛到該 PR 上觸發(fā) Codecov 以 PR base 為參照重新評估codecov/project/platform-backend狀態(tài)gh workflow run platform-backend-ci.yml --ref pr-head-branch -f pr_numberPR#典型場景某 PR 的codecov/project/platform-backendcheck 為紅僅僅是因為該分支從未觸發(fā)過后端 CICodecov 在拿陳舊的 carried-forward 覆蓋率做比較。帶pr_number的 dispatch 會為 PR head 生成當(dāng)前覆蓋率并刷新該 check。內(nèi)部實現(xiàn)上這會把 Codecov action 的override_pr設(shè)為該 PR 號對自動事件則保持為空不影響常規(guī)的 PR/commit 自動檢測。指南還附了一條時序約束workflow_dispatch觸發(fā)器必須先存在于倉庫默認(rèn)分支master上才能被--ref使用因此pr_number/override_pr的刷新路徑要等該變更合入master后才能完整驗證——建議用一次真實 dispatch 做驗證。故障排查指南的 Troubleshooting 部分給出三類常見問題這里完整繼承并結(jié)合源碼補(bǔ)充快照不匹配Snapshot Mismatches仔細(xì)審查 diff若變化是預(yù)期的poetry run pytest --snapshot-update若非預(yù)期修復(fù)產(chǎn)生差異的代碼而不是更新快照。異步測試問題Async Test Issues異步函數(shù)測試確保使用pytest.mark.asyncioasyncio_mode auto下為雙保險Mock 異步函數(shù)時用AsyncMockFastAPI TestClient 會自動處理異步路由。另一個從配置中可得的隱性線索若某測試卡住超過 5 分鐘faulthandler_timeout 300會自動 dump 所有線程棧此時應(yīng)從棧中找誰在等一個永不返回的調(diào)用而不是盲目懷疑測試本身慢。導(dǎo)入錯誤Import Errors確認(rèn)依賴已寫入 pyproject.toml注意倉庫注釋要求新依賴按字母序插入執(zhí)行poetry install保證依賴已安裝核對 import 路徑。小結(jié)AutoGPT Platform 后端的測試體系可以概括為三層pytest全棧含異步與 mock負(fù)責(zé)框架pytest-snapshot負(fù)責(zé) API 響應(yīng)的回歸基線兩層conftest.py根級 backend/conftest.py 管數(shù)據(jù)庫與用戶 fixture、backend/api/conftest.py 管鑒權(quán)與快照 fixture負(fù)責(zé)隔離與復(fù)用?？煺諟y試為 API 響應(yīng)提供了一致性護(hù)欄與傳統(tǒng)精確斷言組合后既能快速捕獲回歸又保持了測試的可維護(hù)性。對貢獻(xiàn)者而言最實用的三條紀(jì)律是新增路由測試時同步--snapshot-update并在提交前git diff審查快照、鑒權(quán)相關(guān)測試統(tǒng)一 overrideget_jwt_payload、數(shù)據(jù)庫相關(guān)操作始終經(jīng)由poetry run test走獨(dú)立的agpt_test庫。正如指南結(jié)尾所言好的測試和好的代碼同等重要。【免費(fèi)下載鏈接】AutoGPTAutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.項目地址: https://gitcode.com/GitHub_Trending/au/AutoGPT創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考