Diagnóstico de Depuração SwiftUI
Quando Usar Esta Skill de Diagnóstico
Use esta skill quando:
- A solução básica de problemas falhou — Padrões da skill
axiom-swiftui-debuggingforam aplicados, mas o problema persiste - Self._printChanges() mostra padrões inesperados — View atualizando quando não deveria, ou não atualizando quando deveria
- Problemas intermitentes — Funciona às vezes, falha em outras vezes ("heisenbug")
- Cadeias de dependência complexas — Necessidade de rastrear o fluxo de dados através de várias views/modelos
- Investigação de desempenho — Views atualizando com muita frequência ou demorando muito
- Mistérios de preview — Travamentos ou falhas que não são imediatamente óbvios
Ações PROIBIDAS
Sob pressão, você será tentado a usar atalhos que escondem problemas em vez de diagnosticá-los. NUNCA faça estas coisas:
❌ Adivinhar com mudanças aleatórias de @State/@Observable
- "Deixe-me tentar adicionar @Observable aqui e ver se funciona"
- "Talvez se eu mudar isso para @StateObject, vai corrigir"
❌ Adicionar .id(UUID()) para forçar atualizações
- Cria uma nova identidade de view a cada renderização
- Destrói a preservação de estado
- Mascara a causa raiz
❌ Usar ObservableObject quando @Observable funcionaria (iOS 17+)
- Adiciona complexidade desnecessária
- Perde o rastreamento automático de dependências
❌ Ignorar problemas intermitentes ("funciona às vezes")
- "Vou apenas fazer o merge e torcer para que não aconteça em produção"
- Intermitente = bug sistemático, não aleatoriedade
❌ Enviar sem entender
- "A correção funciona, não sei porquê"
- Produção é cara demais para tentativa e erro
Etapas Obrigatórias Iniciais
Antes de mergulhar nos padrões de diagnóstico, estabeleça o ambiente de linha de base:
# 1. Verificar configuração do Instruments
xcodebuild -version # Deve ser Xcode 26+ para o Instrument SwiftUI
# 2. Construir no modo Release para perfilamento
xcodebuild build -scheme SeuEsquema -configuration Release
# 3. Limpar dados derivados se estiver investigando problemas de preview
rm -rf ~/Library/Developer/Xcode/DerivedData
Custo de tempo: 5 minutos Porquê: Versão errada do Xcode ou modo Debug produz dados de perfilamento enganosos
Árvore de Decisão de Diagnóstico
Problema de view SwiftUI após solução básica?
│
├─ View não está atualizando?
│ ├─ Verificação básica: Adicionar Self._printChanges() temporariamente
│ │ ├─ Mostra "@self changed" → Valor da view mudou
│ │ │ └─ Padrão D1: Analisar o que causou a recriação da view
│ │ ├─ Mostra propriedade de estado específica → Esse estado acionou a atualização
│ │ │ └─ Verificar: Esse estado deveria acionar a atualização?
│ │ └─ Nada registrado → Body não está sendo chamado
│ │ └─ Padrão D3: Investigação de Identidade de View
│ └─ Avançado: Usar SwiftUI Instrument
│ └─ Padrão D2: Investigação com SwiftUI Instrument
│
├─ View atualizando com muita frequência?
│ ├─ Padrão D1: Análise de Self._printChanges()
│ │ └─ Identificar dependências de estado desnecessárias
│ └─ Padrão D2: SwiftUI Instrument → Gráfico de Causa e Efeito
│ └─ Rastrear fluxo de dados, encontrar dependências amplas
│
├─ Problemas intermitentes (funciona às vezes)?
│ ├─ Padrão D3: Investigação de Identidade de View
│ │ └─ Verificar: A identidade muda inesperadamente?
│ ├─ Padrão D4: Verificação de Dependências de Ambiente
│ │ └─ Verificar: Valores de ambiente mudando com frequência?
│ └─ Reproduzir no preview 30+ vezes
│ └─ Se não conseguir reproduzir: Provavelmente condição de corrida/timing
│
└─ Preview trava (após correções básicas)?
├─ Padrão D5: Diagnóstico de Preview (Xcode 26)
│ └─ Verificar botão de diagnóstico, logs de travamento
└─ Se ainda falhar: Padrão D2 (perfilamento da build de preview)
Padrões de Diagnóstico
Padrão D1: Análise de Self._printChanges()
Custo de tempo: 5 minutos
Sintoma: Necessidade de entender exatamente por que o body da view é executado
Quando usar:
- View atualizando com mais frequência do que o esperado
- View não atualizando quando deveria
- Verificando dependências após refatoração
Técnica:
struct MinhaView: View {
@State private var contador = 0
@Environment(AppModel.self) private var modelo
var body: some View {
let _ = Self._printChanges() // Adicionar temporariamente
VStack {
Text("Contador: \(contador)")
Text("Valor do modelo: \(modelo.valor)")
}
}
}
Interpretação da saída:
# Cenário 1: Parâmetro da view mudou
MinhaView: @self changed
→ Pai passou nova instância de MinhaView
→ Verificar código pai - o que acionou a recriação?
# Cenário 2: Propriedade de estado mudou
MinhaView: contador changed
→ @State local acionou a atualização
→ Esperado se você modificou contador
# Cenário 3: Propriedade de ambiente mudou
MinhaView: @self changed # Ambiente faz parte de @self
→ Valor de ambiente mudou (esquema de cores, localidade, valor personalizado)
→ Padrão D4: Verificar dependências de ambiente
# Cenário 4: Nada registrado
→ Body não está sendo chamado
→ Padrão D3: Investigação de identidade de view
Descobertas comuns:
-
"@self changed" quando você não espera
- Pai recriando a view desnecessariamente
- Verificar gerenciamento de estado do pai
-
Propriedade mostra alteração, mas você não a alterou
- Dependência indireta (lendo de um objeto que mudou)
- Padrão D2: Usar Instruments para rastrear
-
Várias propriedades mudando juntas
- Dependência ampla (ex.: lendo array inteiro quando só precisa de um item)
- Correção: Extrair dependência específica
Verificação:
- Remover a chamada
Self._printChanges()antes de commitar - Nunca enviar para produção com este código
Referência cruzada: Para casos complexos, usar Padrão D2 (SwiftUI Instrument)
Padrão D2: Investigação com SwiftUI Instrument
Custo de tempo: 25 minutos
Sintoma: Padrões de atualização complexos que Self._printChanges() não consegue explicar completamente
Quando usar:
- Várias views atualizando quando apenas uma deveria
- Necessidade de rastrear fluxo de dados através do aplicativo
- Views atualizando sem saber qual dado acionou
- Atualizações longas do body da view (problema de desempenho)
Pré-requisitos:
- Xcode 26+ instalado
- Dispositivo atualizado para iOS 26+ / macOS Tahoe+
- Construir no modo Release
Passos:
1. Iniciar Instruments (5 min)
# Construir Release
xcodebuild build -scheme SeuEsquema -configuration Release
# Iniciar Instruments
# Pressione Command-I no Xcode
# Escolher template "SwiftUI"
2. Gravar Traço (3 min)
- Clicar no botão Gravar
- Realizar a ação que aciona atualizações inesperadas
- Parar a gravação (10-30 segundos de interação são suficientes)
3. Analisar Atualizações Longas de Body de View (5 min)
- Olhar a faixa Long View Body Updates
- Alguma barra laranja/vermelha? Essas são views caras
- Clicar em uma atualização longa → Painel de detalhes mostra o nome da view
- Clicar com o botão direito → "Set Inspection Range and Zoom"
- Alternar para a faixa Time Profiler
- Encontrar sua view na pilha de chamadas
- Identificar operação cara (criação de formatador, cálculo, etc.)
Correção: Mover operação cara para a camada de modelo, armazenar resultado em cache
4. Analisar Atualizações Desnecessárias (7 min)
- Destacar intervalo de tempo da ação do usuário (ex.: tocar no botão de favoritar)
- Expandir hierarquia no painel de detalhes
- Contar atualizações — mais do que o esperado?
- Passar o mouse sobre a view → Clicar na seta → "Show Cause & Effect Graph"
5. Interpretar Gráfico de Causa e Efeito (5 min)
Nós do gráfico:
[Nó azul] = Seu código (gesto, mudança de estado, body da view)
[Nó de sistema] = Trabalho do SwiftUI/sistema
[Seta rotulada "update"] = Causou esta atualização
[Seta rotulada "creation"] = Fez a view aparecer
Padrões comuns:
# Padrão A: Atualização de view única (BOM)
[Gesto] → [Mudança de Estado no ViewModelA] → [Body da ViewA]
# Padrão B: Todas as views atualizam (RUIM - dependência ampla)
[Gesto] → [Mudança no array] → [Todas as views dos itens da lista atualizam]
└─ Correção: Usar view models granulares, um por item
# Padrão C: Cascata através do ambiente (VERIFICAR)
[Mudança de Estado] → [Escrita no ambiente] → [Muitos bodies de view verificam]
└─ Se o valor do ambiente muda com frequência → Correção do Padrão D4
Clicar nos nós:
- Nó de mudança de estado → Ver backtrace de onde o valor foi definido
- Nó de body de view → Ver quais propriedades leu (dependências)
Verificação:
- Gravar novo traço após a correção
- Comparar contagens de atualização antes/depois
- Verificar se barras vermelhas/laranjas foram reduzidas ou eliminadas
Referência cruzada: Skill axiom-swiftui-performance para fluxos de trabalho detalhados do Instruments
Padrão D3: Investigação de Identidade de View
Custo de tempo: 15 minutos
Sintoma: Valores de @State resetados inesperadamente, ou views não animam
Quando usar:
- Contador reseta para 0 quando não deveria
- Animações não funcionam (view aparece de repente em vez de animar)
- Itens do ForEach pulam
- Campo de texto perde foco
Causa raiz: Identidade da view mudou inesperadamente
Passos de investigação:
1. Verificar posicionamento condicional (5 min)
// ❌ PROBLEMA: Identidade muda com a condição
if mostrarDetalhes {
CounterView() // Ganha nova identidade cada vez que mostrarDetalhes alterna
}
// ✅ CORREÇÃO: Usar .opacity()
CounterView()
.opacity(mostrarDetalhes ? 1 : 0) // Mesma identidade sempre
Encontrar: Pesquisar no código por views dentro de if/else que contêm estado
2. Verificar modificadores .id() (5 min)
// ❌ PROBLEMA: .id() muda quando os dados mudam
DetailView()
.id(item.id + "-\(estahEditando)") // ID muda com estahEditando
// ✅ CORREÇÃO: ID estável
DetailView()
.id(item.id) // ID estável
Encontrar: Pesquisar no código por .id( — verificar se os valores de ID mudam
3. Verificar identificadores do ForEach (5 min)
// ❌ ERRADO: ID baseado em índice
ForEach(Array(items.enumerated()), id: \.offset) { index, item in
Text(item.nome)
}
// ❌ ERRADO: ID não único
ForEach(items, id: \.categoria) { item in // Múltiplos itens por categoria
Text(item.nome)
}
// ✅ CERTO: ID único e estável
ForEach(items, id: \.id) { item in
Text(item.nome)
}
Encontrar: Pesquisar por ForEach — verificar IDs únicos e estáveis
Padrões de correção:
| Problema | Correção |
|---|---|
| View em condicional | Usar .opacity() em vez disso |
| .id() muda com muita frequência | Usar identificador estável |
| ForEach pulando | Usar IDs únicos e estáveis (UUID ou ID do servidor) |
| Estado reseta na navegação | Verificar gerenciamento do caminho do NavigationStack |
Verificação:
- Adicionar Self._printChanges() — NÃO deve ver "@self changed" repetidamente
- Animações devem agora funcionar suavemente
- Valores de @State devem persistir
Padrão D4: Verificação de Dependências de Ambiente
Custo de tempo: 10 minutos
Sintoma: Muitas views atualizando quando dados não relacionados mudam
Quando usar:
- Gráfico de Causa e Efeito mostra nó "Environment" acionando muitas atualizações
- Rolagem lenta ou desempenho de animação
- Atualizações em cascata inesperadas
Causa raiz: Valor que muda com frequência no ambiente OU muitas views lendo o ambiente
Passos de investigação:
1. Encontrar escritas no ambiente (3 min)
# Pesquisar por modificadores de ambiente no projeto atual
grep -r "\.environment(" --include="*.swift" .
Procurar por:
// ❌ RUIM: Valores que mudam com frequência
.environment(\.scrollOffset, scrollOffset) // Atualiza 60+ vezes/segundo
.environment(modelo) // Se o modelo atualiza com frequência
// ✅ BOM: Valores estáveis
.environment(\.colorScheme, .dark)
.environment(appModel) // Se appModel raramente muda
2. Verificar o que está no ambiente (3 min)
Usando Padrão D2 (Instruments), verificar o Gráfico de Causa e Efeito:
- Clicar no nó "Environment"
- Ver quais propriedades mudaram
- Contar quantas views verificaram por atualizações
Perguntas:
- Este valor está mudando a cada quadro de rolagem/animação?
- Todas essas views realmente precisam deste valor?
3. Aplicar correção (4 min)
Correção A: Remover do ambiente (se muda com frequência):
// ❌ Antes: Ambiente
.environment(\.scrollOffset, scrollOffset)
// ✅ Depois: Parâmetro direto
ChildView(scrollOffset: scrollOffset)
Correção B: Usar modelo @Observable (se necessário por muitas views):
// Em vez de armazenar primitivo no ambiente:
@Observable class ScrollViewModel {
var offset: CGFloat = 0
}
// Views dependem de propriedades específicas:
@Environment(ScrollViewModel.self) private var viewModel
var body: some View {
Text("\(viewModel.offset)") // Só atualiza quando offset muda
}
Verificação:
- Gravar novo traço no Instruments
- Verificar Gráfico de Causa e Efeito — menos views devem atualizar
- Desempenho deve melhorar (rolagem/animações mais suaves)
Padrão D5: Diagnóstico de Preview (Xcode 26)
Custo de tempo: 10 minutos
Sintoma: Preview não carrega ou trava com erro pouco claro
Quando usar:
- Preview falha após correções básicas (skill swiftui-debugging)
- Mensagem de erro pouco clara ou genérica
- Preview funcionava antes, parou de repente
Passos de investigação:
1. Usar Botão de Diagnóstico de Preview (2 min)
Localização: Menu Editor → Canvas → Diagnostics
O que mostra:
- Mensagens de erro detalhadas
- Dependências ausentes
- Problemas de inicialização de estado
- Problemas específicos de preview
2. Verificar logs de travamento (3 min)
# Abrir diretório de logs de travamento
open ~/Library/Logs/DiagnosticReports/
# Procurar por arquivos .crash recentes contendo "Preview"
ls -lt ~/Library/Logs/DiagnosticReports/ | grep -i preview | head -5
O que procurar:
- Erros fatais (array fora dos limites, force unwrap de nil)
- Imports de módulo ausentes
- Falhas de inicialização de framework
3. Isolar o problema (5 min)
Criar preview mínimo:
// Começar com preview vazio
#Preview {
Text("Teste")
}
// Se isso funcionar, adicionar gradualmente:
#Preview {
MinhaView() // Sua view real, mas com dados mock
.environment(ModeloMock()) // Fornecer todas as dependências
}
// Descobrir qual dependência causa o travamento
Problemas comuns:
| Erro | Causa | Correção |
|---|---|---|
| "Cannot find in scope" | Dependência ausente | Adicionar ao preview (ver exemplo abaixo) |
| "Fatal error: Unexpectedly found nil" | Optional unwrap falhou | Fornecer valor não nulo no preview |
| "No such module" | Import ausente | Adicionar declaração import |
| Travamento silencioso (sem erro) | Inicialização de estado com valor inválido | Usar defaults seguros |
Padrões de correção:
// @Environment ausente
#Preview {
ContentView()
.environment(AppModel()) // Fornecer dependência
}
// @EnvironmentObject ausente (pré-iOS 17)
#Preview {
ContentView()
.environmentObject(AppModel())
}
// ModelContainer ausente (SwiftData)
#Preview {
let config = ModelConfiguration(isStoredInMemoryOnly: true)
let container = try! ModelContainer(for: Item.self, configurations: config)
ContentView()
.modelContainer(container)
}
Verificação:
- Preview deve agora carregar e exibir corretamente
- Se ainda falhar, repetir #3 com menos código
- Se funcionar, problema são as dependências — fornecer mock/valores padrão
Fluxo de Trabalho de Diagnóstico Emergencial
Quando tudo mais falhar, seguir este protocolo:
1. Remover TODOS os modificadores .environment() → 5 min
- Usar parâmetros diretos temporariamente
- Verificar se problema persiste
2. Remover ObservableObject, usar @Observable puro → 10 min
- Se iOS 17+, converter observabilidade
- Verificar se problema persiste
3. Reconstruir view do zero → 15 min
- Copiar conteúdo do body
- Colocar em nova struct
- Adicionar dependências uma por uma
- Testar a cada adição
Quando desistir e pedir ajuda:
- Após 1 hora de diagnóstico sem progresso
- Se você encontrou um bug do SwiftUI (reproduzível com código mínimo)
- Se o problema só ocorre em dispositivos específicos (arquitetura, versão do SO)
Referências Rápidas
Tabela de Padrões
| Padrão | Sintoma Principal | Custo de Tempo | Ferramenta |
|---|---|---|---|
| D1 | Atualizações inesperadas de view | 5 min | Self._printChanges() |
| D2 | Padrões complexos de atualização | 25 min | SwiftUI Instrument |
| D3 | Estado reseta, animações quebradas | 15 min | Inspeção de código |
| D4 | Muitas views atualizam | 10 min | Instruments + grep |
| D5 | Preview trava | 10 min | Botão de diagnóstico + logs |
Comandos Úteis
# Verificar se Self._printChanges() está em arquivos de origem
grep -r "_printChanges" --include="*.swift" .
# Verificar modificadores .id() dinâmicos
# Procurar por operações de string ou concatenação em .id()
grep -rn "\.id(" --include="*.swift" . | grep -E '"[^"]*" \+'
# Encontrar modificadores .environment()
grep -rn "\.environment(" --include="*.swift" . | grep -v "Teste"
Perguntas de Diagnóstico Rápido
Antes de escolher um padrão, responder:
- A view atualiza quando NÃO deveria? → Padrão D1 ou D2
- A view NÃO atualiza quando deveria? → Padrão D1 ou D3
- O problema é intermitente? → Padrão D3 ou D4
- O preview trava sem motivo claro? → Padrão D5
- Muitas views atualizam de uma vez? → Padrão D2 ou D4