Un robot apre un documento Word nella mia Nextcloud due volte al giorno: test end-to-end con Playwright e Zabbix

Tutti i miei controlli possono essere verdi mentre nessuno riesce ad aprire un documento. Così ora un vero browser fa quello che fa una persona: accede a Nextcloud, apre un file Word in Collabora, esce e cerca nel mio blog. Due volte al giorno, in un container Podman rootless, con i risultati in Zabbix. Perché i test end-to-end, quali strumenti esistono, come è costruito, un video di un'esecuzione e un repository pubblico.

Fumetto: in un corridoio di data center con luce blu un robot bianco con la maglietta «E2E Tests» lavora a una scrivania, lo schermo mostra passi di test superati; un uomo in maglietta bianca alza il pollice con una tazza di caffè

🌐 Anche in: English · Deutsch · Français · Español · Português · Nederlands · Polski

In breve: Il mio monitoring controlla se i servizi girano. Non controlla se qualcuno ci può davvero lavorare. Adesso lo fa un vero browser due volte al giorno: accede alle nostre due Nextcloud, apre un documento Word in Collabora Online, aspetta che il server dei documenti lo abbia davvero visualizzato, lo chiude ed esce. Un terzo test cerca nel mio blog. I test girano con Playwright in un container Podman rootless e i risultati finiscono in Zabbix, che registra i tempi e dà l’allarme. Script e istruzioni sono pubblici in un repository GitHub.

Ecco un’esecuzione, registrata in un vero browser:

Un'esecuzione del test (47 s, rallentata per poterla seguire): digitare l'indirizzo, accedere come utente di prova, cliccare sul documento Word, aspettare Collabora, chiudere, uscire. Le esecuzioni normali durano circa 12 secondi. Musica: «Ambient – Ambient Music» di JonasBlakewood tramite Pixabay (Pixabay Content License).
Indice

🎯 Perché i test end-to-end dicono di più

Quasi tutto ciò che sorveglio è uno stato. Il container gira. La porta 443 risponde. status.php dice installed: true. Il certificato vale altri 60 giorni. L’URL di discovery di Collabora restituisce XML. Ognuno di questi controlli è economico, veloce e utile – e tutti possono essere verdi mentre nessuno riesce ad aprire un solo documento.

Tra «il servizio gira» e «una persona può lavorare» c’è una catena: la pagina di accesso deve eseguire il suo JavaScript, la password deve essere accettata, l’app File deve elencare i file, Nextcloud deve passare il file a Collabora tramite WOPI, Collabora deve richiamare, prenderlo, convertirlo e mandare le pagine al browser. Un header del proxy mancante, l’aggiornamento di un’app che rompe il visualizzatore, un disco pieno nel posto sbagliato, un bundle di script che dà 404 dopo un upgrade – ognuno spezza la catena, e nessuno fa diventare rosso un solo controllo di stato.

Un test end-to-end verifica l’effetto, non lo stato. Fa quello che fa una persona e segnala successo solo se anche la persona ce l’avrebbe fatta. Per questo è il controllo più significativo che esista. È anche il più lento e il più fragile: va quindi aggiunto ai controlli semplici, non messo al loro posto, e deve girare di rado e solo sui percorsi che contano davvero.

Quello che spero di ottenere è soprattutto più sicurezza dopo gli aggiornamenti. Nextcloud, Collabora, K3s, i chart Helm e il sistema operativo vengono aggiornati regolarmente su entrambi i server. Finora dopo controllavo a mano – o, a essere sincero, a volte no. Adesso l’esecuzione successiva mi dice se tutta la catena funziona ancora, non solo ogni singolo anello.

Cosa portarsi via: I controlli di stato dicono se i pezzi sono vivi. Solo un test end-to-end dice se funzionano insieme.

🧰 Gli strumenti noti – e perché Playwright

L’automazione dei browser è una disciplina vecchia e gli strumenti sono tanti:

