今週は、GitLabホステッドmacOS RunnerのUIテスト失敗を再試行で片づけず、まずテストがUI操作やtestmanagerdに依存しているかを確認してください。該当する場合はheadless実行の制約が原因候補となるため、UIセッションを利用できるMac実行環境を評価し、Runnerタグの変更だけで直るとは見なさないでください。
企業CIのプラットフォーム担当者、iOSリリース責任者、Apple向けCI環境を選定するIT・技術責任者向けです。ビルド失敗、非対話型テストの失敗、UIテストの失敗を、ログと実行条件から切り分けます。
最終更新：2026年11月5日。GitLabのホステッドmacOS Runner公式資料と、AppleのXCTestおよびXcodeテスト資料を照合しています。Runnerの状態やイメージ、制限は変更される可能性があるため、実際に使う時点の公式資料も確認してください。
まず失敗段階を分け、実行環境を照合します
ジョブが失敗したという事実だけでは、headless制約、ツールチェーンの不足、タスクのルーティングのどれが原因かは特定できません。GitLabのジョブ状態の定義とジョブログの確認方法に沿って、最初に失敗した処理とログの終端を確認します。
| 失敗の見え方 | 先に確認すること | 判断の方向 |
|---|---|---|
| ビルドがテスト開始前に失敗する | Runnerの種類、選択されたイメージ、Xcodeや必要なツールの情報 | UI制約と決めつけず、環境・ビルドログを調査します |
| テストが起動しない、またはSimulatorランタイムが見つからない | ジョブが想定したRunnerに割り当てられたか、イメージとランタイムが合っているか | ルーティングと利用可能な環境情報を照合します |
| 非対話型テストは進むが、画面操作を含むテストが止まる | テスト対象がUI操作やtestmanagerdに依存するか | headless制約への該当を確認し、必要なら別環境を試します |
| ビルドと単体テストは通るが、UIテストが失敗する | UIテストの開始状況、失敗ログ、ユーザーセッションの有無 | ビルド成功をUIテストの実行可能性と混同しません |
GitLabの公式資料では、ホステッドmacOS RunnerはBetaとして案内され、headlessで実行されます。また、testmanagerdを含むUI操作に依存するワークロードはサポート対象外とされています。制限とイメージの説明を基準に、失敗したテストの要件と照合してください。制約に該当するタスクは、再試行やラベル変更で解消する一時的な障害として扱わないことが重要です。
ビルド成功とUIテストの実行可否は分けて考えます
XCTestはAppleのテストフレームワークであり、XCUIAutomationはユーザーインターフェースを操作するテストに関係します。AppleのXCTest資料とXcodeのテスト概要を参考に、プロジェクト内のテストをビルド、単体テスト、統合テスト、UIテストに分けてください。
たとえば、ビルドとロジック中心のテストは成功していても、画面遷移や操作を検証するXCTest UIテストだけが失敗するケースがあります。この場合、ビルド成功だけを根拠にパイプライン全体を利用可能と判断するのは早計です。テスト対象が画面操作やUIセッションに依存するか、失敗直前のログとともに確かめてください。
今週行う切り分け手順
- 失敗ジョブのログを保存し、最初に失敗したコマンドとテスト名を特定します。
- ジョブが実際に使ったRunnerの種類とイメージを、設定したタグやルールだけでなく実行記録でも照合します。
- ログや環境情報から、XcodeとSimulatorランタイムが対象テストに必要な状態かを確認します。イメージの内容や提供状況は、GitLabのホステッドRunner資料で最新情報を確認してください。
- テスト対象をビルド、非対話型テスト、UIテストに分け、どの段階まで通過したか記録します。
- UIテストがtestmanagerdや画面操作に依存する場合、headless制約との一致を確認し、単なる一時障害として再試行を繰り返さないようにします。
- 同じプロジェクト、テスト対象、パイプライン記録を使い、候補となるMac環境でも試走します。通過可否だけでなく、失敗ログの診断しやすさと環境の保守責任も比較します。
バージョンやランタイムの不足は確認すべき手掛かりですが、ログに情報がない段階で原因と断定しないでください。利用可能なイメージやツールは更新されることがあるため、ジョブの実行時情報と公式資料の記載を並べて判断します。
実行環境は「必要なセッション」と保守責任で選びます
非対話型のビルドやテストをホステッドRunnerで試す選択肢は残しつつ、画面操作が必要なテストは別のMac実行経路を評価します。自社管理Runnerではユーザーセッションの維持や運用を担う一方、リモートMacでは接続方式だけでなく、チームのテスト手順が実際に動くかの確認が必要です。
GitLab RunnerのmacOS向け資料では、macOS上のユーザーセッションとLaunchAgentを使う実行方法が説明されています。したがって、候補環境を選ぶときはSimulatorを起動できるユーザーセッションがあるかを確認できますが、資料の説明だけでチームの特定ワークフローとの互換性まで保証されるわけではありません。
- ホステッドRunnerの利点は、個別のMacを購入・管理せずにジョブを試せることです。一方、headless制約に該当するUIワークロードには適しません。
- 自社管理のMacは、ユーザーセッションやツールチェーンをチームの要件に合わせて検証できます。一方、Runnerの保守、アクセス権、環境更新を運用側で管理する必要があります。
- リモートMacは、チームで利用する実行環境の候補になります。一方、リモートアクセスが可能でもUIテストが通るとは限らず、代表的なテストでの試走が欠かせません。
よくある判断上の疑問
失敗したジョブは、まず再実行すべきですか？
ログ上で一時的な通信や処理の失敗が確認でき、UI操作に依存しないタスクなら、再実行結果を比較する余地があります。反対に、UIテストがheadless制約に該当するなら、同じ実行条件で再試行を重ねても原因の切り分けにはなりません。ログとテスト要件を先に照合してください。
Runnerタグを変えればUIテストが動きますか？
タグはジョブの割り当てに関わりますが、割り当て先の実行環境がUIセッションを提供するとは限りません。タグを変更した場合も、実際に割り当てられたRunner、イメージ、実行ログを確認し、テストが必要とするセッション条件を満たすかを別に検証してください。
同じパイプラインで環境の違いをどう比較しますか？
プロジェクトとテスト対象を変えずに候補環境で実行し、成功した段階、失敗したテスト、診断に必要なログが残るかを記録します。さらに、RunnerやMac環境の更新・アクセス管理を誰が担うかも比較対象に含めると、単純な成功率だけでは見えない運用負担を判断できます。
UIセッションが必須なら、試走後にMac環境を選びます
現在のホステッドRunnerを使い続ける場合、headlessのためUI操作に依存するテストを実行できないこと、Runnerタグだけでは環境制約を解消できないこと、イメージやランタイムの提供状態を都度確認する必要があることが制約になります。非対話型ジョブとUIテストを分けて、どのタスクをどの環境に置くかを、同じテスト対象で得た記録から決めてください。
自社管理Macはセッションや構成を細かく確認しやすい反面、保守とアクセス管理が必要です。UIテストの検証環境を一時的に用意したい場合は、OSXPortのMac環境案内を候補の一つとして確認し、実際のテスト対象で適合性を試走してください。運用前にはMac環境のガイドも参照し、リモート利用がUIテストの成功を保証するものではない点を踏まえて判断しましょう。
よくある質問
GitLabのホステッドmacOS Runnerでは、なぜUIテストが失敗するのですか？
GitLabの公式資料では、ホステッドmacOS Runnerはheadlessで動作し、testmanagerdなどUI操作に依存するワークロードはサポート対象外とされています。テストがこの制約に該当するなら、再試行やRunnerタグの変更では解決しません。対象テストと失敗ログを照合してから、UIセッションを利用できる実行環境を評価してください。
XCTestのUIテストが失敗したとき、最初に何を確認すればよいですか？
まずジョブログで、ビルド、テスト起動、テスト実行のどの段階で止まったかを確認します。次にRunnerの種類、選択されたイメージ、XcodeとSimulatorランタイムの情報をジョブログと公式のイメージ説明で照合します。testmanagerdや画面操作が必要なテストなら、環境情報の不一致とheadless制約を別々に判定してください。
ホステッドmacOS RunnerでiOSの単体テストは実行できますか？
単体テストかどうかだけで可否は決められません。ビルドや非対話型のテストは、プロジェクトのテスト対象とRunner環境を使って試走し、実際の結果で判断します。Simulatorの画面操作やUIセッションを必要とするテストは、GitLabが案内するheadless実行の制約に該当する可能性があるため、単体テストとUIテストを分けて確認してください。
iOS SimulatorのUIテストには、どのようなMac CI環境が向いていますか？
ユーザーセッション上でSimulatorや画面操作を実行できるかを確認できる、自社管理のMac RunnerやリモートMac環境が候補になります。GitLab RunnerのmacOS向け資料では、ユーザーセッションで動作するLaunchAgentの構成が説明されています。ただし、リモート接続できることだけではUIテストの成功は保証されないため、同じテスト対象とパイプラインで試走してください。