Que faire si les tests d’interface échouent sur un exécuteur macOS hébergé par GitLab ? Diagnostic 2026

La compilation réussit, mais le job de tests d’interface échoue ou ne démarre pas sur l’exécuteur macOS hébergé par GitLab.

Cette semaine, vérifiez d’abord si le test exige une interaction graphique ou testmanagerd : GitLab indique que ses exécuteurs macOS hébergés fonctionnent en mode headless et que ces charges de travail ne sont pas prises en charge. Si le test est non interactif, contrôlez ensuite l’image, Xcode, le runtime Simulator et le routage du job ; ne considérez pas un simple changement d’étiquette Runner comme une correction.

Cet article s’adresse aux ingénieurs de plateforme CI qui analysent des échecs de tests iOS, aux responsables IT qui répartissent les tâches entre environnements Mac, ainsi qu’aux responsables QA et publication qui doivent distinguer tests non interactifs et validation avec interface.

Dernière vérification éditoriale : 5 novembre 2026, à partir de la documentation GitLab des exécuteurs macOS hébergés, des pages GitLab sur les images disponibles et les sessions macOS, et de la documentation Apple sur XCTest et les tests Xcode. Les états des images et les limites peuvent évoluer : contrôlez les pages officielles et votre environnement au moment du diagnostic.

Le type d’échec avant le message d’erreur

Un job en échec ne permet pas, à lui seul, d’identifier sa cause. Il faut d’abord établir si le pipeline s’arrête pendant la compilation, l’exécution de tests non interactifs ou l’ouverture d’une interface Simulator. Cette distinction évite de modifier l’environnement pour un problème qui se situe en réalité dans le code, ou de relancer indéfiniment une tâche incompatible avec le mode d’exécution.

Moment où le job s’arrête	Indices à chercher dans le journal	Première piste
Avant le lancement des tests	Erreur de compilation, dépendance introuvable, configuration de cible incorrecte	Vérifier le projet, les dépendances et la commande de compilation
Au lancement d’un test non interactif	Échec d’initialisation, cible de test absente, outil ou runtime indisponible	Vérifier l’image et les versions réellement présentes
À l’ouverture d’un Simulator ou pendant un test d’interface	Session graphique indisponible, interaction impossible ou activité liée à `testmanagerd`	Comparer la tâche aux limites headless documentées
Avant même l’exécution des commandes prévues	Job affecté à un Runner inattendu, image ou tags différents de ceux prévus	Examiner la sélection du Runner et le contexte réel du job

Consultez le journal d’un job GitLab CI/CD depuis le début, et non seulement la dernière ligne en rouge. La première erreur significative est souvent plus instructive que le message final, qui peut simplement signaler que le processus précédent s’est interrompu. Les états de job décrits dans la documentation GitLab sur les jobs CI/CD aident aussi à séparer un job non démarré d’un processus ayant commencé puis échoué.

Pourquoi GitLab macOS hosted runners peuvent-ils refuser un test d’interface ?

La documentation GitLab indique que les exécuteurs macOS hébergés sont en bêta et fonctionnent en mode headless. Elle précise que les charges de travail qui nécessitent une interaction avec l’interface, notamment celles impliquant testmanagerd, ne sont pas prises en charge. Vérifiez cette limitation à partir de la documentation officielle des exécuteurs macOS hébergés : il s’agit d’une limite du type de tâche, pas d’un incident que des relances répétées sont supposées corriger.

Cela ne signifie pas que toute commande de test Apple échouera sur cet environnement. XCTest regroupe des mécanismes de test dont les usages ne sont pas tous identiques. La question utile est donc : le test vérifie-t-il une logique sans interaction avec l’interface, ou doit-il piloter une application et son environnement graphique ? Apple présente les rôles de XCTest et de ses outils de test, mais cette description ne constitue pas une garantie de compatibilité avec un Runner GitLab donné.

Le nom de la cible n’est pas une preuve suffisante. Une cible appelée « UI tests » peut inclure des préparations ou contrôles non interactifs ; à l’inverse, un job nommé « tests » peut invoquer des actions Simulator qui ont besoin d’une session graphique. Examinez la commande réellement exécutée, les destinations choisies et les premières erreurs pertinentes.

Les tests XCTest non interactifs peuvent-ils rester sur l’exécuteur hébergé ?

Ils peuvent être évalués sur cet exécuteur si leur exécution ne dépend pas des éléments explicitement non pris en charge et si l’image fournit les outils nécessaires. Une réussite de compilation ou de tests unitaires ne démontre toutefois pas que les tests d’interface fonctionneront dans le même environnement.

Apple distingue les familles de tests et leurs objectifs dans sa documentation sur les tests avec Xcode. Utilisez cette distinction pour décrire votre pipeline : compilation, tests de logique, tests d’intégration et tests d’interface ne valident pas le même comportement. Dans votre configuration, séparez-les en jobs identifiables, avec des commandes et des résultats lisibles ; vous pourrez alors conserver les vérifications non interactives là où elles sont effectivement prises en charge, sans présenter le pipeline comme entièrement validé lorsque l’étape d’interface n’a pas eu lieu.