StrumentoChe cos’èAdatto a questo compito
Seleniumil veterano (dal 2004), standard W3C WebDriver, qualsiasi linguaggiofunziona, ma attese, frame e video richiedono codice o container in più
PlaywrightMicrosoft, dal 2020; Chromium, Firefox, WebKit; Python, JS, Java, .NETaspetta da solo, gestisce iframe annidati, registra video – la mia scelta
PuppeteerGoogle, solo Chrome/Chromium, JavaScriptbuono, ma solo JavaScript e una famiglia di browser
Cypresstest runner per sviluppatori web, gira dentro il browserpensato per testare la propria app durante lo sviluppo, scomodo tra domini e iframe
Robot Frameworktest a parole chiave; Checkmk lo usa come «Robotmk» per il monitoring sinteticoleggibile, ma un altro strato sopra Selenium o Playwright
Grafana k6 browserstrumento per test di carico con modulo browserforte per il carico, eccessivo per un login due volte al giorno
Elastic Syntheticsscript Playwright dentro lo stack Elasticha senso solo se Elastic gira già
Item browser di Zabbixda Zabbix 7.0: test in JavaScript contro un Selenium WebDriverla soluzione più integrata, ma con un container Selenium a parte e meno comoda con i frame
PyAutoGUImuove il mouse reale per coordinate dello schermoil controesempio: si rompe a ogni pixel di layout cambiato

Ho scelto Playwright con Python. Hanno deciso tre proprietà. Aspetta da solo: un clic attende che l’elemento esista, sia visibile e accetti input, quindi lo script non ha bisogno di alcun sleep(). Gestisce in modo pulito gli iframe annidati, ed è importante perché Collabora gira in un frame dentro Nextcloud. E c’è un’immagine container ufficiale con tutti i browser, quindi sull’host non si installa nulla. In più la mia installazione di Zabbix usava già la stessa immagine per i suoi screenshot.

Cosa portarsi via: Per il monitoring, uno strumento che aspetta in modo affidabile e gestisce i frame batte il nome più famoso.

🔍 Cosa fanno i test

Il test di Nextcloud ha sei passi e misura il tempo di ciascuno:

PassoSuperato quando
pagina di accessoil modulo è stato visualizzato – quindi il JavaScript della pagina funziona
accessola password dell’utente di prova viene accettata e il browser lascia /login
elenco filel’app File mostra il documento di prova
documento caricatola barra di stato di Collabora mostra «11 parole»
documento chiusoil frame di Collabora è sparito e l’elenco dei file è tornato
uscitail browser è di nuovo sulla pagina di accesso

Il passo interessante è il quarto. L’iframe di Collabora compare qualche secondo prima che il documento sia utilizzabile, e il documento stesso viene disegnato su un canvas: il suo testo non compare mai nella pagina. Ciò che compare è il numero di parole nella barra di stato, e solo il server dei documenti può calcolarlo: dal file vero, dopo che Nextcloud gliel’ha passato e Collabora l’ha aperto. Se la barra mostra esattamente il numero atteso, tutta la catena ha funzionato:

frame = page.frame_locator("iframe[name^=collaboraframe]").first
frame.locator("#StateWordCount").filter(has_text="11 words").wait_for(timeout=90000)

Il documento di prova lo genera un piccolo script: un titolo, una frase e un grafico a barre, così Collabora deve visualizzare anche un’immagine. Alla prima esecuzione su una nuova cloud il test lo carica da solo tramite il browser – «Nuovo», «Carica file», esattamente come una persona.

L’utente di prova monitor-check esiste solo per questo: nessun diritto di amministratore, nessun gruppo, 100 MB di quota e dentro nient’altro che il documento di prova.

Il test del blog ha tre passi: aprire la home, aprire la ricerca, cercare «Zabbix», aspettare risultati che contengano la parola, aprire il primo e controllare che titolo, testo e immagine ci siano. È proprio la parte che un semplice controllo HTTP non vede: la ricerca di questo blog gira interamente nel browser del visitatore (Pagefind). Se dopo una build mancasse il suo indice, ogni pagina risponderebbe comunque 200 e la ricerca non troverebbe più nulla, in silenzio.

Cosa portarsi via: Aspettare qualcosa che solo il sistema vero può produrre – non il frame, l’indicatore di caricamento o lo stato HTTP.

🧑‍💻 Com’è il test nel codice

I sei passi non stanno in un file di configurazione, ma in un piccolo programma Python che pilota un vero browser. Ogni passo è una riga di Playwright. Abbreviato, check_nextcloud.py è così:

