Depois de acumular uma boa quantidade de código de teste, surge a dúvida: “Com que combinação devo executar estes testes?”
Executar tudo leva 20 minutos no CI(Continuous Integration, integração contínua). Executar só uma parte exige alternar opções manualmente.
Também pode ser difícil encontrar uma forma adequada de executar testes de UI em ambientes coreano e inglês.
Em resumo, a Apple criou o plano de teste(Test Plan) para resolver exatamente esse problema.
Planos de teste apresentados no Xcode 11separa em arquivo os “testes a executar” das “condições de execução”.
Hoje vamos resumir estrutura, configuração prática e integração com CI de uma vez.
Se escrever código de teste ainda é novidade, comece porComo escrever seu primeiro teste com os fundamentos de XCTest e Given-When-Then.
O que é um plano de teste
Um plano de teste é um arquivo com extensão.xctestplan. Seu conteúdo é JSON legível e, depois de adicionado ao projeto, é referenciado pelo scheme(Scheme).
Um arquivo contém duas coisas.
- Testes a executar: quais alvos, suites e funções incluir ou excluir.No Xcode 16 ou posterior, tags do Swift Testing também podem ser usadas como condições
- Configuração(Configuration): em quais condições executar esses testes
O importante é ser um arquivo. .xctestplanpode ser commitado no Git, permitindo compartilhar condições e revisar alterações de configuração.
Em equipe, é mais seguro versionar o plano junto com o scheme compartilhado que o referencia.
Por que configurar apenas o scheme não basta
Antes dos planos de teste, todas as condições ficavam na ação Test do scheme. Essa estrutura tem limitações.
Um scheme tem apenas uma configuração da ação Test. Para separar uma validação rápida de uma completa noturna, era preciso duplicá-lo.
A duplicação também copia configurações de build, execução e perfil. Você copia tudo para alterar uma condição de teste.
O plano de teste inverte essa relação. É possível associarvários planos a um scheme, e cada plano pode ter várias configurações.
Criando um plano de teste
Com base emOrientação atual da Apple, o Xcode cria um plano padrão com todos os testes dos alvos de teste compilados pelo scheme.
- Abra e salve o plano padrão em Product > Scheme > Edit Test Plan
- Na aba Tests, escolha alvos por tags, suites e funções
- Na aba Configurations, adicione configurações compartilhadas e necessárias
Para criar mais planos, use Product > Test Plan > New Test Plan. Em schemes antigos, pode aparecerConvert to use Test Plans; isso éFluxo de conversão de configurações existentes apresentado no Xcode 11.
Se houver vários planos, escolha um como padrão(Default) em Product > Test Plan > Manage Test Plans. Ele será usado quando nenhum outro for especificado.
Ative o plano em Product > Test Plan. Ao executar Command + U, ou seja, Product > Test, o plano ativo roda uma vez por configuração. Diferencie o plano padrão do ativo.
Relação entre configurações compartilhadas e individuais
O editor do plano tem as abas Tests e Configurations. O ponto central é Configurations.
Essa aba tem duas camadas.
- Shared Settings(configurações compartilhadas): valores padrão herdados por todas as configurações
- Configuração individual: variação que sobrescreve apenas os itens necessários
É parecido com a herança do CSS: escreva as condições comuns uma vez e defina só as diferenças por configuração.
Itens sobrescritos aparecem em negrito no editor, deixando claro o que é diferente.
Há muitas opções, mas as mais usadas são estas.
| Item | O que define |
|---|---|
| Arguments / Environment Variables | Argumentos de execução e variáveis de ambiente |
| Application Language / Region | Idioma e região em que o app será executado |
| Code Coverage | Se haverá coleta de cobertura e quais alvos serão cobertos |
| Execution Order | Executar em ordem alfabética ou embaralhar a cada execução |
| Test Repetition Mode | Forma de repetir os testes |
| Test Timeouts | Tempo máximo permitido para cada teste |
| Runtime Sanitization | Address·Thread·Undefined Behavior Sanitizer |
| Memory Management | Malloc Scribble, Malloc Guard Edges, Zombie Objects |
| Automatic Screen Capture | Se uma captura de tela será anexada automaticamente em caso de falha |
O comum fica no compartilhado; as diferenças, na configuração. Assim o plano continua administrável mesmo crescendo.
Exemplo prático de divisão de configurações
O caso mais comum é separar por idioma. Em apps multilíngues, o layout frequentemente quebra conforme o idioma; configurações separadas repetem automaticamente o mesmo teste de UI.
- Configuração compartilhada: ativar cobertura e salvar capturas em caso de falha
- Configuração A “Korean”: Application Language em coreano
- Configuração B “English”: Application Language em inglês
- Configuração C “RTL Pseudolanguage”: validação de idiomas escritos da direita para a esquerda
Ao executar este plano uma vez, O teste selecionado é executado uma vez em cada configuração, e o relatório também separa os resultados por configuração. Fica claro em qual idioma ocorreu a falha.
O mesmo vale para a verificação de memória. Segundo a documentação da Apple, o Address Sanitizer pode usar 2 a 3 vezes mais memória e deixar o código 2 a 5 vezes mais lento, é preciso considerar o custo de execução.
Deixe os sanitizers desligados na configuração normal e crie configurações de diagnóstico separadas. Separe Address Sanitizer e Thread Sanitizer e execute-os no build noturno.
Cobertura, ordem aleatória e repetição
Vamos destacar três opções especialmente úteis nas configurações.
A cobertura de códigonão é só ativar: primeiro defina o que medir. Misturar bibliotecas dependentes no mesmo número pode dificultar a leitura das mudanças no código do app.
Escolha “some targets” para indicar apenas os alvos do seu app e obter uma métrica relevante.
EmExecution Order, escolha Alphabetical ou Random. Não generalize que Alphabetical seja o padrão de todos os testes.
No plano do XCTest, escolher Random embaralha a ordem a cada execução. JáO Swift Testing executa funções de teste em paralelo por padrão e também randomiza a ordem. É preciso distinguir o comportamento dos dois frameworks.
Se mudar a ordem causa falha, provavelmente há dependência do estado deixado pelo teste anterior. É um sinal útil de acoplamento oculto entre testes. Essa independência também é central emO princípio FIRST de bons testes unitários.
Test RepetitionéOpção adicionada no Xcode 13e permite escolher estas formas de repetição.
| Modo | Comportamento | Uso |
|---|---|---|
| Up Until Maximum Repetitions | Repetir até o máximo definido, independentemente do resultado | Medir a taxa de reprodução de falhas intermitentes |
Repetir até falhar(-run-tests-until-failure) |
Repetir até ocorrer uma falha | Rastrear testes que falham ocasionalmente |
| Retry on Failure | Em caso de falha, tentar novamente até o número definido | Proteger a taxa de aprovação no CI de testes de UI instáveis |
SegundoNotas da versão do Xcode 13,Maximum Test Repetitionsdeve receber um inteiro positivo. A documentação oficial não confirma “padrão de 3 vezes”; confira diretamente o valor salvo no plano.
Na linha de comando,-test-iterationsdefine a quantidade. Você pode combinar com-run-tests-until-failureou-retry-tests-on-failure. Essa configuração tem prioridade sobre a do plano.
Retry on Failure é conveniente, mas use com cuidado. Passar por uma nova tentativa mantém um teste instável no projeto.
Use temporariamente e investigue separadamente a causa da instabilidade.
Usando planos de teste no CI
Planos de teste também funcionam na linha de comando. Primeiro, confirme o plano ligado ao scheme comxcodebuild -scheme MyApp -showTestPlans. Em-testPlan, passe o nome do plano, não o caminho do arquivo.
xcodebuild test \
-project MyApp.xcodeproj \
-scheme MyApp \
-testPlan Smoke \
-destination 'platform=iOS Simulator,name=iPhone 16'Mantenha o mesmo scheme e altere apenas o nome do plano para dividir o escopo dos jobs de CI. Por exemplo:
- A cada PR(Pull Request):
-testPlan Smoke— foco nos testes unitários essenciais - Merge na branch principal:
-testPlan Regression— todos os testes unitários e de UI - Agendamento noturno:
-testPlan Nightly— inclui sanitizers e configurações multilíngues
Também é possível dividir ainda mais por configuração.
Como emExemplo atual de linha de comando da Apple,--only-test-configurationexecuta apenas as configurações indicadas. Já--skip-test-configurationexecuta tudo, exceto as indicadas. As duas opções usam dois hífens.
Se o plano tiver cinco configurações de idioma, o CI pode criar cinco jobs e atribuir uma configuração a cada um. Porém, essa distribuição paralela é responsabilidade do CI; o plano não divide máquinas nem reduz o tempo automaticamente.
xcodebuild test \
-scheme MyApp \
-testPlan Localization \
--only-test-configuration Korean \
-destination 'platform=iOS Simulator,name=iPhone 16'Perguntas frequentes
P. O arquivo do plano de teste deve ir para o Git?
R. Para compartilhar as mesmas condições na equipe, é melhor fazer commit. Mas enviar ao Git não é requisito do Xcode. Gerencie juntos o plano e o scheme compartilhado que o referencia.
Como é JSON, editar simultaneamente gera conflitos. Separar arquivos por finalidade reduz sua frequência.
P. Criar várias configurações não dobra o tempo?
R. Sim. Os testes são repetidos conforme o número de configurações.
Por isso, configurações pesadas, como multilíngue e sanitizers, devem sair do plano normal e ir para o plano noturno.
P. Posso colocar testes unitários e de UI no mesmo plano?
R. Pode. Mas testes unitários levam segundos e testes de UI, minutos; a velocidade do feedback é bem diferente.
Separá-los em planos rápido e lento combina melhor com o fluxo de desenvolvimento.
P. Testes feitos com Swift Testing entram no plano?
R. Sim. Se o alvo selecionado tiver testes XCTest e Swift Testing, ambos podem rodar no mesmo plano. Conhecer tambémTags e execução paralela do Swift Testingfacilita dividir os planos.
P. E se eu quiser excluir apenas alguns testes?
R. Na aba Tests, desmarque alvos, suites, funções ou casos parametrizados individuais.No Xcode 16 ou posterior, também é possível escolher o escopo com Include Tags e Exclude Tags do Swift Testing.
Isso fica apenas no arquivo do plano, sem alterar o código; os outros planos continuam executando os testes.
O plano de teste não é uma ferramenta para criar testes. Ele define quais testes existentes executar e sob quais condições.
Se você dividia condições duplicando schemes, salve o plano padrão e organize planos por finalidade. No CI, explicitar plano e configuração por job esclarece o escopo, mas a redução real depende do número de runners e do paralelismo.
Primeiro salve o plano padrão em Product > Scheme > Edit Test Plan e crie um plano Smoke. Depois, adicionar configurações será bem mais fácil.
Fontes e critérios de verificação
- Improving code assessment by organizing tests into test plans (Apple) — Foram verificados o menu atual de criação de planos do Xcode, as unidades de seleção, a execução por configuração e as opções
xcodebuild. - Testing in Xcode, WWDC19 (Apple) — Foram verificados a introdução no Xcode 11, a estrutura de arquivos
.xctestplane o fluxo de conversão de schemes existentes. - Xcode 13 Release Notes (Apple) — Foram verificados modos de repetição, quantidade inteira positiva e prioridade das opções de linha de comando.
- Go further with Swift Testing, WWDC24 (Apple) — Foram verificados a execução paralela padrão e a ordem aleatória do Swift Testing.
- Diagnosing memory, thread, and crash issues early (Apple) — Foram verificadas a função dos sanitizers e o custo de execução do Address Sanitizer.
A data de referência é 16 de agosto de 2026. Os nomes de menus e a sintaxe de linha de comando seguem a documentação oficial atual da Apple; não afirmamos quantidade padrão de repetições nem redução de tempo no CI sem confirmação documental.