測試
在桌面端開啟 工作區工具 → 測試,或在行動端開啟 工具 → 測試,然後 選擇專案。測試頁面會以文字方式讀取專案中的測試檔案,並顯示找到的每個測試:資料夾、檔案、測試名稱,以及每個測試周圍的程式碼。 讀取過程絕不執行、匯入或安裝任何內容;只有在您選擇執行時,測試才會執行。
頁面頂端有一行狀態摘要和兩張卡片。單元測試 與 迴歸測試 卡片分別顯示最近一次執行中通過的測試數量、失敗或不穩定的測試、近期的執行記錄,以及 執行 按鈕。 卡片下方是一個分頁列,包含 單元測試、迴歸測試、整合與 E2E、檢查(lint、型別、建置與驗證指令碼)與 歷史記錄。
解讀狀態摘要
卡片上方的狀態摘要會根據測試的最新結果,先給出結論:
- 尚未執行任何測試時,會顯示 尚未檢查。執行一次測試,即可了解專案的現況。
- 有測試失敗時,狀態摘要會顯示失敗的數量與 查看失敗項目:失敗的測試會套用 失敗 篩選條件開啟;如果某個已修正的缺陷再度出現,對應的迴歸測試會排在最前面。
- 有不穩定的測試(先失敗、重試後才通過)時,狀態摘要會顯示其數量與 查看不穩定的測試。
- 其他情況下,狀態摘要會顯示通過的測試數量、尚未執行的測試數量,以及上次執行結束的時間。
計數包含單元測試、整合測試與端對端測試,以及檢查。迴歸測試重複使用的正是這些測試,因此不會重複計算。
在 自動執行 按鈕旁,狀態摘要還會顯示 下次自動執行 及其時間,或顯示 自動執行已關閉。如果上次自動執行未能開始,狀態摘要會說明原因。
檢視測試
每個分頁依資料夾將測試檔案分組。開啟資料夾即可檢視其中的檔案,接著選擇一個檔案:其測試會顯示在右側(在手機上則顯示於獨立畫面),失敗的測試排在最前面。 失敗的測試會顯示測試執行器回報的預期值與實際值,以及失敗那一行周圍的目前程式碼。 可依 失敗、不穩定 或 尚未執行 篩選,也可依檔案或資料夾名稱搜尋。
從未執行過的測試會顯示 尚未執行。只要有測試失敗,通過率圓環就絕不會顯示 100%。 每種狀態都同時以圖示和文字表示,而不只靠顏色。
測試頁面會自動將檔案分類:單元測試,整合測試與端對端測試(例如 e2e、integration、routes 或 api 等資料夾、Playwright 檔案與網頁情境),以及檢查。
檢查包含 lint、型別檢查、建置,以及專案中的驗證指令碼,名稱帶有後綴的指令碼也包含在內,例如 contrast:ui-check 或 tabs:guard。
如果某個資料夾的分類有誤,請開啟它的 ⋯ 選單,然後選擇 移至單元測試 或 移至整合與 E2E。
執行測試
選擇 執行單元測試、執行迴歸測試、資料夾或檔案的執行按鈕,或其詳細資料中的 執行檔案。 無需事先設定:測試頁面會根據專案中已在執行這些檔案的指令碼(保留其選項)或測試執行器的預設命令建立命令,儲存後隨即啟動。 執行報告會隨之開啟,顯示進度與 停止 按鈕。關閉應用程式不會停止執行;實例會保留結果。
一組測試執行期間,頂端的狀態摘要會顯示進度,並提供 查看進度(重新開啟正在進行的執行)與 停止(停止整組測試:仍在等待的執行不會開始)。離開測試後再回來,進度仍然在。整組結束前,執行單元測試 會顯示 正在執行…,因此再次點擊不會把同樣的測試啟動兩次。如果實例上缺少某個測試工具(例如 pytest),只有它的測試會顯示為未開始,其他測試照常執行。
已儲存的命令仍可編輯:透過 ⋯ → 編輯命令 可以變更其執行檔、引數、層級、前置條件、服務、測試資料與時限。
選擇同時執行多少個測試檔案
狀態摘要旁的 同時執行的測試檔案 設定專案中同時執行多少個測試檔案。預設的 自動 保留每個測試工具自己的設定。選擇一個數字(最多為實例的處理器數量)後,專案的每次執行(無論手動或自動)最多同時執行這麼多檔案:Node、Vitest、Jest 和 Playwright 會遵循它,其他測試工具保留自己的設定,專案的執行隨後依序進行。已經開始的執行保留開始時的數字。
測試一律以低於實例的處理器優先順序執行,因此在測試執行期間,您的對話和應用程式仍能保持回應。只有您可以變更此設定:應用程式內的助理可以依您的要求讀取或修改它,專案中的對話絕不會修改它。
依排程執行測試
選擇狀態摘要旁的 自動執行,即可讓專案的測試依自己的排程執行。每個專案有一個排程:
- 自動執行測試:開啟或關閉此排程。
- 重複:每小時、每天、工作日、每週、每月,或自訂 cron 運算式。兩次執行之間至少須間隔 15 分鐘。
- 時區:排程所依據的時區。系統會優先提供您的顯示時區;之後變更顯示時區,不會改變已儲存排程的執行時間。
- 執行內容:從 單元測試、迴歸測試、整合與 E2E 與 檢查 中至少選擇一項。
- 通知我:選擇 只在出現失敗時(預設)時,通過的執行不會發出通知,但失敗、中斷或需要審查的執行仍會通知您;選擇 每次執行後 時,每次都會通知。
- 錯過的執行:如果在排定時間實例處於關閉狀態,執行個體恢復運作後執行一次(預設)會在實例恢復後只補執行一次,不論錯過了幾次;略過錯過的執行 則會等待下一個排定時間。
自動執行就是一般的執行:它會更新卡片與狀態摘要,並連同報告顯示在 歷史記錄 中。它絕不會與上一次自動執行重疊。記憶體吃緊或正在更新時,它會等待並重試,最長兩小時,且絕不會被算作失敗。 如果自動執行無法開始,例如上一次仍在進行、專案需要檢查或沒有可執行的內容,狀態摘要會說明原因,下一個排定時間照常執行。某類測試沒有可執行的內容時,不會影響其他類別。更新或還原之後,自動執行會自行恢復;期間錯過的排定時間會依照您在 錯過的執行 中的選擇處理。
只有您可以設定排程:應用程式內的助理可以依您的要求讀取或修改排程;專案中的對話可以讀取排程,但絕不會建立或修改排程。
建立測試
選擇右上角的 新增測試:
- 使用 AI 撰寫測試:描述一項行為;AI 會提出測試,您在儲存前進行審閱。在您執行之前,不會執行任何內容。
- 保護已修正的缺陷:根據涵蓋該缺陷的測試建立迴歸測試。
- 網頁情境:在內建瀏覽器中點擊並檢查的步驟。
- 新增測試命令:專案中現有的指令碼,例如
npm test。
編輯測試
選擇一個檔案,然後選擇 在編輯器中開啟 自行修改,或選擇 使用 AI 編輯,針對此檔案與測試開啟新的對話(在您傳送之前不會傳送任何內容)。 測試失敗時,使用 AI 修正 會重現失敗、修正程式碼,然後重新執行同一測試與您的迴歸測試。 在迴歸測試中,編輯測試 可新增或移除保護它的測試。
執行迴歸測試
為集合命名、描述其保護的行為或缺陷,並選取已儲存的 套件、案例或情境的確切修訂版本。單元、整合、API 與 E2E 測試可以放在 同一個集合中,無須複製原始碼。Lint、型別檢查與建置仍是獨立的檢查。
儲存後,再明確執行該修訂版本。完整選取與部分選取會分別 標示。重疊項目只會執行一次;互相衝突的修訂版本及空的選取範圍會被 拒絕。之後編輯集合,不會改變某次執行已經擷取的成員組成。
集合仍儲存於實例的私有狀態中,尚無用於 Git 版本管理的匯出功能。專案既有的 測試檔案與明確匯出的情境原始碼,可以照常進行版本管理。
已修正的測試會成為迴歸測試
在任何專案中,只要缺陷的修正獲得證明,該缺陷就會受到保護,不需要任何人維護清單。當一個曾經失敗的測試在程式碼變更後通過時,測試頁面會把它變成迴歸測試:
- 如果一個測試在某次執行的每次嘗試中都通過,且它在專案前五次執行中的最新結果是在不同程式碼上的失敗,就視為已修正。重試後才通過,或在程式碼未變更時通過,都不算修正。
- 每個已修正的檔案會成為一個迴歸測試,以其中第一個被修正的測試命名,並使用專案指令碼的選項單獨執行該檔案。其受保護的行為會列出已修正的測試。
- 一次執行修正超過五個檔案時,不會保護任何內容:一次修正這麼多,通常代表修好的是環境,而不是缺陷。
- 已受迴歸測試保護的檔案會維持原狀。
建立時不會執行任何內容:下一次迴歸測試執行(無論是您手動啟動或自動執行)會包含它。您可以像對待其他迴歸測試一樣,編輯或刪除它。
選擇基準並比較
將一次保留的執行選為集合基準,再與另一次執行比較。 基準用於比較,並不是第三種執行原始碼模式。 成功的執行永遠不會自動取代它。
基準要求斷言非空且全數經過觀測、預期已知、 資料已隔離,並且具有完整的來源資訊。失敗的基準也能識別既有失敗; 部分結果、匯入結果、略過、不穩定或不完整的證據,都不具備基準資格。
比較會區分新迴歸、既有失敗、修復、新增、 移除、略過、未執行的案例與不穩定性,並呈現預期變更及 設定、資料、執行階段與目標的相容性。部分執行中缺少某個案例,不代表該案例已被移除。 完整的比較證據也可能包含失敗;「完整」不代表「通過」。
新增網頁情境
編輯情境的行為、目標、資料、前置條件、步驟、斷言與清理作業。 使用穩定的角色、標籤、測試 ID 或文字定位器。這不是點擊操作錄製器。
例如,可以使用以下步驟保護任務應用程式的持久化行為:
- 使用專用測試資料開啟應用程式。
- 在新增任務欄位填入一個已知標題,並選擇新增操作。
- 斷言任務可見,再將它標為完成。
- 重新載入頁面。
- 斷言同一任務仍然可見,並且保持勾選狀態。
先儲存情境,再執行它。儲存測試原始碼 是另一項需要明確觸發的 操作:選擇專案內的相對檔案路徑,以保留產生的測試原始碼。 若既有檔案的位元組內容不同,匯出會被拒絕。編輯已匯出的檔案會使 對應關係失效並阻止重播。請審閱情境修訂版本及其原始碼對應關係, 不要覆寫同時進行的工作。先前的證據仍會作為歷史紀錄保留。 測試準備不會改變一般應用程式的啟動、停止或啟用狀態。
整合瀏覽器使用暫時的 Chromium 執行環境,並封鎖 service workers。 它不能驗證離線或 PWA 行為、Safari、Firefox、Android/iOS 原生行為, 也不能驗證真實裝置的效能。目前目標與原始碼之間的對應關係可能仍不確定; 在這種情況下,瀏覽器斷言成功時會顯示 通過,這項事實寫在 詳細資料 中, 但這次執行不會成為完整驗證或符合完整基準資格的結果。 螢幕截圖是證據;視覺迴歸判定需要實際執行的斷言, 以及明確管理的視覺基準。
檢查失敗並保留證據
執行報告會先給出結果:通過、失敗、不穩定,或用一句話說明為何沒有結果, 同時顯示所執行內容的名稱、測試數量、時間長度和日期。失敗的測試排在最前, 若引擎有提供,也會顯示預期值與實際值;顯示記錄 會開啟記錄,詳細資料 彙整了備註 (執行期間變更的檔案、使用專案本身資料的測試)、已儲存的檔案、執行方式,以及與另一次執行的比較。 日誌與清單有容量上限並採用分頁;截斷會明確顯示。
命令成功、測試判定、報告完整性與來源資訊彼此獨立。 沒有可用報告的結束代碼零,只能證明命令成功。零案例、 報告、驗證或相依項目缺失、略過及中斷,都不能視為驗證通過。 一次失敗後重試成功,仍會標為 不穩定,並保留兩次嘗試。
由測試功能保留的截圖、追蹤與報告,不依賴原始瀏覽器工作階段的存續。 下載需要實例驗證;具有可執行內容的 HTML/SVG 會作為附件下載, 不會當作報告執行。證據缺失或損壞時會明確指出。 開啟原始碼時,定位的是目前的專案檔案,不保證其位元組內容仍與歷史測試一致。 後續編輯不會改寫既有結果。
停止 會等待其擁有的子程序結束,並保留無關的應用程式與 對話。清理被拒絕時,該狀態仍會顯示。關閉畫面、網路中斷或將用戶端 移至背景,都不會停止執行。重新連線後,請開啟對應的確切 報告。實例重新啟動時,無法證明連續性的執行會標為中斷, 不會自動重播命令。執行清單與通知會連回 保留的測試結果。
將缺陷轉化為受測試保護的行為
維持這條流程:重現 → 保留紅色測試 → 修正程式碼 → 相同預期轉綠 → 重播迴歸集合。重播會建立相互關聯的新紀錄。 變更、刪除或削弱斷言,不會自動表示缺陷已解決。
你可以自行撰寫測試,也可以選擇 描述行為,取得可編輯的 單元測試或情境提案。使用既有的 Harness、Model、Effort 與 帳號控制項。審閱具體的斷言、檔案、資料與前置條件; 補齊未回答的問題,再明確標記審閱就緒並儲存。 產生、儲存與執行是不同的操作。儲存已審閱的單元測試提案, 會寫入專案的測試檔案;儲存情境則保存其定義, 原始碼匯出是另一項選用操作。提案沒有已執行的判定。 原始碼變更後,儲存前可能需要重新審閱。
使用 AI 修正 會將確切的失敗,連結至重現、可檢視的修正 對話與新的驗證。尚未重現、預期變更,以及迴歸證據不完整的情況 都會明確保留。模型的解釋永遠不能取代斷言。 本機測試不需要模型;選用的 AI 功能遵循既有提供者的 用量、定價與配額控制。費用缺失代表未知,不代表零。 請參閱用量核算。這些操作不會呼叫 Ship,也不會發布任何內容。
已驗證的引擎與前置條件
下列確切版本已在 Node 22.22.2/22.23.2 下,通過 Linux 原始碼環境驗證。 相依項目必須事先存在;測試功能不會安裝或升級它們,也不據此承諾任何版本範圍的相容性。
| 引擎 | 案例與指定範圍重播 | 覆蓋率與限制 |
|---|---|---|
| Node test runner 22.22.2 / 22.23.2 | 結構化案例、掛鉤、skipped/todo;直接使用目前的 Node 執行檔。不支援精確的單案例重跑或重試歷史。 | 明確顯示量測範圍的原生行、分支、函式覆蓋率;覆蓋率中繼資料最多 128 個檔案、64 KiB。 |
| Vitest 4.1.10 | 直接使用進入點;在受監督的收集後,精確選取已保留案例;嘗試紀錄會保留重試。 | 覆蓋率與預期失敗所造成的結果反轉,不在已驗證能力之內。生命週期包裝器,以及無法保留證據外掛程式的設定,會被拒絕。 |
| Jest 30.2.0 | 固定檔案中的唯一完整名稱;每條命令選取一個案例,多個案例使用數量有上限的多條命令。 | 不匯入覆蓋率。含糊的名稱、預設組態、多專案或 TypeScript 設定,以及自訂執行器會被拒絕。 |
| pytest 8.4.2 / CPython 3.10.12 | 直接使用虛擬環境中的 Python -m pytest;保留確切節點識別碼及 setup/call/teardown。 |
覆蓋率、包裝器、分散式執行與重試外掛程式尚未驗證。缺少 pytest 時不會悄悄修復。 |
| Playwright Test 1.63.0 | 使用專案已安裝的執行器;保留專案與重複執行識別碼、重試嘗試及附件。不支援精確的單案例重跑。 | 不支援覆蓋率或預期失敗的結果反轉。專案自身的瀏覽器政策與整合瀏覽器不同。 |
| 自訂命令 / JUnit | 不含案例細節的命令結果,或有上限的報告實際提供的案例。不支援精確的單案例重跑。 | 不猜測覆蓋率、計數或重試含義;不支援的 XML 方言仍為無效或不完整狀態。 |
自訂 JUnit 命令必須將本次報告寫入私有的執行報告
目錄,使用 TEST_REPORT_PATH / TEST_REPORT_DIR 或對應的明確引數
標記 {{TEST_REPORT_PATH}} / {{TEST_REPORT_DIR}}。舊的工作區報告
不能驗證新的執行。外部 XML 可透過 API/操作 tests.importJUnit
匯入,目前介面沒有匯入按鈕。
匯入的計數不能證明本機執行、目前來源資訊或基準資格。
Linux 執行已驗證。Windows 的程序所有權管理已有實作,但 Windows 原生 執行仍未驗證。目前不支援在 macOS 實例上執行; macOS 用戶端可以控制受支援的遠端實例。 Android/iOS 介面可用,不代表原生應用程式測試已通過驗證。 原始碼、確切的承載內容、私有安裝候選、實際提供服務的用戶端、公開發行版本 與實體裝置的證據彼此獨立,不能互相替代。
對話工具
一般且已獲授權的專案對話,可使用五個 MCP 工具與對應的 CLI
命令:aircode_tests_catalog / catalog、aircode_tests_describe / describe、
aircode_tests_run / run、aircode_tests_status / status,以及
aircode_tests_open / open。變更前先讀取輸入結構定義:
aircode-tests catalog
aircode-tests describe --input '{"action":"tests.launchUnits"}'
aircode-tests run --input '{"action":"tests.units","input":{}}'
單元測試套件使用 tests.launchUnits,確切的集合使用 tests.launchRegression,
並帶上傳回的範圍與固定修訂版本,以及結構定義中要求的明確鍵值。
專案由工作階段能力提供;請勿加入 project 欄位。
--input - 接受標準輸入中有大小限制的 JSON。status 接受
{scopeId,ownerKind,ownerId};open 接受相同的識別資料,或以 {} 開啟測試頁面。
請保持傳回的 openPath 原樣不變。使用 MCP 時,將相同引數傳給
對應的 aircode_tests_* 工具。請參閱 AI 文件。
對話中的啟動操作僅接受探索流程已辨識的執行設定與服務。 請使用已辨識的專案指令碼,或從擁有者介面啟動自訂命令。
回應遺失後,先檢查狀態;明確重試相同操作時,請重用 相同的鍵值與輸入。 讀取狀態永遠不會重新啟動工作。Planning 模式與唯讀對話 不能寫入;工具過期或遭撤銷後,需要依正常流程恢復對話。 這些工具不授予通用 shell 或公開傳輸證據的權限。 請勿修改儲存內容或偽造憑證來繞過拒絕。
儲存與可處理的拒絕原因
定義、基準與不可變更的執行事實,存放在實例的 私有測試 SQLite 領域中。大型日誌、截圖與追蹤保存在私有伴隨 檔案中。只備份資料庫不會包含這些位元組內容;請在具一致性的實例備份中 一併保留伴隨檔案。請勿複製正在使用的 WAL 資料庫作為備份。 獨有與核心證據預設保留;只有經驗證確實重複的已結束執行附件, 才能明確刪除。沒有清除獨有證據的通用操作。 已辨識的機密資訊會被遮蔽或拒絕接收,但篩選器無法找出任意日誌、 影像、封存檔或專案資料中的每一項機密。
| 拒絕或需要注意的狀態 | 下一步操作 |
|---|---|
| 沒有單元套件 / 集合為空 | 分類並儲存套件,或加入確切的集合成員。 |
| 引擎缺失或不受支援 | 檢查執行檔、已安裝相依項目與已驗證版本;適當時可使用如實呈現限制的自訂命令。 |
| 資料未隔離 / 原始碼不確定 | 報告顯示通過,這項事實寫在詳細資料中;在這樣的執行可以成為基準之前,請先建立專用測試夾具。 |
| 指定範圍重播不可用 | 重跑完整選取範圍,或檢查保留的報告。 |
| 原始碼變更 / 基準不完整 | 檢查目前的原始碼、預期與相容性,再明確選擇適當的新範圍或基準。 |
| 佇列、記憶體、磁碟或配額導致延後 | 解決指出的資源限制,再明確請求啟動或恢復。不會憑空推定重設時間,也不會自行重試。 |
| 清理被拒絕 / 證據缺失 | 檢查保留的原因與證據;使用可用的證據復原功能,不要重播測試或手動刪除私有狀態。 |