GitLab 官方將 macOS 託管 Runner 標示為 Beta，並明確指出它以 headless 模式執行，依賴 UI 互動的工作負載不受支援；因此，排查 UI 測試時應先判斷是否命中這項限制，而非反覆重試或只改 Runner 標籤。GitLab macOS 託管 Runner 文件亦提醒，單一 job 失敗本身不足以確認根因。
本週建議動作：抽取一筆失敗 job，先按建置、非互動測試、UI 測試分段檢查日誌，再核對實際 Runner、映像與工具鏈。只有在確認工作負載需要 UI 會話後，才安排其他 Mac 執行環境試跑。
適合閱讀的對象
- 正在排查 GitLab 託管 macOS Runner 上 iOS UI 測試失敗的 CI 平台工程師。
- 需要分配託管 Runner 與其他 Mac 執行任務的企業 IT 和技術負責人。
- 必須區分非互動測試與 UI 驗收工作的 QA、iOS 發布負責人。
最後更新於 2026-11-05；此日期的限制與狀態核對依據為 GitLab macOS 託管 Runner 官方文件，以及 Apple 的 XCTest 與 Xcode 測試說明。Runner 映像、可用條件與功能狀態可能變動；實際排查時仍應以最新文件及你所用環境為準。
GitLab 託管 macOS Runner UI 測試失敗：依失敗階段分流
先確認失敗發生在甚麼階段，而非把所有紅色 job 都歸類為 UI 測試問題。GitLab 將 job 狀態用來表示工作執行結果；查看狀態與完整輸出，才能分清任務未開始、建置失敗，或測試執行後才出錯。GitLab CI/CD job 狀態說明與檢視 job 日誌的文件可作為核對依據。
- 建置失敗：檢查編譯器輸出、相依套件解析及簽署設定。若測試尚未啟動，先處理建置或設定問題，暫時不要將原因判作 headless 限制。
- 一般測試失敗：確認測試程序是否啟動、失敗項目是否屬於非互動測試，以及錯誤是否來自斷言、測試資料或相依服務。
- UI 測試失敗：查看測試是否要求操作畫面、啟動 Simulator UI，或依賴 testmanagerd。若測試目標本身需要桌面互動，託管 Runner 的 headless 模式便是需要優先核實的限制。
- 測試未啟動或執行環境不可用：查 job 日誌記錄的 Runner 類型、映像資訊與 Xcode、Simulator runtime 狀態，並確認任務是否真的派送到預期環境。
注意：「測試命令回傳失敗」不是根因判斷。先以日誌確認命令是否啟動、測試目標是否執行，再將錯誤訊息與該測試要求的執行條件對照。
headless 限制與工具鏈問題：兩種不同處理路徑
GitLab 文件列明，託管 macOS Runner 以 headless 模式執行，依賴 UI 互動的工作負載不受支援，並包括涉及 testmanagerd 的工作。若測試有這類依賴，這是執行模式的限制，不是暫時故障；重跑 pipeline、調整標籤或把 job 移到同一類託管 Runner，不能讓它取得原本缺少的 UI 互動條件。官方限制與 Runner 說明
但看到「Simulator 不可用」或「測試未能啟動」，也不應立即推論一定是 headless 問題。先分開核實以下線索：
- Runner 路由：在 job 日誌中確認實際 Runner 類型及執行環境，對照 pipeline 的標籤、規則及任務派送結果。預期的標籤設定不等於實際執行環境已符合預期。
- 映像與工具鏈：核對映像中可用的工具、Xcode 版本及 Simulator runtime。GitLab 的託管 Runner 文件會說明映像與可用條件；不要把其他映像或舊版文件中的資訊直接套用到目前的 job。GitLab 託管 Runner 映像與可用條件
- 測試本身的互動需求：查明測試是否啟動 UI、自動操作畫面，或依賴 testmanagerd。若有，應按已知限制安排環境評估，而非當成 runtime 缺漏處理。
- 日誌完整性：保留失敗 job 的原始輸出、測試目標與觸發條件。缺少這些資料時，無法可靠地區分任務未派送、環境不符與測試執行失敗。GitLab job 日誌文件亦說明了如何檢視 job 輸出。
對使用 GitLab macOS hosted runners 的團隊而言，最容易忽略的風險是把映像、Runner 路由與 UI 執行限制混成一件事。前兩者需要核對當前文件和實際 job 環境；UI 互動是否受支援，則要先對照官方列出的工作負載限制。
XCTest 與 UI 驗收：建置通過不等於整條鏈路可用
Apple 將 XCTest 說明為測試框架，並以 XCUIAutomation 支援 UI 自動化測試；這些用途說明不能單獨用來證明特定 GitLab Runner 支援 UI 測試。Apple 的 XCTest 與 Xcode 測試文件適合用來釐清測試類型，Runner 是否能提供所需條件則應另外依 GitLab 文件及實際試跑判斷。
例如，你的 pipeline 已能編譯應用程式，非互動測試也能執行，但發布前仍有測試要進入 Simulator、操作介面並核對畫面狀態。此時，前兩項通過只代表相應階段可執行，不能推論 UI 驗收也已打通。應逐項記錄測試目標的互動需求，讓 pipeline 分別標示建置、非互動測試與 UI 驗收的結果。
| 執行選項 | 適合評估的任務 | 主要優點 | 主要限制與核對事項 |
|---|---|---|---|
| GitLab 託管 macOS Runner | 建置與不依賴 UI 互動的測試 | 可先用現有託管環境試跑相應任務 | 官方列出 headless 限制；映像、runtime 與路由仍須核對 |
| 自管 Mac Runner | 團隊可管理使用者工作階段及執行條件的任務 | 可按自身工作流程安排 Runner 與 UI 執行環境 | 團隊需負責主機、帳戶、更新、權限與故障維護 |
| 遠端 Mac 執行環境 | 需要另行評估 UI 會話、遠端操作或彈性安排的任務 | 可把 Mac 執行工作與個人開發設備分開考慮 | 遠端連線不等於 UI 測試保證；仍要以相同工作流程驗證 |
代表性試跑與任務分工
Apple 文件能幫你區分 XCTest 與 UI 自動化的用途，GitLab 文件則界定託管 Runner 的已知限制。最後的環境決策應依你自己的專案工作流驗證，不應把文件描述外推為所有專案、映像和測試目標都一致。
可按以下流程試跑：
- 建立失敗樣本：選取一筆重現穩定的失敗 job，保存原始日誌、pipeline 設定、測試目標及觸發方式。
- 拆分測試階段：將建置、非互動測試與 UI 測試分開記錄，避免以單一總結果掩蓋是哪個階段沒有執行。
- 記錄實際環境：從 job 輸出確認 Runner 類型、映像、Xcode 與 Simulator runtime 資訊；若資訊不足，先改善診斷輸出，再判斷兼容性。
- 核對 UI 依賴：檢視測試是否使用 XCUIAutomation、是否需要桌面互動，或是否涉及 testmanagerd。將符合託管 Runner 限制的測試列為需改換環境驗證的候選。
- 對照候選 Mac 環境：使用相同專案、測試目標及 pipeline 記錄，比較可執行性、日誌是否足以診斷，以及主機維護與權限由誰承擔。
- 按證據拆分任務：只有代表性 UI 測試在候選環境中完成試跑，並且診斷資訊足夠時，才把該類任務正式分流；不要只因環境可遠端連線便推定相容。
GitLab Runner 的 macOS 文件說明 LaunchAgent 與使用者工作階段的執行方式，這可協助你判斷自管 Runner 是否具備符合工作流程的會話條件；它不是任何特定 UI 測試必定可運作的承諾。GitLab Runner 在 macOS 的使用者工作階段說明實際仍要以團隊使用的 Xcode、Simulator runtime、Runner 設定與測試目標驗證。
權限提醒：若考慮共享 Mac，先界定誰能登入、誰能讀取建置產物，以及工作完成後如何清理憑證與資料。可先參考資料與隱私說明，並將權限與資料處理要求納入團隊驗收，而非只驗證測試能否執行。
常見問題
GitLab 託管的 macOS Runner 為甚麼會卡在 UI 測試？
GitLab 官方文件指出，託管 macOS Runner 以 headless 模式執行，依賴 UI 互動的工作負載不受支援，包含涉及 testmanagerd 的工作。先確認失敗測試是否要求桌面或 Simulator UI 互動；若命中此限制，重試或改 Runner 標籤都不能改變執行模式。
XCTest UI 測試失敗時，應先核對哪些線索？
先看 job 停在建置、一般測試啟動，還是 UI 測試階段，再查日誌中的 Runner 類型、映像、Xcode 與 Simulator runtime 資訊。若測試程序未啟動或 runtime 不可用，先核對路由與映像內容；若錯誤指向 UI 互動，再評估 headless 限制。
GitLab 託管 macOS Runner 能否執行 iOS 單元測試？
不能單憑「iOS 單元測試」這個名稱判斷。非互動的建置與測試可按專案任務試跑，但仍須確認工具與 runtime 是否存在；如果測試依賴 testmanagerd、桌面互動或 UI 驗收，就不能推論它也受支援。
需要操作 iOS Simulator 畫面的測試，應改用哪種 Mac 環境？
可評估具備使用者工作階段與 UI 存取條件的自管 Mac，或可供團隊連線操作的遠端 Mac 環境。GitLab Runner 文件說明 macOS 上使用者工作階段與 LaunchAgent 的執行方式，但實際相容性仍須以相同專案、測試目標及工作流程試跑。
任務分流與環境選擇：依證據落地
若你的 job 只是建置或執行不依賴 UI 互動的測試，可先在託管 Runner 上依當前映像與工具鏈條件試跑；若測試必須操作 Simulator 或桌面，則應評估具備相應使用者工作階段的自管或遠端 Mac。這不是對特定環境的兼容性保證，而是按工作負載需求選擇驗證路徑。
託管 Runner 的優點是可先承接符合條件的工作，但 headless 限制、映像或 runtime 差異及任務路由，都可能令排查複雜化；自管 Mac 的優點是團隊可安排執行條件，代價則是硬體、帳戶、更新與維護責任。遠端 Mac 可以成為候選執行環境，但其連線方式本身不能替代 UI 測試驗收。
若目前流程完全仰賴託管 Runner，可能遇到 UI 工作負載不受支援、環境診斷不足，以及無法掌控使用者工作階段等限制。企業可以評估自購 Mac，自行承擔資產與維護；若只需為指定測試安排可連線的 Mac 執行環境，亦可先整理代表性測試與日誌，再查看 OSXPort 的 Mac 環境指南及香港 Mac mini 環境資訊。選用租賃方案前，請先用相同工作流確認工具鏈、UI 會話及權限需求；若測試要求特定實體介面或長期固定硬體，則應把自購設備一併納入評估。
常見問題
GitLab 託管的 macOS Runner 為甚麼會卡在 UI 測試？
GitLab 官方文件指出，託管 macOS Runner 以 headless 模式執行，依賴 UI 互動的工作負載不受支援，包含涉及 testmanagerd 的工作。先確認失敗測試是否要求桌面或 Simulator UI 互動；若命中此限制，重試或改 Runner 標籤都不能改變執行模式。
XCTest UI 測試失敗時，應先核對哪些線索？
先看 job 停在建置、一般測試啟動，還是 UI 測試階段，再查 job 日誌中的 Runner 類型、映像、Xcode 與 Simulator runtime 資訊。若測試程序未啟動或 runtime 不可用，先核對任務實際路由與映像內容；若錯誤指向 UI 互動，再評估 headless 限制。
GitLab 託管 macOS Runner 能否執行 iOS 單元測試？
不能只憑「iOS 單元測試」這個名稱判斷。非互動的建置與測試可按專案任務試跑，但仍須確認所需工具與 runtime 是否存在；如果測試依賴 testmanagerd、桌面互動或 UI 驗收，就不能把一般單元測試可執行推論為 UI 測試也受支援。
需要操作 iOS Simulator 畫面的測試，應改用哪種 Mac 環境？
可評估具備使用者工作階段與 UI 存取條件的自管 Mac，或可供團隊連線操作的遠端 Mac 環境。GitLab Runner 的 macOS 文件說明使用者工作階段與 LaunchAgent 的執行方式，但實際相容性仍須以相同專案、測試目標及工作流程試跑，不能僅因可以遠端連線便認定 UI 測試一定成功。