Testes end-to-end de aplicativos Electron: além do suporte do Playwright ao Electron
Testes de aplicativos Electron como o usuário os vê: o que a API do Playwright para Electron cobre, onde ela para, e um teste pela página, pela caixa de diálogo de arquivos e pela notificação.
10 min de leituraPor Ait Nohaila, Representante de desenvolvimento de negócios
A resposta curta
Para testar um aplicativo Electron automaticamente, conduza-o como um usuário, incluindo as caixas de diálogo nativas, e verifique o que ele desenha na tela.
- A API do Playwright para Electron cobre o processo de renderização e o processo principal; o shell precisa de uma ferramenta que veja a tela.
Este guia é para os desenvolvedores e as pessoas de QA de um aplicativo desktop Electron.Ele diz o que torna esse aplicativo diferente de testar, faz um relato justo da API do Playwright para Electron, e depois mostra um teste de ponta a ponta pela página, pela caixa de diálogo de arquivos nativa, por uma exportação e pela notificação dela, executado a cada build.
O que torna um aplicativo Electron diferente de testar
Um aplicativo Electron são dois programas trabalhando juntos.O processo principal é executado em Node.js: ele abre as janelas, cuida do ciclo de vida do aplicativo, e pede ao sistema operacional tudo o que é nativo, como menus, caixas de diálogo e ícones na bandeja.Cada janela, por sua vez, executa um processo de renderização, que é uma página do Chromium: HTML, CSS e JavaScript, como um site.
Para os testes, essa divisão importa.Uma ferramenta feita para sites vê a página e só a página.Um usuário vê tudo: a barra de menus, a caixa de diálogo de arquivos do Windows que abre em Abrir, a notificação que diz que a exportação terminou, o ícone que continua na bandeja depois que a janela é fechada.
É aí que os aplicativos Electron quebram de maneiras que um teste da página nunca vê.
- A caixa de diálogo Salvar abre na pasta errada.
- Um item de menu fica desativado depois de uma atualização.
- Uma segunda janela abre atrás da primeira.
- Uma notificação dispara duas vezes, ou nunca.
- Os rótulos quebram linha em um notebook de 1366 pixels.
O que a API do Playwright para Electron cobre, e onde ela para
Entre as ferramentas de teste de interface para Electron, o Playwright é a que a maioria das equipes experimenta primeiro, porque já o usa para o aplicativo web.A classe Electron dele é documentada como suporte experimental, para o Electron 21 e posteriores.O teste inicia o aplicativo pelo script de entrada, obtém cada janela como uma página do Playwright, e executa código no processo principal com evaluate().
É um alcance real dentro do aplicativo.Cada localizador, clique e asserção que o Playwright oferece em uma página web funciona no processo de renderização, uma segunda janela chega pelo evento window, e evaluate() pode ler ou alterar o estado do aplicativo.Veja a classe ElectronApplication para a lista completa.
O limite é documentado com a mesma clareza.Chamadas de caixas de diálogo nativas, como dialog.showOpenDialog, não são interceptadas, porque vão direto para o sistema operacional, e a documentação recomenda substituir esses métodos a partir do teste por um stub que retorna o caminho de arquivo desejado.A caixa de diálogo real nunca abre, então nunca é testada.O mesmo vale para tudo o mais que o sistema operacional desenha fora da página.
| O que você testa | A API do Playwright para Electron | Um teste da tela, no GUI Test Studio |
|---|---|---|
| A página (o processo de renderização) | Cada janela é uma página: localizadores, cliques, digitação, asserções, capturas de tela. | Cliques e teclas como entrada real, e asserções do que a página desenha. |
| O processo principal | evaluate() executa o seu código nele: ler o estado do aplicativo, substituir um método por um stub. | Não é acessado diretamente.O que ele faz é verificado onde aparece: na tela. |
| Caixas de diálogo nativas de arquivo e de mensagem | Não são interceptadas, segundo a própria documentação: o teste substitui a chamada da caixa de diálogo por um stub. | A caixa de diálogo real do Windows faz parte do teste: gravada, conduzida, verificada. |
| A bandeja do sistema e os menus nativos | Não há chamada própria.O handler de um item de menu pode ser executado com evaluate(), sem o clique. | Clicados onde são desenhados, pela visão, como o usuário clica neles. |
| Notificações do sistema | Nenhuma chamada lê o que o Windows desenhou.O teste pode verificar o código que pediu uma. | Uma asserção textual aguarda as palavras da notificação na tela. |
| Uma segunda janela | Cada janela é uma página, pelo evento window ou por windows(). | Qualquer janela na tela, incluindo a caixa de diálogo sobre ela. |
| O que o usuário vê | Uma captura de tela da página de uma janela, que o teste pode comparar com uma armazenada. | A tela inteira é gravada, e cada asserção compara o que é desenhado. |
Fatos lidos na documentação do Playwright em 6 de novembro de 2026.Playwright e Electron são marcas comerciais dos respectivos proprietários; este guia não é afiliado a eles nem endossado por eles.
Uma caixa de diálogo substituída por um stub prova que o aplicativo trata um caminho de arquivo.Só a caixa de diálogo real prova que o usuário consegue escolher o arquivo.
Um teste de ponta a ponta pela página e pelo shell
Veja como testar um aplicativo Electron de ponta a ponta no GUI Test Studio, com um aplicativo de faturamento como exemplo: abrir um arquivo pela caixa de diálogo nativa, editar uma linha, exportar um PDF, e verificar a notificação que diz que terminou.
- 1
Grave o aplicativo, não a página
No GUI Test Runner-Recorder, clique em Gravar e escolha Um aplicativo.Selecione o seu aplicativo Electron, ou procure o executável dele, e marque a caixa que o inicia com o teste e o fecha no final, para que cada execução comece com o aplicativo recém-aberto.Depois, use-o como um usuário faria.
A tela inteira é sempre gravada.Escolher o aplicativo só decide de onde vêm as asserções automáticas. - 2
Abra um arquivo pela caixa de diálogo real
Clique em Abrir.Para a gravação, a caixa de diálogo de arquivos do Windows é uma janela como qualquer outra: digite o caminho do arquivo no campo do nome do arquivo e pressione Enter, e as duas coisas são gravadas como entrada real.Uma asserção da caixa de diálogo é gravada antes do clique, então a execução espera até que ela esteja realmente aberta.
Muitos aplicativos Electron também são servidos como página web.Para essa versão das mesmas telas, a etapa Enviar arquivo entrega o arquivo à página sem nenhuma caixa de diálogo.
- 3
Edite, exporte e leia a notificação
Altere uma quantidade, clique em Exportar.Quando a notificação aparecer, deixe-a na tela por um momento antes de encerrar: a gravação anota o que apareceu, e o teste ganha uma asserção disso.
- 4
Diga o que o teste deve verificar
Quando você encerra, o GUI Test Runner-Recorder pergunta o que o teste deve verificar: os elementos em que você clicou, os textos, e o que apareceu na tela.Mantenha os três ativados.Cada etapa passa a ser um bloco na linha do tempo do GUI Test Studio, e nada nela nomeia um processo.
Uma gravação, cinco momentos, três lugares
- ShellExecutar aplicativoInicia o aplicativo do zero
- PáginaClicar em AbrirAsserção visual no botão
- Caixa de diálogoDigitar o nome do arquivo, EnterAsserção textual: a caixa de diálogo está aberta
- PáginaEditar, depois ExportarAsserção textual no total
- Área de trabalhoA notificaçãoAsserção textual: Exportação concluída
As asserções que importam: textuais, visuais, de layout
Uma gravação dá ao teste as asserções que ancoram os cliques.As que vale a pena acrescentar à mão detectam o que um aplicativo Electron quebra com mais frequência.
Asserção textual
Uma asserção textual aguarda palavras: o título da caixa de diálogo, o total depois da edição, Exportação concluída na notificação, e uma asserção textual dinâmica aceita um valor de formato conhecido, como a data de hoje em um nome de arquivo.
Asserção visual
Uma asserção visual compara uma imagem: o botão Exportar, o ícone na bandeja, o item de menu que não pode estar desativado.
Asserção de layout
Uma asserção de layout verifica se os elementos de uma tela ainda estão onde deveriam, o que detecta uma janela que abriu atrás de outra ou um rótulo que quebrou linha em uma tela menor.
Cada comparação ignora o ruído de renderização que duas execuções sempre têm, um tom mais claro aqui, uma borda mais suave ali, e ainda assim detecta as regressões reais que uma pessoa chamaria de mudança: um ícone ausente, uma palavra alterada, um botão na cor errada.Veja Asserções visuais para saber o quanto cada asserção é rigorosa.
Dois hábitos fazem um teste Electron se manter firme.
- Verifique o resultado, não só os cliques: o total na tela, as palavras da notificação.
- Dê às peças nativas uma asserção própria: o título da caixa de diálogo antes de digitar nela, o item de menu antes de clicar nele.
O Relatório de confiança então diz, para cada asserção, se o elemento foi encontrado e se tem a aparência gravada, com as imagens esperada e encontrada lado a lado.Para um aplicativo de desktop cujos controles o Windows não consegue descrever, a mesma abordagem funciona só pela visão: veja como testar aplicativos Windows sem árvore de acessibilidade.
Testes automatizados de Electron a cada build
O gtr-cli, o executor de linha de comando, executa o teste exatamente como o botão Executar teste, e acrescenta o que um pipeline precisa: um código de saída, um arquivo JUnit, e todas as evidências de uma falha em uma única pasta.
gtr-cli run tests\electron --countdown 0 --junit results\junit.xml --artifacts results\artifactsA etapa Executar aplicativo no início do teste inicia o build em teste: aponte-a para o executável empacotado que o build gerou, e o mesmo teste verifica cada versão que você entrega.O agente de build precisa de uma sessão de área de trabalho do Windows conectada e desbloqueada, porque o aplicativo desenha em uma tela real.O guia de CI/CD configura isso para o TeamCity, o Jenkins, o GitHub Actions, o GitLab e o Azure DevOps.
Uma coisa não se aplica aqui.Os Navegadores e dispositivos do GUI Test Studio criam versões de um teste web para Chrome, Edge, Firefox e celulares emulados, como explica o artigo sobre testes entre navegadores.Um aplicativo Electron traz o próprio Chromium, então há um único navegador para testar, e as versões que importam são os seus builds.
O build é executado
O gtr-cli inicia o aplicativo empacotado
A jornada é reproduzida
Página, caixa de diálogo, exportação, notificação
Relatório de confiança
Regressão ou ruído, com imagens
Entregar, ou corrigir antes
Uma asserção reprovada faz o build falhar
Quando a API do Playwright para Electron ainda é a ferramenta certa
Um guia justo diz onde a outra ferramenta vence, e aqui ela vence.A API do Playwright para Electron é a escolha certa para testes em nível de código do processo principal: evaluate() lê o estado do aplicativo diretamente, uma caixa de diálogo substituída por um stub torna o teste do tratamento de arquivos rápido e exato, e nada disso precisa de uma tela.Uma equipe que já escreve testes do Playwright para o seu aplicativo web mantém os localizadores e os hábitos no processo de renderização, e executa esses testes em segundos a cada pull request.
Os dois não são rivais.Mantenha o Playwright para o processo de renderização e o processo principal, e um teste da tela para a jornada que um usuário faz pelo shell: a caixa de diálogo real, o menu real, a notificação real, no build real.Cada um detecta o que o outro não consegue ver.
Pontos principais
- 1Um aplicativo Electron é uma página mais um shell: o processo principal cuida das caixas de diálogo, dos menus, da bandeja e das notificações, e um usuário encontra todos eles.
- 2A API do Playwright para Electron alcança a página e o processo principal por código, e a própria documentação dela diz que as caixas de diálogo nativas não são interceptadas.
- 3O GUI Test Studio testa o aplicativo como o usuário o vê: a tela inteira gravada, a caixa de diálogo de arquivos real conduzida como qualquer janela, nenhum build de teste e nenhum plugin.
- 4As asserções textuais, visuais e de layout detectam o que quebra: um total errado, um ícone ausente, um item de menu desativado, uma janela atrás de outra.
- 5O mesmo teste é executado a cada build com o gtr-cli, com um arquivo JUnit para o pipeline; Navegadores e dispositivos são para páginas web, aqui as versões são os seus builds.
Perguntas
Como testar um aplicativo Electron automaticamente?
Conduza-o do jeito que um usuário faz: inicie o aplicativo, clique e digite nas janelas dele, abra as caixas de diálogo nativas, e verifique o que é desenhado na tela.O GUI Test Studio grava essa jornada uma vez e a reproduz a cada build, sem código de teste.A API do Playwright para Electron é o caminho por código, para a página e o processo principal.
O Playwright oferece suporte ao Electron?
Sim, como recurso experimental.A classe Electron do Playwright inicia um aplicativo Electron por código, entrega cada uma das janelas dele como uma página, e executa código no processo principal.A documentação dele cita o Electron versão 21 e posteriores.
O Playwright consegue testar as caixas de diálogo nativas de um aplicativo Electron?
Não como o usuário as vê.A documentação do Playwright diz que ele não intercepta chamadas de caixas de diálogo nativas, como dialog.showOpenDialog, e recomenda substituir esses métodos a partir do teste.Um teste que precisa abrir a caixa de diálogo de arquivos real precisa de uma ferramenta que conduza a tela.
Como testar as caixas de diálogo de abrir e salvar arquivos de um aplicativo Electron?
Grave-as.No GUI Test Studio, a caixa de diálogo de arquivos do Windows é uma janela como qualquer outra: o clique em Abrir, o nome do arquivo digitado e a tecla Enter são gravados e reproduzidos como entrada real, e uma asserção antes do clique garante que a caixa de diálogo esteja lá.Quando as mesmas telas são servidas como página web, a etapa Enviar arquivo entrega o arquivo sem nenhuma caixa de diálogo.
É possível testar a bandeja do sistema e as notificações de um aplicativo Electron?
Sim, quando o teste vê a tela.Um ícone na bandeja e uma notificação são desenhados pelo Windows fora da janela do aplicativo, então um teste que só alcança a página não consegue vê-los.O GUI Test Studio grava a tela inteira: um clique no ícone da bandeja é um clique, e uma asserção textual aguarda as palavras da notificação.
O GUI Test Studio precisa de um build de teste ou de um plugin dentro do aplicativo Electron?
Não.Nada é acrescentado ao aplicativo: o GUI Test Studio observa a tela, usa o mouse e o teclado como uma pessoa, e pergunta ao Windows o que o aplicativo já descreve.O build que você testa é o build que você entrega.
Os testes de aplicativos Electron podem ser executados em um pipeline de CI/CD?
Sim.O gtr-cli executa o mesmo teste em um agente de build Windows com uma sessão de área de trabalho desbloqueada, faz o build falhar quando uma asserção é reprovada, e gera um arquivo JUnit para a aba de testes do TeamCity, do Jenkins, do GitHub Actions, do GitLab ou do Azure DevOps.
Devo usar o Playwright ou o GUI Test Studio para o meu aplicativo Electron?
Use a API do Playwright para Electron para testes rápidos, em nível de código, da página e do processo principal, especialmente se a sua equipe já escreve testes do Playwright.Use o GUI Test Studio para a jornada de ponta a ponta como o usuário a vê, incluindo as caixas de diálogo nativas, a bandeja e as notificações, sem código de teste.Os dois podem conviver lado a lado.
Electron, Playwright, Chromium, Node.js, Windows, TeamCity, Jenkins, GitHub, GitLab e Azure DevOps são marcas comerciais dos respectivos proprietários.
Pronto para gravar o seu primeiro teste?
Todos os recursos, por 15 dias.
Prefere ver no tipo de aplicativo que você testa?Agende uma chamada gratuita de 30 minutos com a nossa equipe.