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.

Quadrinho: num corredor de data center com luz azul, um robô branco com camiseta «E2E Tests» trabalha numa mesa e a tela mostra passos de teste aprovados; um homem de camiseta branca faz sinal de positivo com uma caneca de café

🌐 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:

Uma execução do teste (47 s, desacelerada para dar para acompanhar): digitar o endereço, entrar como usuário de teste, clicar no documento do Word, esperar pelo Collabora, fechar, sair. As execuções normais levam cerca de 12 segundos. Música: «Ambient – Ambient Music» de JonasBlakewood via Pixabay (Pixabay Content License).
Í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:

FerramentaO que éAdequação a esta tarefa
Seleniumo veterano (desde 2004), padrão W3C WebDriver, qualquer linguagemfunciona, mas esperas, frames e vídeo pedem código ou contêineres extras
PlaywrightMicrosoft, desde 2020; Chromium, Firefox, WebKit; Python, JS, Java, .NETespera sozinho, lida com iframes aninhados, grava vídeo – a minha escolha
PuppeteerGoogle, só Chrome/Chromium, JavaScriptbom, mas só JavaScript e uma família de navegadores
Cypressexecutor de testes para desenvolvedores web, roda dentro do navegadorfeito para testar o próprio app durante o desenvolvimento, desajeitado entre domínios e iframes
Robot Frameworktestes por palavras-chave; o Checkmk o usa como «Robotmk» para monitoramento sintéticolegível, mas mais uma camada sobre Selenium ou Playwright
Grafana k6 browserferramenta de teste de carga com módulo de navegadorforte para carga, exagero para um login duas vezes por dia
Elastic Syntheticsscripts Playwright dentro da stack Elasticsó faz sentido se o Elastic já roda
Itens de navegador do Zabbixdesde o Zabbix 7.0: testes em JavaScript contra um Selenium WebDrivera opção mais integrada, mas com um contêiner Selenium à parte e menos confortável com frames
PyAutoGUImove o mouse de verdade por coordenadas de telao 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:

PassoPassa quando
página de logino formulário foi exibido – portanto o JavaScript da página funciona
logina senha do usuário de teste é aceita e o navegador sai de /login
lista de arquivoso app Arquivos mostra o documento de teste
documento carregadoa barra de status do Collabora mostra «11 palavras»
documento fechadoo frame do Collabora sumiu e a lista de arquivos voltou
logouto 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.py inicia o contêiner do Playwright com podman 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:

ItemConteúdo
e2e.ok1 passou, 0 falhou
e2e.secondsduração da execução inteira
e2e.loado passo que importa: documento exibido ou busca respondida
e2e.stepo passo que falhou
e2e.errora 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.load a 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_enforced está 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=host isso 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-id fazia 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; Escape o 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

  1. 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.
  2. Espere por uma prova, não pelo frame. A contagem de palavras na barra de status do Collabora só pode vir do documento real.
  3. 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.
  4. 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».
  5. 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.
Alguns textos e imagens deste site foram criados com a ajuda de IA ou gerados por IA. Detalhes