Desenvolver automação de interfaces móveis e corrigir falhas no produto, não na CI

## Colocar cada mudança no módulo responsável pelo comportamento Mantenha um mapa conciso dos módulos que identifique onde o código é executado e quem consome seus artefatos. Separe, no mínimo, estas responsabilidades: - drivers no dispositivo e seus binários gerados; - adaptadores de plataforma no host e clientes de protocolo; - interpretação de comandos, novas tentativas, controle de ciclo de vida e classificação de erros; - modelos compartilhados de comandos e dados; - interfaces de linha de comando e interfaces voltadas a agentes; - drivers web, definições de formatos de comunicação, utilitários e testes entre módulos. Coloque a alteração onde o comportamento é de fato controlado. A interação com o dispositivo e o tratamento de diálogos do sistema pertencem aos drivers de plataforma ou aos adaptadores do host; novas tentativas e sequenciamento de comandos pertencem à orquestração; formatos compartilhados de solicitação pertencem aos módulos de modelo ou protocolo. Não resolva um problema de propriedade em um módulo distante apenas porque é mais fácil aplicar uma correção ali. Mantenha o mapa como fonte única de verdade para workflows e agentes especialistas. Atualize-o quando as responsabilidades dos módulos mudarem, evitando divergência nas orientações derivadas. ## Escolher a camada de teste mais barata que comprove o comportamento Use uma estratégia de testes em camadas e escolha por padrão a camada de menor custo capaz de comprovar o comportamento: 1. Testes unitários para classes isoladas, análise, pequenos utilitários e lógica local de decisão. 2. Testes de integração para orquestração de comandos, cancelamento, mecanismos de script, limites de rede e interação entre vários módulos que possam ser executados sem dispositivo. 3. Testes de ponta a ponta para drivers reais, comportamento de dispositivo ou navegador, integração com o sistema operacional e fluxos completos do usuário. 4. Avaliações da interface para agentes, medindo o comportamento do modelo e a correção das ferramentas quando o produto expõe um protocolo voltado a IA. Não promova um teste a uma camada mais cara quando componentes simulados ou no mesmo processo puderem representar o contrato com precisão. Por outro lado, não substitua evidências no nível do dispositivo por mocks quando o risco for o comportamento da plataforma. ## Separar as suítes que devem passar das que devem falhar Separe os fluxos de ponta a ponta pelo resultado esperado. Uma suíte positiva contém fluxos que devem ser aprovados; qualquer falha é uma regressão. Uma suíte negativa contém asserções ou comandos intencionalmente inválidos e deve falhar da maneira esperada. A estrutura de testes pode inverter a interpretação de sucesso da suíte negativa. Por isso, a leitura dos artefatos deve preservar o rótulo da suíte. Nunca diagnostique um resultado negativo esperado como regressão do produto nem enfraqueça ou reescreva um fluxo negativo apenas para fazê-lo passar. Quando um processo automático de diagnóstico consumir artefatos, restrinja-o às falhas reais da suíte positiva, a menos que seu contrato ofereça suporte explícito à análise de caminhos negativos. Armazene os artefatos em uma hierarquia previsível que inclua aplicação, plataforma, suíte e identidade da execução. ## Reutilizar uma única aplicação fixture nos testes de ponta a ponta de todas as plataformas Use uma aplicação fixture padrão para exercitar toda a superfície de comandos nas plataformas suportadas. Reutilize os mesmos fluxos para dois fins: testes rápidos de regressão nas versões atuais das plataformas e validação de compatibilidade em uma nova versão do sistema operacional. Se um comportamento for específico de uma estrutura, adicione um workspace fixture dedicado em vez de distorcer a aplicação padrão. Dê a cada workspace seus próprios fluxos e artefato de build, e permita que a execução manual seja limitada a uma aplicação ou a um fluxo. Parametrize o driver de teste pela plataforma e por entradas de ambiente explícitas. Valide as entradas de execução antes de provisionar infraestrutura cara: rejeite antecipadamente versões de sistema não suportadas, workspaces ausentes e seletores de fluxo ambíguos. ## Corrigir falhas do dispositivo no driver, não com ajustes na CI Quando um fluxo de ponta a ponta falhar porque um driver de plataforma não consegue lidar com o comportamento real do dispositivo, corrija o driver, o adaptador do host ou a aplicação fixture que os usuários realmente executam. Não esconda a lacuna adicionando configurações de emulador, comandos de shell, ajustes de linha de comando ou pré-configuração ao workflow de CI. Alterações de workflow são adequadas para a própria estrutura do workflow: matrizes, retenção, gatilhos, entradas de execução validadas ou exceções de infraestrutura limitadas e documentadas. Elas não substituem o comportamento do produto. Use a mesma regra ao validar uma nova versão do sistema operacional. Um fluxo que só passa após uma preparação exclusiva de CI ainda indica um defeito de compatibilidade do produto, a menos que essa preparação seja um pré-requisito explícito para o usuário. ## Classificar os erros conforme valha a pena tentar de novo e sempre limpar os arquivos temporários Use execução assíncrona estruturada com dispatchers ou executores explícitos. Reserve pontes bloqueantes para os pontos de entrada da aplicação. Classifique as falhas expostas para que a orquestração diferencie condições que podem ser tentadas novamente de erros terminais, em vez de repetir tudo da mesma forma. Gerencie arquivos e diretórios temporários por meio de um gerenciador de recursos responsável pelo ciclo de vida. Crie-o próximo da operação que possui os recursos, faça as alocações por sua API e feche-o em um caminho `finally`, para que a limpeza recursiva ocorra após sucesso, falha ou cancelamento. Não contorne o gerenciador de recursos com chamadas diretas de criação de arquivos temporários. Arquivos não gerenciados se acumulam em workers de longa duração e dificultam a reprodução das falhas. Quando nenhum dispositivo for necessário, teste cancelamento, tempo limite, comportamento do supervisor e limpeza com orquestração real e drivers simulados determinísticos. ## Testar separadamente as ferramentas para agentes e o comportamento do modelo Quando a aplicação de linha de comando também expuser um servidor para agentes, mantenha duas famílias de testes distintas: - testes de funcionalidade das ferramentas que verifiquem solicitações, respostas, configuração dos dispositivos e comportamento diante de falhas; - avaliações de comportamento do modelo que meçam se um agente seleciona e usa corretamente as ferramentas. Use casos declarativos de avaliação e scripts de configuração específicos da plataforma para tornar a cobertura reproduzível. Execute testes rápidos de ferramentas em alterações comuns de implementação; execute avaliações de modelo mais lentas quando mudarem prompts, descrições das ferramentas, schemas, routing ou comportamento visível ao agente. Não trate uma pontuação do modelo como prova de que a ferramenta subjacente funciona, nem um teste funcional da ferramenta como prova de que um agente a usará corretamente. Os dois contratos precisam de evidências próprias. ## Regenerar os binários pela compilação, sem editá-los à mão Trate binários de drivers versionados, executores empacotados, somas de verificação e outros arquivos derivados como resultados de geradores. Nunca os edite manualmente. Execute a tarefa de build ou o finalizador responsável e registre os artefatos resultantes junto com a alteração de origem que os produziu. Antes de concluir: 1. Confirme que a alteração está no módulo responsável pelo comportamento. 2. Execute a camada de teste suficiente de menor custo e qualquer camada mais ampla diretamente afetada. 3. Interprete as suítes positivas e negativas de acordo com seus contratos. 4. Verifique se os recursos temporários são fechados após sucesso, falha e cancelamento. 5. Gere novamente os artefatos derivados pelo caminho oficial de build. 6. Confirme que as alterações de CI descrevem a estrutura da infraestrutura, em vez de ocultar defeitos do produto. Mantenha sincronizados a documentação dos workflows, a disposição das fixtures e as notas sobre propriedade dos módulos, para que colaboradores e agentes automatizados posteriores respeitem os mesmos limites.