page.goto(f"{URL}/login")                     # 1. aprire la pagina di login
page.locator("#user").fill(USER)              # 2. digitare il nome utente
page.locator("#password").fill(PASSWORD)      #    digitare la password
page.locator("button[type=submit]").click()   #    cliccare su «Accedi»
page.goto(f"{URL}/index.php/apps/files/")     # 3. aprire l'app File
row.click()                                   # 4. cliccare sul documento Word …
frame.locator("#StateWordCount") \
     .filter(has_text="11 words").wait_for()  #    … attendere che Collabora mostri il numero di parole
frame.locator("#closebutton").click()         # 5. chiudere il documento
page.get_by_text("Log out").click()            # 6. disconnettersi

Tre comandi bastano per quasi tutto: fill digita qualcosa, click clicca, wait_for aspetta che qualcosa compaia sulla pagina. Se non compare in tempo, il test è fallito e il nome del passo va a Zabbix come errore.

Il file di configurazione targets.ini stabilisce solo quali obiettivi vengono controllati, non come: una sezione per obiettivo con il tipo di test (nextcloud o site), il nome dell’host in Zabbix e un file a parte con indirizzo, utente e password (permessi 600):

# una Nextcloud: credenziali in un file a parte (permessi 600)
[cloud]
kind = nextcloud
credentials = .credentials-cloud
zabbix_host = Nextcloud
# file .credentials-cloud: NC_URL=…, NC_USER=…, NC_PASS=…

Per controllare un’altra Nextcloud basta aggiungere una sezione e un file di credenziali. Per controllare altro – una webmail, un wiki, un negozio – si scrive un breve script proprio con lo stesso schema.

🐳 Come gira

Tutto sta sul mio server di casa HP3, accanto a Zabbix, come utente normale senza root:

  • Un cron avvia run.py alle 06:57 e alle 18:57. Due volte al giorno bastano per questo tipo di controllo, e ogni esecuzione apre una vera sessione Collabora sui server, cosa che non voglio ogni cinque minuti.
  • Per ogni obiettivo run.py avvia il container Playwright con podman run. Le credenziali arrivano da un file con permessi 600 tramite --env-file, mai da riga di comando.
  • Se un’esecuzione fallisce, aspetta due minuti e riprova una volta. Conta solo il secondo risultato, così un singhiozzo isolato non sveglia nessuno.
  • In caso di errore vengono salvati uno screenshot e il testo della pagina, per vedere dopo dove si è bloccato.

Un’esecuzione normale dura da 11 a 14 secondi per Nextcloud e 2 secondi per il blog. Collabora mostra il documento dopo circa 3–4 secondi.

Cosa portarsi via: Un controllo raro e affidabile vale più di uno frequente e traballante.

📊 Dentro Zabbix

All’inizio lo script mi mandava le mail da solo. Funzionava, ma era un secondo sistema di allarme accanto a Zabbix, con la sua logica e senza storico. Così ora i risultati vanno in Zabbix, ed ecco cosa è cambiato lì:

Cinque item trapper per host. Un item trapper non interroga nulla; accetta valori che qualcuno invia. Ognuno dei tre host (Nextcloud cvjm, Nextcloud sofie, blog) ha ricevuto:

ItemContenuto
e2e.ok1 superato, 0 fallito
e2e.secondsdurata dell’intera esecuzione
e2e.loadil passo che conta: documento visualizzato o ricerca che ha risposto
e2e.stepil passo fallito
e2e.erroril messaggio di errore

Inviato senza software aggiuntivo. Il protocollo sender di Zabbix è semplice – un’intestazione fissa, la lunghezza, poi JSON – quindi run.py lo parla direttamente con la libreria standard di Python e il pacchetto zabbix_sender non serve. Gli item accettano valori solo da localhost.

Tre trigger per host:

  • Test fallito (Alta). Dipende dal trigger «Internet irraggiungibile» e dai trigger di livello Alta già presenti sull’host. Se il server è semplicemente giù, parla già l’allarme esistente e il trigger E2E tace. Scatta solo quando tutti i controlli semplici sono verdi ma il percorso dentro l’applicazione è rotto – esattamente il caso per cui è stato costruito.
  • Nessun risultato da 13 ore (Media). Un controllo che si ferma in silenzio è peggio di nessun controllo. Se si rompono cron, immagine o credenziali, Zabbix nota i valori mancanti.
  • Lento (Avviso) se il passo chiave supera i 30 secondi. Un peggioramento graduale si vede molto prima di un guasto, e il grafico di e2e.load lo rende visibile.

