Diagnóstico de Depuración SwiftUI
Cuándo usar este skill de diagnóstico
Usa este skill cuando:
- La solución básica falló — Aplicaste los patrones del skill
axiom-swiftui-debuggingpero el problema persiste Self._printChanges()muestra patrones inesperados — La vista se actualiza cuando no debería, o no se actualiza cuando debería- Problemas intermitentes — Funciona a veces, falla otras veces ("heisenbug")
- Cadenas de dependencia complejas — Necesitas rastrear el flujo de datos a través de múltiples vistas/modelos
- Investigación de rendimiento — Las vistas se actualizan demasiado seguido o tardan demasiado
- Misterios en la vista previa (preview) — Bloqueos o fallos que no son inmediatamente evidentes
Acciones PROHIBIDAS
Bajo presión, te sentirás tentado a tomar atajos que ocultan problemas en lugar de diagnosticarlos. NUNCA hagas esto:
❌ Adivinar con cambios aleatorios de @State/@Observable
- "Déjame probar añadiendo @Observable aquí y ver si funciona"
- "Quizás si cambio esto a @StateObject se soluciona"
❌ Usar .id(UUID()) para forzar actualizaciones
- Crea una nueva identidad de vista en cada renderizado
- Destruye la preservación del estado
- Enmascara la causa raíz
❌ Usar ObservableObject cuando @Observable funcionaría (iOS 17+)
- Añade complejidad innecesaria
- Pierdes el seguimiento automático de dependencias
❌ Ignorar problemas intermitentes ("funciona a veces")
- "Solo lo fusionaré y espero que no ocurra en producción"
- Intermitente = error sistemático, no aleatoriedad
❌ Enviar sin entender
- "La corrección funciona, no sé por qué"
- La producción es demasiado costosa para prueba y error
Pasos Obligatorios Iniciales
Antes de sumergirte en los patrones de diagnóstico, establece el entorno base:
# 1. Verificar la configuración de Instruments
xcodebuild -version # Debe ser Xcode 26+ para el instrumento SwiftUI
# 2. Compilar en modo Release para perfilado
xcodebuild build -scheme TuEsquema -configuration Release
# 3. Borrar datos derivados si investigas problemas de vista previa
rm -rf ~/Library/Developer/Xcode/DerivedData
Costo de tiempo: 5 minutos Por qué: Una versión incorrecta de Xcode o el modo Debug produce datos de perfilado engañosos
Árbol de Decisión de Diagnóstico
¿Problema de vista SwiftUI después de solución básica?
│
├─ ¿La vista no se actualiza?
│ ├─ Verificación básica: Añadir Self._printChanges() temporalmente
│ │ ├─ Muestra "@self changed" → El valor de la vista cambió
│ │ │ └─ Patrón D1: Analizar qué causó la recreación de la vista
│ │ ├─ Muestra una propiedad de estado específica → Ese estado activó la actualización
│ │ │ └─ Verificar: ¿Debería ese estado activar la actualización?
│ │ └─ Nada registrado → El cuerpo no se está llamando en absoluto
│ │ └─ Patrón D3: Investigación de identidad de vista
│ └─ Avanzado: Usar el instrumento SwiftUI
│ └─ Patrón D2: Investigación con el instrumento SwiftUI
│
├─ ¿La vista se actualiza demasiado seguido?
│ ├─ Patrón D1: Análisis con Self._printChanges()
│ │ └─ Identificar dependencias de estado innecesarias
│ └─ Patrón D2: Instrumento SwiftUI → Gráfico de causa y efecto
│ └─ Rastrear flujo de datos, encontrar dependencias amplias
│
├─ ¿Problemas intermitentes (funciona a veces)?
│ ├─ Patrón D3: Investigación de identidad de vista
│ │ └─ Verificar: ¿Cambia la identidad inesperadamente?
│ ├─ Patrón D4: Verificación de dependencias del entorno
│ │ └─ Verificar: ¿Los valores del entorno cambian con frecuencia?
│ └─ Reproducir en vista previa 30+ veces
│ └─ Si no se puede reproducir: Probablemente problema de sincronización/condición de carrera
│
└─ ¿Bloqueos en vista previa (después de correcciones básicas)?
├─ Patrón D5: Diagnóstico de vista previa (Xcode 26)
│ └─ Verificar botón de diagnóstico, registros de bloqueo
└─ Si aún falla: Patrón D2 (perfilar compilación de vista previa)
Patrones de Diagnóstico
Patrón D1: Análisis con Self._printChanges()
Costo de tiempo: 5 minutos
Síntoma: Necesitas entender exactamente por qué se ejecuta el cuerpo de la vista
Cuándo usarlo:
- La vista se actualiza más seguido de lo esperado
- La vista no se actualiza cuando debería
- Verificar dependencias después de refactorizar
Técnica:
struct MiVista: View {
@State private var contador = 0
@Environment(ModeloApp.self) private var modelo
var body: some View {
let _ = Self._printChanges() // Añadir temporalmente
VStack {
Text("Contador: \(contador)")
Text("Valor del modelo: \(modelo.valor)")
}
}
}
Interpretación de la salida:
# Escenario 1: El parámetro de la vista cambió
MiVista: @self changed
→ El padre pasó una nueva instancia de MiVista
→ Verificar el código del padre: ¿qué activó la recreación?
# Escenario 2: Una propiedad de estado cambió
MiVista: contador changed
→ El @State local activó la actualización
→ Esperado si modificaste el contador
# Escenario 3: Una propiedad del entorno cambió
MiVista: @self changed # El entorno es parte de @self
→ Un valor del entorno cambió (esquema de color, configuración regional, valor personalizado)
→ Patrón D4: Verificar dependencias del entorno
# Escenario 4: Nada registrado
→ El cuerpo no se está llamando
→ Patrón D3: Investigación de identidad de vista
Descubrimientos comunes:
-
"@self changed" cuando no lo esperas
- El padre recrea la vista innecesariamente
- Verificar la gestión de estado del padre
-
La propiedad cambió pero no la cambiaste
- Dependencia indirecta (leyendo de un objeto que cambió)
- Patrón D2: Usar Instruments para rastrear
-
Múltiples propiedades cambiando juntas
- Dependencia amplia (ej., leyendo todo un arreglo cuando solo necesitas un elemento)
- Corrección: Extraer dependencia específica
Verificación:
- Eliminar la llamada a
Self._printChanges()antes de hacer commit - Nunca enviar a producción con este código
Referencia cruzada: Para casos complejos, usar Patrón D2 (Instrumento SwiftUI)
Patrón D2: Investigación con el Instrumento SwiftUI
Costo de tiempo: 25 minutos
Síntoma: Patrones de actualización complejos que Self._printChanges() no puede explicar completamente
Cuándo usarlo:
- Múltiples vistas se actualizan cuando solo una debería
- Necesitas rastrear el flujo de datos a través de la aplicación
- Las vistas se actualizan pero no sabes qué dato las activó
- Actualizaciones largas del cuerpo de la vista (problema de rendimiento)
Requisitos previos:
- Xcode 26+ instalado
- Dispositivo actualizado a iOS 26+ / macOS Tahoe+
- Compilar en modo Release
Pasos:
1. Iniciar Instruments (5 min)
# Compilar Release
xcodebuild build -scheme TuEsquema -configuration Release
# Iniciar Instruments
# Presiona Comando-I en Xcode
# Elige la plantilla "SwiftUI"
2. Grabar traza (3 min)
- Haz clic en el botón Grabar
- Realiza la acción que activa las actualizaciones inesperadas
- Detén la grabación (10-30 segundos de interacción son suficientes)
3. Analizar actualizaciones largas del cuerpo de la vista (5 min)
- Mira en el carril Long View Body Updates
- ¿Hay barras naranjas/rojas? Esas son vistas costosas
- Haz clic en una actualización larga → El panel de detalle muestra el nombre de la vista
- Haz clic derecho → "Establecer rango de inspección y acercar"
- Cambia a la pista Time Profiler
- Encuentra tu vista en la pila de llamadas
- Identifica la operación costosa (creación de formateador, cálculo, etc.)
Corrección: Mueve la operación costosa a la capa del modelo, almacena en caché el resultado
4. Analizar actualizaciones innecesarias (7 min)
- Resalta el rango de tiempo de la acción del usuario (ej., tocar botón de favorito)
- Expande la jerarquía en el panel de detalle
- Cuenta las actualizaciones — ¿más de las esperadas?
- Pasa el cursor sobre la vista → Haz clic en la flecha → "Mostrar gráfico de causa y efecto"
5. Interpretar el gráfico de causa y efecto (5 min)
Nodos del gráfico:
[Nodo azul] = Tu código (gesto, cambio de estado, cuerpo de vista)
[Nodo del sistema] = SwiftUI/trabajo del sistema
[Flecha etiquetada "update"] = Causó esta actualización
[Flecha etiquetada "creation"] = Causó que la vista apareciera
Patrones comunes:
# Patrón A: Una sola vista se actualiza (BUENO)
[Gesto] → [Cambio de estado en ViewModelA] → [Cuerpo de VistaA]
# Patrón B: Todas las vistas se actualizan (MALO - dependencia amplia)
[Gesto] → [Cambio de arreglo] → [Todas las vistas de elementos de la lista se actualizan]
└─ Corrección: Usar modelos de vista granulares, uno por elemento
# Patrón C: Cascada a través del entorno (VERIFICAR)
[Cambio de estado] → [Escritura en entorno] → [Muchos cuerpos de vista verifican]
└─ Si el valor del entorno cambia con frecuencia → Corrección del Patrón D4
Haz clic en los nodos:
- Nodo de cambio de estado → Ver el backtrace de dónde se estableció el valor
- Nodo de cuerpo de vista → Ver qué propiedades leyó (dependencias)
Verificación:
- Grabar una nueva traza después de la corrección
- Comparar conteos de actualizaciones antes/después
- Verificar que las barras rojas/naranjas se redujeron o eliminaron
Referencia cruzada: Skill axiom-swiftui-performance para flujos de trabajo detallados con Instruments
Patrón D3: Investigación de Identidad de Vista
Costo de tiempo: 15 minutos
Síntoma: Los valores de @State se restablecen inesperadamente, o las vistas no animan
Cuándo usarlo:
- El contador se restablece a 0 cuando no debería
- Las animaciones no funcionan (la vista aparece de golpe en lugar de animarse)
- Los elementos de ForEach saltan
- El campo de texto pierde el foco
Causa raíz: La identidad de la vista cambió inesperadamente
Pasos de investigación:
1. Verificar colocación condicional (5 min)
// ❌ PROBLEMA: La identidad cambia con la condición
if mostrarDetalles {
VistaContador() // Obtiene nueva identidad cada vez que se alterna mostrarDetalles
}
// ✅ CORRECCIÓN: Usar .opacity()
VistaContador()
.opacity(mostrarDetalles ? 1 : 0) // Siempre la misma identidad
Encontrar: Busca en el código base vistas dentro de if/else que mantienen estado
2. Verificar modificadores .id() (5 min)
// ❌ PROBLEMA: .id() cambia cuando los datos cambian
VistaDetalle()
.id(elemento.id + "-\(estáEditando)") // ID cambia con estáEditando
// ✅ CORRECCIÓN: ID estable
VistaDetalle()
.id(elemento.id) // ID estable
Encontrar: Busca en el código base .id( — verifica si los valores de ID cambian
3. Verificar identificadores de ForEach (5 min)
// ❌ INCORRECTO: ID basado en índice
ForEach(Array(elementos.enumerated()), id: \.offset) { indice, elemento in
Text(elemento.nombre)
}
// ❌ INCORRECTO: ID no único
ForEach(elementos, id: \.categoria) { elemento in // Múltiples elementos por categoría
Text(elemento.nombre)
}
// ✅ CORRECTO: ID único y estable
ForEach(elementos, id: \.id) { elemento in
Text(elemento.nombre)
}
Encontrar: Busca ForEach — verifica IDs únicas y estables
Patrones de corrección:
| Problema | Corrección |
|---|---|
| Vista en condicional | Usar .opacity() en su lugar |
| .id() cambia demasiado seguido | Usar identificador estable |
| ForEach saltando | Usar IDs únicas y estables (UUID o ID del servidor) |
| Estado se restablece en navegación | Verificar gestión de la ruta de NavigationStack |
Verificación:
- Añadir Self._printChanges() — NO deberías ver "@self changed" repetidamente
- Las animaciones deberían funcionar sin problemas
- Los valores de @State deberían persistir
Patrón D4: Verificación de Dependencias del Entorno
Costo de tiempo: 10 minutos
Síntoma: Muchas vistas se actualizan cuando cambian datos no relacionados
Cuándo usarlo:
- El gráfico de causa y efecto muestra un nodo "Environment" que activa muchas actualizaciones
- Rendimiento lento en desplazamiento o animaciones
- Actualizaciones en cascada inesperadas
Causa raíz: Un valor que cambia con frecuencia en el entorno O demasiadas vistas leyendo el entorno
Pasos de investigación:
1. Encontrar escrituras en el entorno (3 min)
# Buscar modificadores de entorno en el proyecto actual
find . -name "*.swift" -exec grep -l "\.environment(" {} \;
Buscar:
// ❌ MALO: Valores que cambian con frecuencia
.environment(\.desplazamientoScroll, desplazamientoScroll) // Se actualiza 60+ veces/segundo
.environment(modelo) // Si el modelo se actualiza con frecuencia
// ✅ BUENO: Valores estables
.environment(\.esquemaColor, .oscuro)
.environment(modeloApp) // Si modeloApp cambia raramente
2. Verificar qué hay en el entorno (3 min)
Usando el Patrón D2 (Instruments), verifica el gráfico de causa y efecto:
- Haz clic en el nodo "Environment"
- Mira qué propiedades cambiaron
- Cuenta cuántas vistas verificaron si hay actualizaciones
Preguntas:
- ¿Este valor cambia en cada fotograma de desplazamiento/animación?
- ¿Todas estas vistas realmente necesitan este valor?
3. Aplicar corrección (4 min)
Corrección A: Eliminar del entorno (si cambia con frecuencia):
// ❌ Antes: Entorno
.environment(\.desplazamientoScroll, desplazamientoScroll)
// ✅ Después: Parámetro directo
VistaHija(desplazamientoScroll: desplazamientoScroll)
Corrección B: Usar modelo @Observable (si lo necesitan muchas vistas):
// En lugar de almacenar un primitivo en el entorno:
@Observable class ModeloScrollView {
var desplazamiento: CGFloat = 0
}
// Las vistas dependen de propiedades específicas:
@Environment(ModeloScrollView.self) private var modeloVista
var body: some View {
Text("\(modeloVista.desplazamiento)") // Solo se actualiza cuando cambia el desplazamiento
}
Verificación:
- Grabar una nueva traza en Instruments
- Verificar el gráfico de causa y efecto — menos vistas deberían actualizarse
- El rendimiento debería mejorar (desplazamiento/animaciones más suaves)
Patrón D5: Diagnóstico de Vista Previa (Xcode 26)
Costo de tiempo: 10 minutos
Síntoma: La vista previa no carga o se bloquea con un error poco claro
Cuándo usarlo:
- La vista previa falla después de correcciones básicas (skill swiftui-debugging)
- El mensaje de error es poco claro o genérico
- La vista previa funcionaba antes, dejó de funcionar repentinamente
Pasos de investigación:
1. Usar el botón de Diagnóstico de Vista Previa (2 min)
Ubicación: Menú Editor → Canvas → Diagnostics
Qué muestra:
- Mensajes de error detallados
- Dependencias faltantes
- Problemas de inicialización de estado
- Problemas específicos de vista previa
2. Verificar registros de bloqueo (3 min)
# Abrir el directorio de registros de bloqueo
open ~/Library/Logs/DiagnosticReports/
# Buscar archivos .crash recientes que contengan "Preview"
ls -lt ~/Library/Logs/DiagnosticReports/ | grep -i preview | head -5
Qué buscar:
- Errores fatales (arreglo fuera de límites, force unwrap nil)
- Importaciones de módulos faltantes
- Fallos de inicialización del framework
3. Aislar el problema (5 min)
Crear vista previa mínima:
// Comenzar con una vista previa vacía
#Preview {
Text("Prueba")
}
// Si esto funciona, añadir gradualmente:
#Preview {
MiVista() // Tu vista real, pero con datos simulados
.environment(ModeloSimulado()) // Proporcionar todas las dependencias
}
// Encontrar qué dependencia causa el bloqueo
Problemas comunes:
| Error | Causa | Corrección |
|---|---|---|
| "Cannot find in scope" | Dependencia faltante | Añadir a la vista previa (ver ejemplo abajo) |
| "Fatal error: Unexpectedly found nil" | Optional unwrap fallido | Proporcionar valor no nil en la vista previa |
| "No such module" | Importación faltante | Añadir declaración import |
| Bloqueo silencioso (sin error) | Inicialización de estado con valor inválido | Usar valores predeterminados seguros |
Patrones de corrección:
// @Environment faltante
#Preview {
VistaPrincipal()
.environment(ModeloApp()) // Proporcionar dependencia
}
// @EnvironmentObject faltante (pre-iOS 17)
#Preview {
VistaPrincipal()
.environmentObject(ModeloApp())
}
// ModelContainer faltante (SwiftData)
#Preview {
let config = ModelConfiguration(isStoredInMemoryOnly: true)
let container = try! ModelContainer(for: ModeloElemento.self, configurations: config)
VistaListaElementos()
.modelContainer(container)
}
Verificación:
- La vista previa debería cargarse y mostrarse correctamente
- Interactúa con ella 10+ veces para verificar estabilidad
Referencia cruzada: Patrón D2 (Instrumento SwiftUI) para vista previa con perfilado de rendimiento