Les indices d’image, de runtime et de routage

Lorsque le journal dit que le test n’a pas démarré, qu’une destination manque ou qu’un runtime Simulator est indisponible, traitez ces messages comme des pistes à vérifier, et non comme la preuve d’une restriction headless. L’image réellement attribuée au job, l’état actuel des images proposées et les outils présents peuvent varier. La documentation des exécuteurs hébergés et de leurs images est la référence pour contrôler les conditions et les environnements actuellement disponibles.

Vérification	Élément à relever dans le job	Interprétation prudente
Type d’exécuteur	Runner effectif et informations d’environnement visibles dans les logs	Confirmez que le job a atteint l’environnement prévu
Image sélectionnée	Image ou environnement demandé par la configuration et réellement utilisé	Vérifiez sa disponibilité actuelle dans la documentation GitLab
Chaîne Xcode	Version affichée par les outils disponibles dans le job	Comparez-la aux exigences du projet ; ne déduisez pas une version à partir d’un ancien journal
Runtime Simulator	Runtimes et destinations visibles dans l’environnement du job	Un runtime absent est une piste de configuration ou de disponibilité à investiguer
Étape d’interface	Commande, cible, destination et premier message d’échec	Déterminez si l’échec concerne le lancement de l’outil ou l’interaction graphique

Si les commandes sont disponibles dans l’image, vous pouvez ajouter à un job de diagnostic des relevés comme xcodebuild -version et xcrun simctl list runtimes. Ces sorties ne prouvent pas qu’un test d’interface est pris en charge ; elles documentent plutôt la chaîne d’outils et les runtimes effectivement visibles au moment de l’exécution. Évitez d’imprimer des variables d’environnement sans filtrage : elles peuvent contenir des secrets.

Que vérifier en premier lorsqu’un test XCTest échoue sur GitLab Runner macOS ?

Commencez par la route du job, puis contrôlez l’environnement observé. Une configuration de pipeline peut demander un Runner via des tags, mais les tags ne modifient ni le mode headless, ni les capacités de l’image, ni la nature du test. Si le job est correctement routé vers l’exécuteur hébergé attendu et que le test dépend d’une interface, changer ses tags ne répond pas à la cause documentée.

Procédez dans cet ordre, en conservant pour chaque essai le journal et la configuration correspondants :

Confirmez l’exécuteur réellement utilisé. Relevez les informations du Runner et les messages de préparation du job ; comparez-les à la sélection prévue dans le pipeline.
Identifiez la première commande qui échoue. Distinguez échec de compilation, absence d’outil, absence de destination et impossibilité d’interagir avec l’application.
Relevez les outils et runtimes depuis le job lui-même. Ne vous fiez ni à la machine d’un développeur ni à un journal ancien pour décrire l’image courante.
Lancez séparément compilation et tests non interactifs. Leur résultat renseigne sur ces étapes uniquement ; il ne valide pas la suite d’interface.
Inspectez la cible d’interface et ses dépendances. Cherchez les appels qui nécessitent un Simulator, une session utilisateur, une interaction visible ou testmanagerd.
Reproduisez le test représentatif dans l’environnement candidat. Comparez les mêmes commits, cibles, paramètres et données de test ; sinon, la différence de résultat ne permet pas d’attribuer la cause à l’environnement.

Ces contrôles couvrent trois explications distinctes : une limite d’interaction, une différence d’outillage ou de runtime, et un routage vers le mauvais exécuteur. Ne les regroupez pas sous l’étiquette vague « panne du Runner » : chaque cas appelle une décision différente.

Répartir les tâches entre exécuteurs

Si la compilation et les tests non interactifs passent tandis que le contrôle d’interface échoue, conservez ces résultats séparément. Votre tableau de suivi doit indiquer quelles cibles ont effectivement été exécutées et sur quel environnement. La documentation Apple sur XCTest et Xcode décrit les usages des outils ; elle ne remplace pas un essai de la suite réelle sur l’exécuteur que vous envisagez d’utiliser.

Option d’exécution	Tâches à évaluer	Atout de décision	Limite à vérifier
Runner macOS hébergé par GitLab	Compilation et tests ne nécessitant pas d’interface, après essai	Environnement administré selon l’offre et les conditions documentées par GitLab	Mode headless et tâches dépendant de l’interface non prises en charge
Mac autogéré avec session utilisateur adaptée	Tests qui nécessitent une session ou une interaction Simulator	Contrôle de l’environnement et possibilité de configurer la session requise	Exploitation, mises à jour, accès et stabilité à gérer par votre équipe
Mac distant administré ou loué	Tests nécessitant un Mac accessible à distance, sous réserve d’essai	Peut fournir un environnement Mac distinct sans achat d’une machine par développeur	L’accès distant ne garantit pas à lui seul le fonctionnement d’une suite UI

