Framework de Automação do Zero: Guia com 5 Camadas Essenciais

Meu primeiro “framework” de automação, lá na iPort, era uma pasta cheia de arquivo de teste que repetia o mesmo bloco de login em quase todo teste, com seletor de elemento espalhado direto no meio da lógica de teste. Funcionava, até o dia em que o time mudou um atributo de classe CSS num botão e eu precisei corrigir a mesma linha em vinte e três arquivos diferentes. Foi esse dia que me obrigou a aprender, na prática e sob pressão, o que separa “um monte de teste automatizado” de um framework de automação do zero de verdade. Resposta direta: montar um framework de automação do zero significa separar o código em camadas — teste, ação de página, configuração, dado e relatório — de um jeito que uma mudança na interface do sistema afete só uma camada, não o projeto inteiro; a ferramenta que você escolhe (Cypress, Playwright, Selenium) importa menos do que essa separação.

Por que a pergunta não deveria ser Cypress ou Playwright primeiro

O erro mais comum que vejo em quem está montando o primeiro framework de automação é começar pela ferramenta: abrir a documentação do Playwright ou do Cypress e já sair escrevendo teste, sem parar pra pensar em como o projeto vai crescer daqui a seis meses. O problema não é a ferramenta em si — é que decisão de arquitetura (como organizar pasta, onde guardar seletor, como isolar dado de ambiente) é praticamente a mesma independente de qual ferramenta está por trás, e ignorar isso no começo custa caro depois, quando reorganizar meia suíte de teste já rodando fica dolorido. É esse tipo de decisão inicial que separa um framework de automação do zero bem pensado de uma pasta de scripts que cresceu sem direção.

Um framework de automação bem desenhado deveria, em teoria, sobreviver a uma troca de ferramenta com esforço relativamente baixo — se você decidir migrar de Selenium pra uma ferramenta mais moderna, ou entre Cypress ou Playwright, a camada de teste (o que testar, em que ordem, quais dados usar) muda pouco; o que muda é só a camada de baixo nível que efetivamente clica e verifica elemento na tela. Se a sua estrutura hoje não permitiria isso nem em teoria, é sinal de que ferramenta e lógica de negócio estão coladas demais uma na outra.

Isso não quer dizer que a escolha de ferramenta não importa — importa, e bastante, pros detalhes de implementação de cada camada. Mas a ordem certa é definir a arquitetura primeiro, ferramenta depois, não o contrário. É basicamente o inverso do que a maioria dos cursos introdutórios ensina, que costuma focar direto em “como clicar num botão com o Selenium” sem nunca chegar em “como organizar isso quando você tiver duzentos testes”.

As camadas que todo framework de automação decente precisa ter

Na prática, um framework de automação do zero bem estruturado se divide em cinco camadas com responsabilidade clara. A camada de teste é onde vive a lógica de negócio, escrita numa linguagem próxima de como um humano descreveria o cenário — “fazer login com credencial válida e verificar que o dashboard aparece” — sem nenhuma menção a seletor CSS ou XPath ali dentro. Logo abaixo fica a camada de página (ou de tela, em app mobile), que concentra os seletores de elemento e as ações possíveis naquela tela específica: é aqui, e só aqui, que um ID de elemento ou uma classe CSS deveria aparecer no código.

A camada de configuração cuida de tudo que muda dependendo de onde o teste está rodando — URL base do ambiente (homologação, produção, local), credencial de usuário de teste, tipo de navegador, se roda com interface visível ou headless. O objetivo aqui é nunca ter valor fixo (“hardcoded”) espalhado pelo código: tudo que pode mudar por ambiente vive em arquivo de configuração ou variável de ambiente, nunca dentro da lógica de teste em si.

As duas últimas camadas costumam ser as mais negligenciadas por quem está começando. A camada de dado organiza massa de teste (usuário válido, cartão de teste, produto de exemplo) separada da lógica que usa esse dado, geralmente em arquivo JSON ou função factory que gera dado fresco a cada execução — isso evita o clássico problema de teste que só passa na primeira vez porque o dado fixo já foi “usado” no banco. E a camada de relatório e log é o que transforma “o teste falhou” em “o teste falhou nesse passo específico, com essa mensagem de erro, e aqui está o screenshot do momento” — sem isso, depurar falha em CI vira adivinhação.

Page Object Model na prática: o que errar aqui custa caro depois

O Page Object Model é o padrão de projeto por trás da camada de página que mencionei acima, descrito originalmente por Martin Fowler em seu artigo de referência sobre o padrão, e a ideia central dele é simples: cada tela ou componente da aplicação vira uma classe (ou módulo) que expõe ações com nome de negócio — fazerLogin(usuario, senha) — escondendo por trás o seletor e a sequência de clique necessária pra executar aquela ação. Quem escreve o teste chama paginaDeLogin.fazerLogin(...) sem nunca precisar saber que por trás disso existe um seletor #input-email que pode mudar amanhã.

O erro mais caro que vejo repetido é colocar asserção (verificação de resultado esperado) dentro da própria page object, misturando “ação que a página permite fazer” com “verificação que o teste espera” — isso quebra a reutilização, porque a mesma ação de login pode ser usada num teste que espera sucesso e noutro que espera erro de credencial inválida, e a asserção fixa dentro da page object atrapalha os dois casos. A regra prática que uso: page object executa ação e no máximo retorna estado (a página carregou, o elemento apareceu); a decisão sobre se isso é certo ou errado fica sempre na camada de teste. Não seguir essa separação é um dos erros mais comuns de quem está construindo um framework de automação do zero pela primeira vez.

