Diagnostics de Débogage SwiftUI
Quand utiliser cette compétence de diagnostic
Utilisez cette compétence lorsque :
- Le dépannage de base a échoué — Les patrons de la compétence
axiom-swiftui-debuggingont été appliqués mais le problème persiste - Self._printChanges() affiche des modèles inattendus — Vue se met à jour quand elle ne devrait pas, ou ne se met pas à jour quand elle le devrait
- Problèmes intermittents — Cela fonctionne parfois, échoue d'autres fois ("heisenbug")
- Chaînes de dépendances complexes — Nécessité de tracer le flux de données à travers plusieurs vues/modèles
- Investigation de performance — Vues se mettant à jour trop souvent ou prenant trop de temps
- Mystères d'aperçu (Preview) — Crashs ou échecs qui ne sont pas immédiatement évidents
Actions INTERDITES
Sous pression, vous serez tenté par des raccourcis qui cachent les problèmes au lieu de les diagnostiquer. Ne faites JAMAIS ceci :
❌ Deviner avec des changements aléatoires @State/@Observable
- "Laissez-moi essayer d'ajouter @Observable ici et voir si ça marche"
- "Peut-être que si je change ceci en @StateObject, ça corrigera le problème"
❌ Ajouter .id(UUID()) pour forcer les mises à jour
- Crée une nouvelle identité de vue à chaque rendu
- Détruit la préservation de l'état
- Masque la cause racine
❌ Utiliser ObservableObject alors que @Observable fonctionnerait (iOS 17+)
- Ajoute une complexité inutile
- Passe à côté du suivi automatique des dépendances
❌ Ignorer les problèmes intermittents ("ça fonctionne parfois")
- "Je vais juste fusionner et espérer que ça n'arrive pas en production"
- Intermittent = bogue systématique, pas de l'aléatoire
❌ Livrer sans comprendre
- "La correction fonctionne, je ne sais pas pourquoi"
- La production est trop coûteuse pour les essais-erreurs
Premières étapes obligatoires
Avant de plonger dans les patrons de diagnostic, établissez l'environnement de base :
# 1. Vérifier la configuration d'Instruments
xcodebuild -version # Doit être Xcode 26+ pour l'instrument SwiftUI
# 2. Compiler en mode Release pour le profilage
xcodebuild build -scheme VotreScheme -configuration Release
# 3. Effacer les données dérivées si vous enquêtez sur des problèmes d'aperçu
rm -rf ~/Library/Developer/Xcode/DerivedData
Coût en temps : 5 minutes Pourquoi : Une mauvaise version de Xcode ou le mode Debug produit des données de profilage trompeuses
Arbre de décision de diagnostic
Problème de vue SwiftUI après dépannage de base ?
│
├─ La vue ne se met pas à jour ?
│ ├─ Vérification basique : Ajoutez Self._printChanges() temporairement
│ │ ├─ Affiche "@self changed" → La valeur de la vue a changé
│ │ │ └─ Patron D1 : Analyser ce qui a provoqué la recréation de la vue
│ │ ├─ Affiche une propriété d'état spécifique → Cet état a déclenché la mise à jour
│ │ │ └─ Vérifier : Cet état doit-il déclencher une mise à jour ?
│ │ └─ Rien n'est enregistré → Le body n'est pas appelé du tout
│ │ └─ Patron D3 : Investigation de l'identité de la vue
│ └─ Avancé : Utiliser l'instrument SwiftUI
│ └─ Patron D2 : Investigation avec l'instrument SwiftUI
│
├─ La vue se met à jour trop souvent ?
│ ├─ Patron D1 : Analyse Self._printChanges()
│ │ └─ Identifier les dépendances d'état inutiles
│ └─ Patron D2 : Instrument SwiftUI → Graphe Cause & Effet
│ └─ Tracer le flux de données, trouver les dépendances larges
│
├─ Problèmes intermittents (fonctionne parfois) ?
│ ├─ Patron D3 : Investigation de l'identité de la vue
│ │ └─ Vérifier : L'identité change-t-elle de manière inattendue ?
│ ├─ Patron D4 : Vérification des dépendances d'environnement
│ │ └─ Vérifier : Les valeurs d'environnement changent-elles fréquemment ?
│ └─ Reproduire dans l'aperçu 30+ fois
│ └─ Si impossible à reproduire : Probablement un problème de timing/race condition
│
└─ L'aperçu (Preview) plante (après corrections de base) ?
├─ Patron D5 : Diagnostics d'aperçu (Xcode 26)
│ └─ Vérifier le bouton de diagnostics, les logs de crash
└─ Si échec persiste : Patron D2 (profilage de la compilation d'aperçu)
Patrons de diagnostic
Patron D1 : Analyse Self._printChanges()
Coût en temps : 5 minutes
Symptôme : Nécessité de comprendre exactement pourquoi le body de la vue s'exécute
Quand l'utiliser :
- Vue se met à jour plus souvent que prévu
- Vue ne se met pas à jour quand elle le devrait
- Vérification des dépendances après un refactoring
Technique :
struct MaVue: View {
@State private var compteur = 0
@Environment(ModeleApp.self) private var modele
var body: some View {
let _ = Self._printChanges() // Ajouter temporairement
VStack {
Text("Compteur : \(compteur)")
Text("Valeur du modèle : \(modele.valeur)")
}
}
}
Interprétation des résultats :
# Scénario 1 : Paramètre de vue changé
MaVue: @self changed
→ Le parent a passé une nouvelle instance MaVue
→ Vérifier le code parent - qu'est-ce qui a déclenché la recréation ?
# Scénario 2 : Propriété d'état changée
MaVue: compteur changed
→ @State local a déclenché la mise à jour
→ Attendu si vous avez modifié compteur
# Scénario 3 : Propriété d'environnement changée
MaVue: @self changed # L'environnement fait partie de @self
→ Une valeur d'environnement a changé (color scheme, locale, valeur personnalisée)
→ Patron D4 : Vérifier les dépendances d'environnement
# Scénario 4 : Rien n'est enregistré
→ Le body n'est pas appelé
→ Patron D3 : Investigation de l'identité de la vue
Découvertes courantes :
-
"@self changed" alors que vous ne vous y attendez pas
- Le parent recrée la vue inutilement
- Vérifier la gestion d'état du parent
-
Propriété affichée comme changée alors que vous ne l'avez pas modifiée
- Dépendance indirecte (lecture d'un objet qui a changé)
- Patron D2 : Utiliser Instruments pour tracer
-
Plusieurs propriétés changent ensemble
- Dépendance large (ex : lecture d'un tableau entier alors qu'un seul élément est nécessaire)
- Correction : Extraire la dépendance spécifique
Vérification :
- Supprimer l'appel
Self._printChanges()avant de commiter - Ne jamais livrer en production avec ce code
Référence croisée : Pour les cas complexes, utiliser le Patron D2 (Instrument SwiftUI)
Patron D2 : Investigation avec l'instrument SwiftUI
Coût en temps : 25 minutes
Symptôme : Modèles de mise à jour complexes que Self._printChanges() ne peut pas expliquer complètement
Quand l'utiliser :
- Plusieurs vues se mettent à jour alors qu'une seule devrait
- Nécessité de tracer le flux de données à travers l'application
- Des vues se mettent à jour mais vous ne savez pas quelle donnée a déclenché la mise à jour
- Mises à jour longues du body de la vue (problème de performance)
Prérequis :
- Xcode 26+ installé
- Appareil mis à jour vers iOS 26+ / macOS Tahoe+
- Compilation en mode Release
Étapes :
1. Lancer Instruments (5 min)
# Compiler en Release
xcodebuild build -scheme VotreScheme -configuration Release
# Lancer Instruments
# Appuyer sur Commande-I dans Xcode
# Choisir le modèle "SwiftUI"
2. Enregistrer une trace (3 min)
- Cliquer sur le bouton Enregistrer
- Effectuer l'action qui déclenche les mises à jour inattendues
- Arrêter l'enregistrement (10-30 secondes d'interaction suffisent)
3. Analyser les mises à jour longues du body de la vue (5 min)
- Regarder la voie Long View Body Updates
- Des barres orange/rouges ? Ce sont des vues coûteuses
- Cliquer sur une mise à jour longue → Le volet des détails montre le nom de la vue
- Clic droit → "Set Inspection Range and Zoom"
- Basculer sur la voie Time Profiler
- Trouver votre vue dans la pile d'appels
- Identifier l'opération coûteuse (création de formateur, calcul, etc.)
Correction : Déplacer l'opération coûteuse vers la couche modèle, mettre en cache le résultat
4. Analyser les mises à jour inutiles (7 min)
- Mettre en surbrillance la plage temporelle de l'action utilisateur (ex : appui sur un bouton favori)
- Développer la hiérarchie dans le volet des détails
- Compter les mises à jour — plus que prévu ?
- Survolez la vue → Cliquer sur la flèche → "Show Cause & Effect Graph"
5. Interpréter le graphe Cause & Effet (5 min)
Nœuds du graphe :
[Nœud bleu] = Votre code (geste, changement d'état, body de la vue)
[Nœud système] = Travail SwiftUI/système
[Flèche étiquetée "update"] = A causé cette mise à jour
[Flèche étiquetée "creation"] = A fait apparaître la vue
Patrons courants :
# Patron A : Une seule vue se met à jour (BON)
[Geste] → [Changement d'état dans ViewModelA] → [body de ViewA]
# Patron B : Toutes les vues se mettent à jour (MAUVAIS - dépendance large)
[Geste] → [Changement de tableau] → [Toutes les vues d'élément de liste se mettent à jour]
└─ Correction : Utiliser des view models granulaires, un par élément
# Patron C : Cascade via l'environnement (À VÉRIFIER)
[Changement d'état] → [Écriture dans l'environnement] → [De nombreux body de vues vérifient]
└─ Si la valeur d'environnement change fréquemment → Correction du Patron D4
Cliquer sur les nœuds :
- Nœud de changement d'état → Voir la backtrace de l'endroit où la valeur a été définie
- Nœud de body de vue → Voir quelles propriétés il a lues (dépendances)
Vérification :
- Enregistrer une nouvelle trace après la correction
- Comparer les comptes de mises à jour avant/après
- Vérifier que les barres rouges/oranges ont été réduites ou éliminées
Référence croisée : Compétence axiom-swiftui-performance pour des workflows détaillés avec Instruments
Patron D3 : Investigation de l'identité de la vue
Coût en temps : 15 minutes
Symptôme : Les valeurs @State se réinitialisent de manière inattendue, ou les vues ne s'animent pas
Quand l'utiliser :
- Le compteur se remet à 0 alors qu'il ne devrait pas
- Les animations ne fonctionnent pas (la vue apparaît brusquement au lieu de s'animer)
- Les éléments ForEach sautent
- Le champ de texte perd le focus
Cause racine : L'identité de la vue a changé de manière inattendue
Étapes d'investigation :
1. Vérifier le placement conditionnel (5 min)
// ❌ PROBLÈME : L'identité change avec la condition
if afficherDetails {
VueCompteur() // Obtient une nouvelle identité à chaque bascule de afficherDetails
}
// ✅ CORRECTION : Utiliser .opacity()
VueCompteur()
.opacity(afficherDetails ? 1 : 0) // Toujours la même identité
Trouver : Chercher dans le codebase les vues à l'intérieur de if/else qui conservent un état
2. Vérifier les modificateurs .id() (5 min)
// ❌ PROBLÈME : .id() change lorsque les données changent
VueDetail()
.id(element.id + "-\(estEnEdition)") // L'ID change avec estEnEdition
// ✅ CORRECTION : ID stable
VueDetail()
.id(element.id) // ID stable
Trouver : Chercher dans le codebase .id( — vérifier si les valeurs d'ID changent
3. Vérifier les identifiants ForEach (5 min)
// ❌ MAUVAIS : ID basé sur l'index
ForEach(Array(elements.enumerated()), id: \.offset) { index, element in
Texte(element.nom)
}
// ❌ MAUVAIS : ID non unique
ForEach(elements, id: \.categorie) { element in // Plusieurs éléments par catégorie
Texte(element.nom)
}
// ✅ BON : ID unique et stable
ForEach(elements, id: \.id) { element in
Texte(element.nom)
}
Trouver : Chercher ForEach — vérifier les ID uniques et stables
Patrons de correction :
| Problème | Correction |
|---|---|
| Vue dans un conditionnel | Utiliser .opacity() à la place |
| .id() change trop souvent | Utiliser un identifiant stable |
| ForEach sautent | Utiliser des ID uniques et stables (UUID ou ID serveur) |
| État réinitialisé lors de la navigation | Vérifier la gestion du chemin NavigationStack |
Vérification :
- Ajouter Self._printChanges() — ne devrait PAS voir "@self changed" de manière répétée
- Les animations devraient maintenant fonctionner correctement
- Les valeurs @State devraient persister
Patron D4 : Vérification des dépendances d'environnement
Coût en temps : 10 minutes
Symptôme : De nombreuses vues se mettent à jour alors que des données non liées changent
Quand l'utiliser :
- Le graphe Cause & Effet montre un nœud "Environment" déclenchant de nombreuses mises à jour
- Défilement lent ou performances d'animation
- Mises à jour en cascade inattendues
Cause racine : Valeur changeant fréquemment dans l'environnement OU trop de vues lisant l'environnement
Étapes d'investigation :
1. Trouver les écritures dans l'environnement (3 min)
# Chercher les modificateurs d'environnement dans le projet actuel
grep -r "\.environment(" --include="*.swift" .
Rechercher :
// ❌ MAUVAIS : Valeurs changeant fréquemment
.environment(\.scrollOffset, scrollOffset) // Se met à jour 60+ fois/seconde
.environment(modele) // Si le modèle se met à jour fréquemment
// ✅ BON : Valeurs stables
.environment(\.colorScheme, .dark)
.environment(modeleApp) // Si modeleApp change rarement
2. Vérifier ce qu'il y a dans l'environnement (3 min)
En utilisant le Patron D2 (Instruments), vérifier le graphe Cause & Effet :
- Cliquer sur le nœud "Environment"
- Voir quelles propriétés ont changé
- Compter combien de vues ont vérifié les mises à jour
Questions :
- Cette valeur change-t-elle à chaque image de défilement/animation ?
- Toutes ces vues ont-elles réellement besoin de cette valeur ?
3. Appliquer la correction (4 min)
Correction A : Supprimer de l'environnement (si change fréquemment) :
// ❌ Avant : Environnement
.environment(\.scrollOffset, scrollOffset)
// ✅ Après : Paramètre direct
VueEnfant(scrollOffset: scrollOffset)
Correction B : Utiliser un modèle @Observable (si nécessaire pour de nombreuses vues) :
// Au lieu de stocker une primitive dans l'environnement :
@Observable class ModeleDefilement {
var offset: CGFloat = 0
}
// Les vues dépendent de propriétés spécifiques :
@Environment(ModeleDefilement.self) private var modeleDefilement
var body: some View {
Texte("\(modeleDefilement.offset)") // Se met à jour uniquement lorsque offset change
}
Vérification :
- Enregistrer une nouvelle trace dans Instruments
- Vérifier le graphe Cause & Effet — moins de vues devraient se mettre à jour
- Les performances devraient s'améliorer (défilement/animations plus fluides)
Patron D5 : Diagnostics d'aperçu (Xcode 26)
Coût en temps : 10 minutes
Symptôme : L'aperçu (Preview) ne se charge pas ou plante avec une erreur peu claire
Quand l'utiliser :
- L'aperçu échoue après les corrections de base (compétence swiftui-debugging)
- Le message d'erreur est peu clair ou générique
- L'aperçu fonctionnait avant, s'est arrêté soudainement
Étapes d'investigation :
1. Utiliser le bouton de diagnostics d'aperçu (2 min)
Emplacement : Menu Éditeur → Canvas → Diagnostics
Ce qu'il affiche :
- Messages d'erreur détaillés
- Dépendances manquantes
- Problèmes d'initialisation d'état
- Problèmes spécifiques à l'aperçu
2. Vérifier les logs de crash (3 min)
# Ouvrir le répertoire des logs de crash
open ~/Library/Logs/DiagnosticReports/
# Chercher les fichiers .crash récents contenant "Preview"
ls -lt ~/Library/Logs/DiagnosticReports/ | grep -i preview | head -5
Ce qu'il faut rechercher :
- Erreurs fatales (hors limites du tableau, force unwrap nil)
- Importations de modules manquantes
- Échecs d'initialisation du framework
3. Isoler le problème (5 min)
Créer un aperçu minimal :
// Commencer avec un aperçu vide
#Preview {
Texte("Test")
}
// Si cela fonctionne, ajouter progressivement :
#Preview {
MaVue() // Votre vue réelle, mais avec des données fictives
.environment(ModeleFictif()) // Fournir toutes les dépendances
}
// Trouver quelle dépendance provoque le crash
Problèmes courants :
| Erreur | Cause | Correction |
|---|---|---|
| "Cannot find in scope" | Dépendance manquante | Ajouter à l'aperçu (voir exemple ci-dessous) |
| "Fatal error: Unexpectedly found nil" | Optionnel déballé a échoué | Fournir une valeur non nulle dans l'aperçu |
| "No such module" | Importation manquante | Ajouter une instruction import |
| Crash silencieux (pas d'erreur) | Initialisation d'état avec valeur invalide | Utiliser des valeurs par défaut sûres |
Patrons de correction :
// @Environment manquant
#Preview {
ContentView()
.environment(ModeleApp()) // Fournir la dépendance
}
// @EnvironmentObject manquant (pré-iOS 17)
#Preview {
ContentView()
.environmentObject(ModeleApp())
}
// ModelContainer manquant (SwiftData)
#Preview {
let config = ModelConfiguration(isStoredInMemoryOnly: true)
let conteneur = try! ModelContainer(for: Element.self, configurations: config)
ElementListe()
.modelContainer(conteneur)
}
Vérification :
- L'aperçu se charge et fonctionne de manière fiable
- Ne plus voir d'erreurs dans le panneau de l'aperçu
- Tester avec différentes données pour confirmer la robustesse
Référence rapide
| Patron | Symptôme | Temps | Instrument clé |
|---|---|---|---|
| D1 | Mises à jour inattendues des vues | 5 min | Self._printChanges() |
| D2 | Modèles de mise à jour complexes | 25 min | Instrument SwiftUI |
| D3 | Réinitialisation d'état, problèmes d'animation | 15 min | Vérification du code |
| D4 | Trop de vues se mettent à jour | 10 min | Graphe Cause & Effet |
| D5 | Crashs d'aperçu | 10 min | Diagnostics d'aperçu |
Règle d'or
"Comprenez pourquoi cela fonctionne maintenant"
Ne vous arrêtez pas lorsque l'aperçu se charge ou que le test réussit. Comprendre pourquoi la correction a fonctionné est ce qui empêche le prochain bogue. Si vous ne pouvez pas expliquer pourquoi cela a fonctionné, vous n'avez pas terminé.
Contenu adapté de la compétence axiom-ai-claude-skills