Pour un Runner autogéré sur macOS, GitLab documente les modes de lancement et le rôle d’une session utilisateur, notamment l’usage de LaunchAgent dans les situations concernées. Consultez les instructions GitLab pour Runner sur macOS avant de conclure qu’un Mac autogéré répondra à votre besoin. Il faut tester la session, le lancement du Simulator et la suite ciblée dans vos conditions de pipeline ; la possibilité d’accéder à distance à un Mac ne constitue pas, à elle seule, une garantie de réussite des tests d’interface.

Quel environnement choisir pour des tests d’interface sur iOS Simulator ?

Choisissez selon les prérequis observés, pas selon le seul nom du service. Si la cible exige une session graphique ou une interaction explicitement exclue des exécuteurs macOS hébergés, évaluez un Mac qui offre les conditions de session requises. Si le test est non interactif, commencez par vérifier l’image, la chaîne Xcode, le runtime et le routage avant de déplacer toute la suite.

Pour prendre une décision comparable, exécutez une même sélection représentative de tests dans l’environnement actuel et dans le candidat. Gardez le même projet, les mêmes cibles, les mêmes paramètres de build et les mêmes conditions de déclenchement. Comparez ensuite :

les étapes réellement exécutées et leurs résultats ;
la capacité à diagnostiquer l’échec à partir des journaux ;
la disponibilité des outils et runtimes requis ;
la responsabilité de l’équipe concernant les mises à jour, les accès et la continuité du service.

Ne cherchez pas à tirer une conclusion de performance à partir d’un essai isolé ou de configurations différentes. Pour une équipe dont les validations comprennent aussi des parcours de conception, de vidéo ou d’audio dépendant d’une interface, sélectionnez des scénarios représentatifs de ces applications : une suite de tests purement logique ne dira rien sur le bon fonctionnement d’un parcours visuel ou d’une session graphique.

Essai contrôlé et décision d’exploitation

Traitez votre essai comme une preuve de compatibilité, pas comme une démonstration universelle. Consignez le commit testé, la cible, la commande, le Runner effectif, l’image ou l’environnement, les versions relevées et les journaux pertinents. Répétez le protocole lorsque l’image ou la configuration change ; une validation antérieure ne garantit pas que des runtimes et outils toujours disponibles correspondent à ceux du prochain job.

Une fiche de décision peut tenir dans un tableau partagé par l’équipe :

Question de validation	Preuve à conserver	Conséquence pour la répartition
La tâche nécessite-t-elle une interaction ou `testmanagerd` ?	Cible, commande et erreur reproduite	Si oui, ne comptez pas sur une relance pour lever la limite headless
Le runtime et les outils sont-ils présents ?	Sorties de diagnostic du job	Sinon, vérifiez la documentation actuelle et le routage avant de déplacer la suite
Le test représentatif passe-t-il dans l’environnement candidat ?	Journaux complets et résultat reproductible	Si non, l’environnement n’est pas encore validé
Qui assure le maintien de l’exécuteur ?	Répartition explicite des responsabilités	Intégrez cette charge au choix entre hébergement et gestion interne

Un essai concluant dans un environnement ne doit pas être extrapolé à tous les tests ou à toutes les images. Votre compte rendu doit préciser le périmètre validé : par exemple, compilation et tests non interactifs, mais pas parcours d’interface ; ou, au contraire, cible d’interface testée avec une session et un runtime explicitement relevés. Cette précision est utile aux responsables de publication, qui peuvent ainsi définir les contrôles bloquants sans confondre couverture du code et validation complète du comportement visible.

Pour documenter la séparation des tâches et les conditions d’accès, vous pouvez consulter nos guides consacrés aux environnements Mac ainsi que les informations sur la protection des données et la confidentialité. Ces ressources ne remplacent pas l’essai de votre pipeline : elles vous aident à préparer les exigences opérationnelles avant de choisir un environnement.

Le Runner hébergé évite à votre équipe certaines responsabilités matérielles, mais son mode headless écarte les tâches qui dépendent d’une interaction graphique. Un Mac autogéré offre davantage de contrôle, au prix de l’administration des sessions, des outils et de la maintenance. Un poste local est disponible pour les essais ponctuels, mais sa disponibilité et sa configuration ne constituent pas nécessairement une base reproductible pour une équipe.

Si une suite représentative confirme que vos jobs doivent piloter un Simulator ou une interface, vous pouvez comparer cette preuve avec un Mac distant accessible par votre équipe, sans supposer que l’accès distant garantit la compatibilité. Pour un besoin temporaire ou une évaluation avant achat, la location de Mac proposée par OSXPort peut vous permettre de tester un environnement Mac réel à distance ; vérifiez d’abord que la session, les outils et le flux CI requis sont compatibles avec votre projet. Si vos charges sont durables et fortement sollicitées, comparez aussi le coût d’exploitation d’un Mac autogéré : la location n’est pas automatiquement le meilleur choix pour chaque équipe.