Outro erro comum é duplicar seletor do mesmo elemento em página object diferente porque o componente aparece em mais de uma tela — um cabeçalho de navegação, por exemplo. Nesse caso, vale criar um componente compartilhado (às vezes chamado de “component object”) que várias page objects podem herdar ou compor, em vez de copiar e colar o mesmo seletor em três lugares diferentes esperando que ninguém mude ele sem lembrar de atualizar todas as cópias.

Dados, ambientes e CI/CD: o que transforma script solto em framework de verdade

Depois que a estrutura de camada está definida, o que separa um framework “de verdade” de uma coleção organizada de scripts é a integração com o resto do fluxo de desenvolvimento. Isso começa pela configuração de múltiplos ambientes: o mesmo conjunto de teste deveria rodar contra homologação ou produção só trocando uma variável de ambiente, nunca duplicando arquivo de teste pra cada ambiente diferente — se você se pega copiando pasta de teste “para produção” e “para homologação”, a camada de configuração não está fazendo o trabalho dela.

Testes orientados a dado (data-driven) entram aqui como uma extensão natural: em vez de escrever cinco testes quase idênticos pra cinco combinações de entrada, um framework bem montado roda o mesmo teste cinco vezes, cada vez lendo uma linha diferente de uma fonte de dado externa (JSON, planilha, ou até um banco de teste). Isso reduz duplicação de código de teste e centraliza a manutenção: mudou a regra de negócio, muda a lógica do teste uma vez só, não em cinco lugares. Esse tipo de ganho é o que justifica o esforço de montar um framework de automação do zero em vez de acumular script solto.

Por fim, integrar tudo isso num pipeline de CI/CD (GitHub Actions, GitLab CI, Jenkins) é o que fecha o ciclo: a suíte roda sozinha a cada push ou pull request, gera relatório num formato legível (Allure é uma opção comum, mas um relatório HTML customizado também resolve), e falha o build automaticamente se algum teste crítico quebrar. Sem essa integração, o framework mais bem desenhado do mundo ainda depende de alguém lembrar de rodar ele manualmente — e isso, na prática, quer dizer que ele vai ser esquecido.

Minha experiência real montando framework do zero (e os erros que cometi)

Depois daquele episódio dos vinte e três arquivos pra corrigir na iPort, minha reação inicial foi o oposto do problema original: tentei montar de uma vez um framework “perfeito”, com camada de abstração pra tudo, suporte a três ferramentas diferentes ao mesmo tempo e configuração flexível o bastante pra qualquer cenário futuro imaginável. Levou semanas, ninguém no time conseguia contribuir teste novo sem minha ajuda porque a estrutura tinha ficado complexa demais pra ser intuitiva, e boa parte daquela flexibilidade nunca foi usada de verdade.

O que funcionou, da segunda vez que refiz esse processo já na Entrepay, foi o caminho inverso: comecei com a estrutura mínima de três camadas (teste, page object, configuração), sem dado externo nem relatório sofisticado, e só fui adicionando camada nova quando a dor de não ter ela ficava concreta — a camada de dado surgiu quando duplicar caso de teste ficou óbvio demais pra ignorar; o relatório detalhado, quando depurar falha em CI virou frustração repetida do time inteiro. Framework de automação do zero não precisa nascer completo, precisa nascer certo na estrutura básica e crescer sob demanda real.

Se você ainda está decidindo se vale a pena investir tempo nisso antes de simplesmente escrever teste solto, vale rever o comparativo entre QA manual e automação de testes e o guia de como migrar de QA manual pra automação, que cobrem o degrau anterior a esse. E se a camada que falta no seu framework hoje é testar API além do navegador, os comparativos entre ferramentas de teste de API gratuitas e entre Postman e Insomnia mostram por onde começar. Entender bem essa arquitetura, no fim das contas, é um dos fatores que mais separa quem sabe escrever teste de quem sabe efetivamente virar SDET. Nenhum desses passos substitui o trabalho de realmente montar seu framework de automação do zero com as próprias mãos.

Perguntas frequentes

Preciso saber Design Patterns pra montar um framework de automação?

Não precisa ser especialista, mas conhecer o Page Object Model e a ideia geral de separar responsabilidade em camadas já cobre 80% do que importa na prática. Os outros padrões (factory, builder, singleton) ajudam em casos específicos, mas dá pra montar um framework sólido conhecendo bem só o essencial e evoluindo conforme a necessidade aparece.

Framework de automação funciona igual em Cypress, Playwright e Selenium?

A estrutura de camadas (teste, page object, configuração, dado, relatório) é praticamente a mesma nas três. O que muda é a sintaxe específica de cada ferramenta na camada de página, que é justamente a camada mais baixa e mais isolada — por isso um framework bem desenhado sobrevive melhor a uma eventual troca de ferramenta.

Vale a pena usar um framework pronto em vez de montar o meu?

Depende do contexto. Frameworks prontos (como Robot Framework ou soluções corporativas internas) economizam tempo de configuração inicial e já vêm com convenção estabelecida, mas prendem você às decisões de arquitetura de quem criou o framework. Montar o seu dá mais controle e aprendizado real de como automação funciona por baixo dos panos, ao custo de mais tempo investido no início.

Quanto tempo leva pra montar um framework de automação do zero?

A estrutura básica de três camadas (teste, page object, configuração) dá pra montar em poucos dias pra um projeto pequeno. O que leva mais tempo é fazer ela crescer de forma saudável conforme o projeto cresce — não é um trabalho de uma vez só, é um processo contínuo de ajuste conforme dor real aparece, como descrevi na minha própria experiência. Foi assim que encarei meu próprio framework de automação do zero, e recomendo que você encare o seu do mesmo jeito.