GitLab 호스팅 macOS Runner에서 UI 테스트가 실패하면, 먼저 해당 테스트가 UI 상호작용이나 testmanagerd에 의존하는지 확인하세요. 공식 문서는 이 Runner가 headless 방식으로 실행되며 UI 상호작용이 필요한 작업을 지원하지 않는다고 명시합니다. 이 조건에 해당하면 반복 실행이나 Runner 태그 변경 대신, UI 세션을 갖춘 Mac 환경을 검증하세요.
이 안내는 호스팅 Runner의 실패를 조사하는 CI 플랫폼 엔지니어, 작업을 분리하려는 IT 책임자, iOS 테스트 결과를 검토하는 QA 및 출시 담당자를 위한 내용입니다.
2026년 11월 5일 확인: GitLab 문서는 macOS 호스팅 Runner를 Beta로 표시하고, headless 실행 및 UI 상호작용 작업의 제한을 안내합니다. 이미지와 기능 상태는 바뀔 수 있으므로 최신 호스팅 macOS Runner 안내를 다시 확인하세요.
실패 단계에 따라 원인을 분리하세요
job이 실패했다는 사실만으로는 원인을 알 수 없습니다. 빌드가 끝나기 전에 실패했는지, 테스트 프로세스가 시작된 뒤 실패했는지, UI 조작 단계에서 멈췄는지부터 구분해야 합니다. GitLab은 job 상태와 로그를 별도로 설명하므로 job 상태 정의와 job 로그 확인 방법을 기준으로 기록을 살펴보세요.
- 빌드 실패: 컴파일이나 의존성 설치 단계에서 멈췄다면 UI 지원 여부를 먼저 의심하지 마세요. 오류에 표시된 도구, 설정, 의존성 문제를 확인합니다.
- 일반 테스트 실패: 테스트가 시작됐지만 검증 조건을 통과하지 못했다면 실패한 테스트와 실행 환경을 분리해 살핍니다. 단위 테스트 실패를 UI 세션 제한으로 단정하지 마세요.
- UI 테스트 실패: 테스트가 Simulator 화면을 열거나 화면 요소와 상호작용하는 시점에 실패한다면, headless 제한과 테스트 요구 조건이 맞지 않는지 확인합니다.
- 테스트 미시작 또는 런타임 오류: 테스트 대상 실행 흔적이 없거나 Simulator 런타임을 찾지 못한다면 Runner 유형, 이미지, Xcode 및 런타임 정보를 점검합니다.
이 구분은 대응 경로를 바꿉니다. 로그에 UI 상호작용을 요구하는 작업의 단서가 있다면 단순한 일시 오류로 분류하지 마세요. 반대로 로그만으로 제한 여부가 분명하지 않다면, 테스트 대상과 Runner 정보를 확보한 뒤 한 가지씩 검증해야 합니다.
headless 제한과 환경 문제를 구별하세요
GitLab의 macOS 호스팅 Runner 안내는 UI 상호작용에 의존하는 작업, testmanagerd를 사용하는 작업을 지원 대상에서 제외합니다. 따라서 해당 작업은 재시도만으로 해결될 것으로 기대하기 어렵습니다. GitLab macOS 호스팅 Runner의 제한과 실행 조건을 확인하고, 팀의 테스트가 실제로 어떤 세션을 요구하는지 대조하세요.
그와 별개로 이미지나 도구 체인, 작업 라우팅 문제일 수 있습니다. job이 의도한 Runner에 배정됐는지, 사용 중인 이미지에서 필요한 Xcode와 Simulator 런타임을 이용할 수 있는지 확인해야 합니다. 이미지별 도구와 지원 상태는 바뀔 수 있으므로, 특정 버전이 항상 설치돼 있다고 가정하지 말고 호스팅 Runner의 이미지와 이용 조건에서 현재 정보를 확인하세요.
판별할 때 주의하세요: 빌드가 성공하거나 일반 XCTest가 통과해도 UI 자동화가 지원된다는 뜻은 아닙니다. Apple은 XCTest와 XCUIAutomation의 테스트 기능을 설명하지만, 해당 설명은 GitLab 호스팅 Runner의 지원 범위를 보증하지 않습니다. Apple의 XCTest 안내와 Xcode 테스트 개요를 테스트 유형을 구분하는 자료로 활용하세요.
실행 환경은 테스트 요구 조건으로 선택하세요
아래 표는 작업을 어디에서 검증할지 정하기 위한 비교입니다. 실제 지원 여부는 프로젝트와 설정에 따라 달라지므로, 대표 테스트로 확인한 뒤 배치하세요.
| 실행 경로 | 적합성을 판단할 기준 | 주요 주의점 |
|---|---|---|
| GitLab 호스팅 macOS Runner | UI 세션 없이 수행되는 빌드와 테스트를 실제 job으로 검증합니다. | 공식 안내의 headless 제한에 맞는 UI 작업은 지원되지 않습니다. |
| 팀이 관리하는 Mac Runner | 사용자 세션, Runner 실행 방식, Simulator 접근을 팀이 직접 구성하고 검증할 수 있습니다. | OS와 도구 체인 관리, 계정 및 권한 통제, 유지보수가 팀 책임입니다. |
| 원격 Mac 실행 환경 | UI 세션이 필요한 작업을 실행할 조건이 있는지 실제 테스트로 검증합니다. | 원격 접속이 가능하다는 사실만으로 UI 테스트 호환성이 보장되지는 않습니다. |
GitLab Runner의 macOS 설치 및 사용자 세션 안내를 보면 macOS에서 Runner를 실행하는 방식과 LaunchAgent 등 세션 관련 조건을 확인할 수 있습니다. 이를 참고해도 팀의 Simulator 설정이나 인증 흐름이 자동으로 호환되는 것은 아닙니다.
실무에서는 빌드와 UI 검증을 별도 job으로 나누는 편이 원인 파악에 유리합니다. Apple 플랫폼 작업을 호스팅 Runner에 어디까지 둘지 정할 때는 기업 iOS CI 환경 안내도 참고할 수 있습니다. 데이터 접근과 계정 관리가 중요한 조직은 데이터와 개인정보 안내를 검토해 보세요.
재현 가능한 시험으로 다음 조치를 정하세요
다음 순서로 시험하면 문제를 환경 제한, 런타임, 라우팅 중 어디에 둘지 판단하기 쉽습니다.
- 실패한 job의 원본 로그를 저장합니다. 빌드 단계, 테스트 시작 여부, 마지막으로 성공한 작업을 기록하세요. GitLab의 로그 안내에 따라 job 로그를 확인합니다.
- 실행 조건을 고정해 적습니다. 프로젝트, 테스트 대상, Runner 유형, 이미지, Xcode 및 Simulator 런타임 정보를 남깁니다. 모르는 항목은 추측하지 말고 Runner 정보와 공식 문서에서 확인합니다.
- 테스트 요구를 구분합니다. 빌드, 일반 단위 테스트, 통합 테스트, Simulator 화면 조작이 필요한 XCTest UI 테스트를 나눕니다. Apple의 테스트 기능 설명을 참고하되, Runner 지원 판단과 혼동하지 마세요.
- 호스팅 Runner에서 비대화형 작업을 시험합니다. 같은 프로젝트의 빌드와 UI 상호작용을 요구하지 않는 테스트를 실행하고 로그를 남깁니다. 여기서 성공하면 해당 작업에 대한 확인이지, UI 자동화 전체의 승인으로 확대할 수는 없습니다.
- UI 작업은 후보 Mac 환경에서 재현합니다. 동일한 테스트 대상과 필요한 설정을 사용하고, 사용자 세션과 Simulator 접근이 실제로 작동하는지 확인합니다. 원격 화면을 볼 수 있는 것만으로는 통과 판정을 내리지 마세요.
- 결과를 기준으로 job을 배치합니다. 비대화형 작업은 확인된 조건에 따라 호스팅 Runner에서 운영하고, UI 세션을 요구하는 작업은 별도 Mac 경로에서 검증합니다. 이미지나 런타임이 달라지면 기존 결과를 새 환경의 보증으로 취급하지 않습니다.
시험 결과는 실행 가능 여부뿐 아니라 로그로 원인을 진단할 수 있었는지, 이미지와 세션을 누가 유지하는지까지 포함해 비교하세요. 팀의 인증 정보나 테스트 데이터가 외부 환경에 전달되는 구조라면 접근 권한과 보존 정책도 함께 검토해야 합니다.
자주 묻는 질문
호스팅 Runner에서 UI 테스트가 지원되지 않는 이유는 무엇인가요?
GitLab이 안내하는 실행 방식은 headless이며, UI 상호작용이나 testmanagerd에 의존하는 작업은 지원 범위 밖입니다. 따라서 테스트가 실제 데스크톱 세션을 요구하는지 확인하세요. 해당 조건이 확인되면 재시도보다 사용자 세션을 마련할 수 있는 실행 경로를 검증하는 편이 타당합니다.
XCTest UI 테스트가 실패할 때 먼저 볼 항목은 무엇인가요?
먼저 job 로그에서 빌드 성공 여부와 테스트 프로세스의 시작 여부를 확인합니다. 이어 실제 Runner와 이미지, Xcode 및 Simulator 런타임을 대조하세요. 테스트가 UI 조작에 도달한 뒤 실패하는지, 런타임을 찾지 못해 시작하지 못하는지 구분해야 서로 다른 원인을 한데 묶지 않을 수 있습니다.
호스팅 Runner에서 iOS 단위 테스트를 실행할 수 있나요?
UI 상호작용을 요구하지 않는 테스트는 프로젝트의 실제 작업을 실행해 확인할 수 있습니다. 다만 테스트 종류만 보고 결과를 일반화하지 마세요. 의존성, 런타임, job 설정이 맞는지 로그와 함께 기록하고, 비대화형 테스트 성공을 UI 테스트 지원의 근거로 사용하지 않습니다.
Simulator UI 테스트에는 어떤 Mac 환경을 선택해야 하나요?
사용자 세션과 UI 접근을 구성할 수 있는 팀 관리 Mac 또는 원격 Mac을 후보로 시험하세요. GitLab Runner 문서의 macOS 사용자 세션 안내는 구성 조건을 파악하는 데 도움을 주지만, 특정 프로젝트의 호환성을 보장하지 않습니다. 같은 테스트 대상을 실행해 세션, 런타임, 로그가 모두 필요한 기준을 만족하는지 판단하세요.
시험 결과를 바탕으로 실행 경로를 정하세요
호스팅 Runner는 팀이 직접 관리할 항목을 줄일 수 있지만, headless 제한과 이미지 조건을 따라야 하며 UI 세션이 필요한 작업을 맡기기 어렵습니다. 팀 관리 Mac은 세션과 도구 체인을 통제할 수 있는 대신 유지보수와 보안 책임이 늘어납니다. 원격 Mac도 UI 테스트 적합성을 먼저 검증해야 하며, 원격 접속 기능 자체를 성공 보증으로 보아서는 안 됩니다.
UI 검증이 CI의 필수 단계라면, 실패 로그와 대표 테스트를 정리한 뒤 별도 Mac 환경에서 같은 작업을 시험하세요. 필요하면 서울 원격 Mac 환경 정보를 살펴보고 테스트 조건에 맞는지 확인할 수 있습니다. 자체 Mac 구매는 장기적으로 고정된 사양과 물리적 접근이 필요한 팀에 맞을 수 있습니다. 반면 시험용 환경이나 일정이 제한된 검증을 위해 장비를 먼저 구매하면 초기 조달, 유지보수, 사용률 관리가 따라옵니다. OSXPort의 Mac 대여는 이런 단기 검증 경로를 검토할 선택지지만, 실제 XCTest UI 테스트 통과 여부는 팀의 프로젝트와 세션 조건으로 확인한 뒤 결정하세요.
자주 묻는 질문
GitLab 호스팅 macOS Runner에서 UI 테스트가 막히는 이유는 무엇인가요?
공식 문서에 따르면 호스팅 macOS Runner는 headless 방식으로 실행되며, testmanagerd를 포함해 UI 상호작용에 의존하는 작업은 지원되지 않습니다. 따라서 같은 작업을 다시 실행하거나 Runner 태그만 바꾸는 것으로 해결된다고 볼 수 없습니다. 먼저 실패한 테스트가 실제 데스크톱 또는 Simulator UI 세션을 요구하는지 확인하고, 요구한다면 해당 조건을 갖춘 별도 Mac 환경을 검증하세요.
GitLab macOS Runner에서 XCTest UI 테스트가 실패하면 무엇부터 확인해야 하나요?
실패한 job의 로그에서 빌드 단계, 테스트 실행 단계, 테스트 대상이 시작된 흔적을 차례로 확인하세요. 이어서 실제 할당된 Runner 유형과 이미지, Xcode 및 Simulator 런타임 정보를 공식 이미지 안내와 대조해야 합니다. 테스트가 시작되지 않았거나 런타임을 찾지 못했다면 환경 또는 라우팅 문제일 수 있고, UI 상호작용 단계에서 막혔다면 headless 제한과 맞는지 따로 판단해야 합니다.
호스팅 macOS Runner에서 iOS 단위 테스트도 실행할 수 있나요?
UI 세션을 요구하지 않는 빌드나 테스트는 프로젝트의 실제 작업을 호스팅 Runner에서 시험해 볼 수 있습니다. 다만 Apple의 XCTest 설명만으로 특정 GitLab Runner에서의 지원을 보장할 수는 없습니다. 테스트 대상과 의존 도구, Simulator 런타임을 확인하고 대표 작업의 결과를 기록하세요. 일반 테스트가 통과해도 UI 자동화까지 사용할 수 있다는 뜻은 아닙니다.
iOS Simulator UI 테스트에는 어떤 Mac CI 환경을 검토해야 하나요?
사용자 세션과 UI 접근 조건을 통제할 수 있는 자가 관리 Mac 또는 원격 Mac을 후보로 두고, 동일한 프로젝트와 테스트 대상을 실행해 보세요. GitLab Runner의 macOS 안내는 사용자 세션과 LaunchAgent 실행 방식에 관한 조건을 설명하지만, 그 자체가 모든 UI 테스트의 성공을 보장하지는 않습니다. 팀의 인증 정보, Simulator 설정, 로그 보존 방식까지 포함해 실제 파이프라인에서 확인해야 합니다.