Quando uma macro de emulador Android não avança, o sintoma visível costuma ser o mesmo: nenhum toque novo, nenhuma troca de tela e nenhuma rotina concluída. A causa ainda pode ser bem diferente. A macro pode ter falhado antes da execução, estar esperando porque uma condição é falsa, estar recuperando a conexão com o emulador ou ter parado depois de um erro irrecuperável numa ação.
O EmuloAgent trata esses casos de formas diferentes. Ele não encerra a rotina inteira só porque uma imagem deixou de ser encontrada uma vez, mas bloqueia o início quando as resoluções da macro e do emulador são incompatíveis. Também pode continuar tentando depois de uma falha temporária de captura e parar quando seguir adiante seria inseguro.
Este guia organiza o diagnóstico para você corrigir a camada que falhou, em vez de alterar limites de detecção, esperas e perfis ao acaso.
Primeiro identifique quando a macro deixou de avançar
Antes de editar a automação, coloque o sintoma em uma destas etapas:
- Ela nem iniciou: o perfil ou a macro não passou nas verificações de partida.
- Ela iniciou, mas continua esperando: a execução está ativa, porém as condições atuais não liberam a ação.
- Ela perdeu contato com o emulador: o EmuloAgent não consegue capturar um quadro atual e tenta reconectar.
- Ela parou depois de um erro explícito: uma ação informou um problema fatal ou o runtime acumulou erros internos.
- Você usou Parar de propósito: esse comando encerra a execução atual e não representa falha do produto.
Não aplique uma única correção aos cinco casos. Reduzir a precisão de uma imagem não recupera uma conexão ADB; reconectar o ADB não torna confiável uma referência capturada na resolução errada.
Se a macro não iniciou, confira perfil e resolução
O EmuloAgent verifica o ambiente antes de entrar no ciclo da macro. A partida pode terminar em estado de falha quando:
- o perfil selecionado não tem resolução detectada;
- a macro salva não pode ser carregada;
- a macro foi calibrada numa resolução e o emulador está rodando em outra.
A verificação de resolução é intencional. Coordenadas, regiões de captura e imagens de referência estão ligadas a um arranjo de pixels. Rodar uma macro calibrada em 960x540 contra outro tamanho de quadro gastaria tempo procurando nos lugares errados e poderia enviar um toque para uma área indesejada.
Confirme a resolução exibida pelo emulador e abra a edição do perfil. Se o emulador deve manter o tamanho original da macro, restaure esse tamanho antes de iniciar novamente. Se a nova resolução é intencional, abra o Construtor de Macros com esse perfil e recapture ou revise as referências visuais para o novo layout.
Se o EmuloAgent não detecta o emulador, siga primeiro o guia de conexão para MuMu, BlueStacks, LDPlayer e Nox antes de mudar a macro.
Se ela continua esperando, inspecione a condição atual
Uma macro que segue em execução, mas não age, não está necessariamente travada. Cada ação pode esperar por condições de imagem, contador de imagens, texto, cor, perfil ou variável. Quando a condição é falsa, a ação é ignorada e o ciclo continua observando a tela.
Comece pela primeira diferença observável:
- O emulador está na tela esperada pela ação?
- A imagem capturada ainda corresponde ao tema, idioma e escala atuais?
- A região de detecção cobre a posição atual do alvo?
- O texto ganhou ou perdeu pontuação e espaços?
- A cor foi capturada numa parte estável da interface?
- A ação está restrita a outro perfil?
Teste o menor passo suspeito no Construtor de Macros sobre a tela atual. Se ele funciona sozinho, reproduza os passos imediatamente anteriores. A ação anterior pode estar deixando o emulador em outro estado, mesmo que o passo suspeito esteja configurado corretamente.
O guia de detecção por imagem, cor e texto ajuda a escolher um sinal mais forte. Mude uma variável por vez; baixar todas as precisões esconde a falha original e pode criar correspondências falsas.
Uma falha comum de ação não para a macro inteira
Essa diferença evita um diagnóstico frequente. No EmuloAgent, uma falha comum de ação — como não encontrar uma imagem de referência — não pausa automaticamente toda a rotina. O resultado é registrado como aviso, o fluxo segue conforme sua estrutura e a macro pode iniciar outro ciclo.
Esse comportamento é útil para telas opcionais ou temporárias, mas também permite que um fluxo frágil pareça ocupado sem produzir progresso. Modele os dois lados das transições importantes:
- proteja a ação com uma condição que prove que a tela de destino está pronta;
- execute a ação;
- adicione uma verificação posterior que prove que a tela mudou;
- defina o que a macro deve fazer quando essa confirmação não aparece.
Não use “a ação foi tentada” como prova de sucesso. Procure um estado observável depois dela.
Se o emulador não responde, deixe a reconexão agir
A captura de tela é o retorno visual da automação. Quando o EmuloAgent falha repetidamente ao obter um quadro, ele avisa que o emulador não responde e continua tentando reconectar. Assim que a captura volta a funcionar, a sequência de falhas é zerada e a execução pode continuar.
Durante a recuperação, confira o ambiente sem reconstruir a macro:
- confirme que o processo do emulador e a instância certa continuam abertos;
- verifique se o perfil aponta para o host e a porta ADB corretos;
- evite reiniciar várias instâncias do emulador ao mesmo tempo;
- confira se o computador está sob pressão forte de CPU ou memória;
- mantenha a resolução do emulador sem alterações durante a execução.
Se a conexão voltar, confirme que o app ainda está numa tela reconhecida pela macro. A reconexão recupera o acesso à tela; ela não devolve o app Android ao estado que existia antes da interrupção.
Se o EmuloAgent parou após um erro, leia o motivo antes de reiniciar
Algumas falhas são explicitamente fatais porque continuar às cegas seria inseguro ou inútil. Entre os casos implementados estão uma ação de Teclado Virtual sem senha para o perfil ativo, referências de dígitos ausentes, senha que não pode ser decifrada, falhas repetidas do reconhecimento do teclado ou mecanismo de OCR indisponível para uma ação de texto.
Exceções internas do runtime e timeouts de detectores também podem abrir a proteção depois de falhas repetidas. Nesse caso, o EmuloAgent encerra a execução atual e inclui o perfil e o motivo disponível na mensagem de diagnóstico.
Abra os logs em %APPDATA%\EmuloAgent\logs\ e procure, a partir do fim do arquivo mais recente, pelo nome do perfil e pelo primeiro erro anterior à parada. Mensagens posteriores costumam ser consequências. Quando uma ação fatal ainda tem uma captura atual, o EmuloAgent também tenta salvar a imagem da falha e registra o caminho na entrada de diagnóstico.
Use a mensagem para escolher a correção:
- template ou dígito ausente: recapture a referência na resolução correta;
- senha ausente para este perfil: edite a ação Teclado Virtual e cadastre o segredo para o perfil;
- OCR indisponível: repare ou atualize a instalação do EmuloAgent em vez de trocar verificações de texto por toques cegos;
- resolução incompatível: alinhe o emulador à macro ou recalibre a macro;
- erro interno repetido: preserve o log e a captura de falha ao falar com o suporte.
Depois de corrigir a causa, inicie uma nova execução controlada. Uma parada fatal encerra a execução atual; não é uma orientação para continuar apertando Executar sem mudar nada.
Exemplo prático: o botão de confirmação nunca avança
Imagine uma macro de apoio a QA que espera a imagem Continuar, toca nela e depois deveria encontrar o título de um painel.
Diagnostique na ordem:
- Confirme que a macro iniciou e passou pela verificação de resolução.
- Coloque o emulador na tela de confirmação esperada.
- Teste isoladamente a condição da imagem Continuar.
- Se ela falhar, confira o recorte salvo, a região de busca, o tema, o idioma e a escala atual.
- Se a condição passar, teste o toque e observe se o alvo se move ou está coberto por outro elemento.
- Confira a condição do título do painel depois do toque.
- Se o emulador parar de produzir quadros, corrija a conexão em vez de alterar a precisão da imagem.
- Se a execução parar com um motivo fatal explícito, corrija esse motivo e preserve a entrada correspondente do log.
Essa sequência separa quatro camadas — partida, detecção, ação e runtime — para uma correção não criar outro problema em seguida.
Use um checklist curto antes da próxima execução
- A instância do emulador está aberta e o perfil aponta para ela.
- A resolução do emulador corresponde à calibração da macro.
- O app está numa tela inicial conhecida.
- A primeira condição bloqueada passa num teste isolado.
- A ação produz um resultado visível, não apenas um comando concluído.
- A condição seguinte confirma esse resultado.
- Um emulador reconectado voltou para uma tela reconhecível.
- O primeiro aviso ou erro relevante foi revisado no log atual.
- Apenas uma configuração foi alterada antes do próximo teste.
Depois de corrigir a falha, aplique o checklist de estabilização da macro antes de fixá-la em mais perfis ou deixá-la numa execução longa.
Diagnostique a camada e só então execute novamente
Uma macro que parece parada não representa uma única falha genérica. Verificações de partida protegem perfis incompatíveis, condições podem manter um fluxo ativo esperando, a recuperação de captura trata uma perda temporária do emulador e erros fatais encerram uma execução que não deveria continuar igual. Identifique a etapa, verifique uma camada por vez e reinicie somente depois de tratar a causa registrada.