Provato come un guasto. Ho mandato a Zabbix un errore artificiale («TEST»): il problema è comparso, la mail è arrivata, e un «ok» successivo l’ha richiuso. Solo se Zabbix stesso è irraggiungibile run.py manda ancora una mail per conto suo.

Cosa portarsi via: Un solo posto per tutti gli allarmi. La dipendenza dai trigger esistenti impedisce al nuovo controllo di urlare per guasti già segnalati.

🪤 Dove si è inceppato

  • HTTP 401 al caricamento. Su entrambe le cloud è attivo token_auth_enforced: client come WebDAV hanno bisogno di password per app e la password normale viene rifiutata. È un irrigidimento voluto, quindi invece di indebolirlo il test carica il documento tramite il browser.
  • Il modulo di accesso non compariva mai. Nella rete predefinita di Podman rootless, Chromium vedeva un cambio di rete subito dopo l’avvio del container (ERR_NETWORK_CHANGED) e scartava il JavaScript della pagina. Con --network=host il problema è sparito.
  • «Browser non supportato». Nextcloud manda i browser sconosciuti su /unsupported. Il mio user agent era troppo insolito; ora è quello normale di Chrome con «e2e-check» in coda, così le esecuzioni restano riconoscibili nei log.
  • L’avvio del container restava appeso per minuti. --userns=keep-id faceva copiare a Podman l’immagine da 2,6 GB con i proprietari riscritti. In Podman rootless non serve affatto: root nel container è già il mio utente.
  • /apps/files/ restituiva 403 dietro l’nginx di una delle installazioni; /index.php/apps/files/ funziona ovunque.
  • Il tour di benvenuto. Alla prima apertura Collabora mostra un tour sopra il documento; Esc lo chiude.

Cosa portarsi via: La maggior parte dei problemi non era nel test, ma nell’ambiente intorno – rete, user agent, impostazioni di sicurezza. Ognuno ora è un commento nel codice.

🎬 Come è nato il video

Un browser headless non ha barra degli indirizzi né puntatore, quindi i controlli normali non si possono filmare in modo che sembri una persona. Per il video, uno script demo a parte gira in un container con uno schermo virtuale (Xvfb): si apre una finestra di Chrome visibile, l’indirizzo viene digitato nella barra e il vero puntatore si sposta su ogni elemento e clicca (xdotool). ffmpeg registra lo schermo e aggiunge una didascalia per ogni passo. Due dettagli hanno contato: la bolla di Chrome «Salvare la password?» copriva il menu utente e andava disattivata nel profilo, e --test-type toglie la barra di avviso su --no-sandbox. La musica è «Ambient – Ambient Music» di JonasBlakewood, da Pixabay.

📦 Il repository

Tutto è pubblico come e2e-browser-check, con segnaposto al posto dei miei server: i due test, run.py con il nuovo tentativo e l’invio a Zabbix, zbx_setup.py per item e trigger, il generatore del documento di prova, cron e timer systemd, la registrazione della demo e un README che spiega passo per passo installazione, lato Zabbix e insidie. Il client per l’API di Zabbix viene dal mio repository precedente zabbix-podman-homelab.

🎯 Le lezioni

  1. Uno stato verde non è un servizio che funziona. Solo un test che fa ciò che fa un utente mostra se la catena regge.
  2. Aspettare una prova, non il frame. Il numero di parole nella barra di stato di Collabora può venire solo dal documento vero.
  3. Di rado e in modo affidabile. Due volte al giorno con un nuovo tentativo bastano per un test end-to-end; i controlli semplici coprono i minuti nel mezzo.
  4. Un solo sistema di allarme. Risultati in Zabbix, con dipendenze, così un guasto noto non suona due volte – e con un trigger per «il controllo stesso si è fermato».
  5. Rispettare il proprio irrigidimento. Quando il test è andato a sbattere contro token_auth_enforced, la soluzione giusta era cambiare il test, non il server.
Alcuni testi e immagini di questo sito sono creati con l’aiuto dell’IA o generati dall’IA. Dettagli