Um robô abre um documento do Word na minha Nextcloud duas vezes por dia: testes end-to-end com Playwright e Zabbix
Todas as minhas verificações podem estar verdes enquanto ninguém consegue abrir um documento. Por isso agora um navegador de verdade faz o que uma pessoa faz: entrar na Nextcloud, abrir um arquivo do Word no Collabora, sair e pesquisar no meu blog. Duas vezes por dia, num contêiner Podman rootless, com os resultados no Zabbix. Por que testes end-to-end, que ferramentas existem, como foi montado, um vídeo de uma execução e um repositório público.

🌐 Também em: English · Deutsch · Français · Español · Italiano · Nederlands · Polski
Em resumo: O meu monitoramento verifica se os serviços estão no ar. Não verifica se alguém consegue de fato trabalhar com eles. Agora quem faz isso, duas vezes por dia, é um navegador de verdade: ele entra nas nossas duas Nextcloud, abre um documento do Word no Collabora Online, espera até o servidor de documentos tê-lo realmente exibido, fecha-o e sai. Um terceiro teste pesquisa no meu blog. Os testes rodam com Playwright num contêiner Podman rootless, e os resultados vão para o Zabbix, que registra os tempos e dispara o alarme. Scripts e instruções estão públicos num repositório no GitHub.
É assim que uma execução aparece, gravada num navegador de verdade:
Índice
🎯 Por que os testes end-to-end dizem mais
Quase tudo o que eu monitoro é um estado. O contêiner está rodando. A porta 443 responde. O status.php diz installed: true. O certificado vale mais 60 dias. A URL de discovery do Collabora devolve XML. Cada uma dessas verificações é barata, rápida e útil – e todas podem estar verdes enquanto ninguém consegue abrir um único documento.
Entre «o serviço está no ar» e «uma pessoa consegue trabalhar» há uma corrente: a página de login precisa executar o seu JavaScript, a senha precisa ser aceita, o app Arquivos precisa listar os arquivos, a Nextcloud precisa entregar o arquivo ao Collabora via WOPI, o Collabora precisa chamar de volta, buscá-lo, convertê-lo e enviar as páginas ao navegador. Um cabeçalho de proxy que falta, uma atualização de app que quebra o visualizador, um disco cheio no lugar errado, um pacote de scripts que dá 404 depois de um upgrade – qualquer um rompe a corrente, e nenhum deixa vermelha uma única verificação de estado.
Um teste end-to-end verifica o efeito, não o estado. Faz o que uma pessoa faz e só informa sucesso se a pessoa também teria conseguido. Isso o torna a verificação mais significativa que existe. É também a mais lenta e a mais frágil, então ela vem além das verificações simples, não no lugar delas, e deve rodar raramente e só nos caminhos que realmente importam.
O que espero ganhar é sobretudo mais segurança depois das atualizações. Nextcloud, Collabora, K3s, os charts do Helm e o sistema operacional são atualizados com regularidade nos dois servidores. Até agora, depois disso, eu clicava em tudo à mão – ou, sendo sincero, às vezes não. Agora a execução seguinte me diz se a corrente inteira ainda funciona, e não só cada elo.
O que fica: Verificações de estado dizem se as peças estão vivas. Só um teste end-to-end diz se elas funcionam juntas.
🧰 As ferramentas conhecidas – e por que Playwright
A automação de navegadores é uma disciplina antiga, e há muitas ferramentas:
| Ferramenta | O que é | Adequação a esta tarefa |
|---|---|---|
| Selenium | o veterano (desde 2004), padrão W3C WebDriver, qualquer linguagem | funciona, mas esperas, frames e vídeo pedem código ou contêineres extras |
| Playwright | Microsoft, desde 2020; Chromium, Firefox, WebKit; Python, JS, Java, .NET | espera sozinho, lida com iframes aninhados, grava vídeo – a minha escolha |
| Puppeteer | Google, só Chrome/Chromium, JavaScript | bom, mas só JavaScript e uma família de navegadores |
| Cypress | executor de testes para desenvolvedores web, roda dentro do navegador | feito para testar o próprio app durante o desenvolvimento, desajeitado entre domínios e iframes |
| Robot Framework | testes por palavras-chave; o Checkmk o usa como «Robotmk» para monitoramento sintético | legível, mas mais uma camada sobre Selenium ou Playwright |
| Grafana k6 browser | ferramenta de teste de carga com módulo de navegador | forte para carga, exagero para um login duas vezes por dia |
| Elastic Synthetics | scripts Playwright dentro da stack Elastic | só faz sentido se o Elastic já roda |
| Itens de navegador do Zabbix | desde o Zabbix 7.0: testes em JavaScript contra um Selenium WebDriver | a opção mais integrada, mas com um contêiner Selenium à parte e menos confortável com frames |
| PyAutoGUI | move o mouse de verdade por coordenadas de tela | o contraexemplo: quebra a cada pixel de mudança de layout |
Escolhi Playwright com Python. Três propriedades decidiram. Ele espera sozinho: um clique espera até o elemento existir, estar visível e aceitar entrada, então o script não precisa de nenhum sleep(). Lida bem com iframes aninhados, o que importa porque o Collabora roda num frame dentro da Nextcloud. E há uma imagem de contêiner oficial com todos os navegadores, então nada precisa ser instalado no host. Além disso, a minha instalação do Zabbix já usava a mesma imagem para as capturas de tela.
O que fica: Para monitoramento, uma ferramenta que espera de forma confiável e entende frames vale mais do que o nome mais famoso.
🔍 O que os testes fazem
O teste da Nextcloud tem seis passos e mede o tempo de cada um:
| Passo | Passa quando |
|---|---|
| página de login | o formulário foi exibido – portanto o JavaScript da página funciona |
| login | a senha do usuário de teste é aceita e o navegador sai de /login |
| lista de arquivos | o app Arquivos mostra o documento de teste |
| documento carregado | a barra de status do Collabora mostra «11 palavras» |
| documento fechado | o frame do Collabora sumiu e a lista de arquivos voltou |
| logout | o navegador voltou à página de login |
O passo interessante é o quarto. O iframe do Collabora aparece segundos antes de o documento ser utilizável, e o documento em si é desenhado num canvas – o seu texto nunca aparece na página. O que aparece é a contagem de palavras na barra de status, e só o servidor de documentos pode calculá-la: a partir do arquivo real, depois que a Nextcloud o entregou e o Collabora o abriu. Se a barra mostra exatamente o número esperado, a corrente inteira funcionou:
frame = page.frame_locator("iframe[name^=collaboraframe]").first
frame.locator("#StateWordCount").filter(has_text="11 words").wait_for(timeout=90000)
O documento de teste é gerado por um pequeno script: um título, uma frase e um gráfico de barras, para que o Collabora também precise exibir uma imagem. Na primeira execução numa nuvem nova, o próprio teste o envia pelo navegador – «Novo», «Enviar arquivos», exatamente como uma pessoa.
O usuário de teste monitor-check existe só para isso: sem direitos de administrador, sem grupos, cota de 100 MB e nada dentro além do documento de teste.
O teste do blog tem três passos: abrir a página inicial, abrir a busca, pesquisar «Zabbix», esperar resultados que contenham a palavra, abrir o primeiro e verificar se título, texto e imagem estão lá. É justamente a parte que uma verificação HTTP simples não vê: a busca deste blog roda inteira no navegador do visitante (Pagefind). Se o índice faltasse depois de um build, todas as páginas continuariam respondendo 200, e a busca não encontraria nada, em silêncio.
O que fica: Espere por algo que só o sistema real pode produzir – não pelo frame, pelo indicador de carregamento nem pelo status HTTP.
🧑💻 Como o teste fica no código
Os seis passos não estão num arquivo de configuração, mas num pequeno programa em Python que controla um navegador de verdade. Cada passo é uma linha de Playwright. Resumido, o check_nextcloud.py fica assim:
page.goto(f"{URL}/login") # 1. abrir a página de login
page.locator("#user").fill(USER) # 2. digitar o usuário
page.locator("#password").fill(PASSWORD) # digitar a senha
page.locator("button[type=submit]").click() # clicar em “Entrar”
page.goto(f"{URL}/index.php/apps/files/") # 3. abrir o app Arquivos
row.click() # 4. clicar no documento Word …
frame.locator("#StateWordCount") \
.filter(has_text="11 words").wait_for() # … esperar o Collabora mostrar a contagem de palavras
frame.locator("#closebutton").click() # 5. fechar o documento
page.get_by_text("Log out").click() # 6. sair
Três comandos resolvem quase tudo: fill digita algo, click clica, wait_for espera até algo aparecer na página. Se não aparecer a tempo, o teste falhou e o nome do passo vai para o Zabbix como erro.
O arquivo de configuração targets.ini define só quais alvos são verificados, não como: uma seção por alvo com o tipo de teste (nextcloud ou site), o nome do host no Zabbix e um arquivo separado com endereço, usuário e senha (permissão 600):
# uma Nextcloud: credenciais num arquivo separado (permissão 600)
[cloud]
kind = nextcloud
credentials = .credentials-cloud
zabbix_host = Nextcloud
# arquivo .credentials-cloud: NC_URL=…, NC_USER=…, NC_PASS=…
Para verificar outra Nextcloud, basta acrescentar uma seção e um arquivo de credenciais. Para verificar outra coisa – um webmail, um wiki, uma loja – escreve-se um script curto próprio no mesmo padrão.
🐳 Como roda
Tudo fica no meu servidor de casa HP3, ao lado do Zabbix, como usuário comum sem root:
- Um cron inicia o
run.pyàs 06:57 e às 18:57. Duas vezes por dia bastam para esse tipo de verificação, e cada execução abre uma sessão real do Collabora nos servidores – algo que não quero a cada cinco minutos. - Para cada alvo, o
run.pyinicia o contêiner do Playwright compodman run. As credenciais vêm de um arquivo com permissão 600 via--env-file, nunca por linha de comando. - Se uma execução falha, ele espera dois minutos e tenta mais uma vez. Só o segundo resultado conta, para que um soluço isolado não acorde ninguém.
- Em caso de falha, são guardados uma captura de tela e o texto da página, para ver depois onde travou.
Uma execução normal leva de 11 a 14 segundos por Nextcloud e 2 segundos para o blog. O Collabora mostra o documento depois de uns 3 a 4 segundos.
O que fica: Uma verificação rara e confiável vale mais do que uma frequente e instável.
📊 Para o Zabbix
No começo o próprio script me mandava e-mails. Funcionava, mas era um segundo sistema de alarme ao lado do Zabbix, com lógica própria e sem histórico. Por isso os resultados agora vão para o Zabbix, e foi isto que mudou lá:
Cinco itens trapper por host. Um item trapper não consulta nada; ele aceita valores que alguém envia. Cada um dos três hosts (Nextcloud cvjm, Nextcloud sofie, blog) ganhou:
| Item | Conteúdo |
|---|---|
e2e.ok | 1 passou, 0 falhou |
e2e.seconds | duração da execução inteira |
e2e.load | o passo que importa: documento exibido ou busca respondida |
e2e.step | o passo que falhou |
e2e.error | a mensagem de erro |
Enviado sem software extra. O protocolo sender do Zabbix é simples – um cabeçalho fixo, o comprimento e depois JSON –, então o run.py o fala diretamente com a biblioteca padrão do Python e o pacote zabbix_sender não é necessário. Os itens só aceitam valores vindos de localhost.
Três triggers por host:
- Teste falhou (Alta). Ele depende do trigger «internet inacessível» e dos triggers de nível Alta que o host já tem. Se o servidor simplesmente caiu, o alarme existente já avisa e o trigger E2E fica quieto. Ele só dispara quando todas as verificações simples estão verdes mas o caminho pela aplicação está quebrado – exatamente o caso para o qual foi feito.
- Sem resultado há 13 horas (Média). Uma verificação que para em silêncio é pior do que nenhuma. Se o cron, a imagem ou as credenciais quebrarem, o Zabbix percebe a falta de valores.
- Lento (Aviso) se o passo principal levar mais de 30 segundos. Uma piora gradual aparece muito antes de uma queda, e o gráfico de
e2e.loada torna visível.
Testado como uma queda. Mandei ao Zabbix uma falha artificial («TEST»): o problema apareceu, o e-mail chegou, e um «ok» depois o fechou de novo. Só se o próprio Zabbix estiver inacessível é que o run.py ainda manda um e-mail por conta própria.
O que fica: Um só lugar para todos os alarmes. A dependência dos triggers existentes impede que a nova verificação grite por quedas que já foram avisadas.
🪤 Onde travou
- HTTP 401 no envio. Nas duas nuvens o
token_auth_enforcedestá ativado: clientes como o WebDAV precisam de senhas de aplicativo, e a senha normal é recusada. É um endurecimento proposital, então, em vez de enfraquecê-lo, o teste envia o documento pelo navegador. - O formulário de login nunca aparecia. Na rede padrão do Podman rootless, o Chromium via uma mudança de rede logo após o contêiner iniciar (
ERR_NETWORK_CHANGED) e descartava o JavaScript da página. Com--network=hostisso sumiu. - «Navegador não suportado». A Nextcloud manda navegadores desconhecidos para
/unsupported. O meu próprio user agent era incomum demais; agora é a string normal do Chrome com «e2e-check» no fim, para que as execuções continuem reconhecíveis nos logs. - A partida do contêiner travava por minutos. O
--userns=keep-idfazia o Podman copiar a imagem de 2,6 GB com os donos reescritos. No Podman rootless isso nem é necessário: o root dentro do contêiner já é o meu usuário. /apps/files/devolvia 403 atrás do nginx de uma das instalações;/index.php/apps/files/funciona em todas.- O tour de boas-vindas. Na primeira abertura, o Collabora mostra um tour sobre o documento;
Escapeo fecha.
O que fica: A maioria dos problemas não estava no teste, mas no ambiente em volta – rede, user agent, configurações de segurança. Cada um agora é um comentário no código.
🎬 Como o vídeo foi feito
Um navegador headless não tem barra de endereços nem ponteiro de mouse, então as verificações normais não podem ser filmadas de um jeito que pareça uma pessoa. Para o vídeo, um script de demonstração separado roda num contêiner com uma tela virtual (Xvfb): abre-se uma janela do Chrome visível, o endereço é digitado na barra, e o ponteiro de verdade vai até cada elemento e clica (xdotool). O ffmpeg grava a tela e acrescenta uma legenda por passo. Dois detalhes importaram: o balão do Chrome «Salvar senha?» cobria o menu do usuário e teve de ser desligado no perfil, e --test-type remove a barra de aviso sobre --no-sandbox. A música é «Ambient – Ambient Music», de JonasBlakewood, do Pixabay.
📦 O repositório
Tudo está público como e2e-browser-check, com marcadores no lugar dos meus servidores: os dois testes, o run.py com a nova tentativa e o envio ao Zabbix, o zbx_setup.py para itens e triggers, o gerador do documento de teste, cron e timer do systemd, a gravação da demonstração e um README que explica passo a passo a instalação, o lado do Zabbix e as armadilhas. O cliente da API do Zabbix vem do meu repositório anterior zabbix-podman-homelab.
🎯 As lições
- Um status verde não é um serviço funcionando. Só um teste que faz o que um usuário faz mostra se a corrente aguenta.
- Espere por uma prova, não pelo frame. A contagem de palavras na barra de status do Collabora só pode vir do documento real.
- Raramente e de forma confiável. Duas vezes por dia com uma nova tentativa basta para um teste end-to-end; as verificações simples cobrem os minutos entre elas.
- Um só sistema de alarme. Resultados no Zabbix, com dependências, para que uma queda conhecida não toque duas vezes – e com um trigger para «a própria verificação parou».
- Respeite o seu próprio endurecimento. Quando o teste esbarrou no
token_auth_enforced, a solução certa era mudar o teste, não o servidor.
