Qualcuno ti chiede un file HAR. Di solito è il supporto, o uno sviluppatore che sta guardando un bug che hai segnalato, e quasi sempre la richiesta arriva con istruzioni che danno per scontato che tu sappia già di cosa si tratta.

Un file HAR è la registrazione di tutte le richieste fatte dal browser mentre stavi facendo qualcosa, salvata in un unico file. HAR sta per HTTP Archive. È un normale file JSON che elenca ogni richiesta inviata dalla pagina, che cosa è tornato indietro, quanto ci ha messo ognuna e in che ordine: la scheda Rete degli strumenti per sviluppatori del tuo browser, messa per iscritto e consegnata.

Cosa contiene

Per ogni richiesta fatta dalla pagina durante la registrazione:

  • La richiesta: metodo, URL completo, intestazioni, query string e il corpo, se c’era
  • La risposta: codice di stato, intestazioni, tipo di contenuto, dimensione e spesso il corpo
  • I tempi: quanto la richiesta ha atteso, quanto ci ha messo a connettersi, a inviare e ad avere il primo byte
  • Quando è successo, così l’ordine e le pause tra una richiesta e l’altra restano leggibili

È quest’ultimo punto a rendere un HAR più utile di uno screenshot della scheda Rete. Uno screenshot ti mostra un elenco; un HAR permette a qualcuno di rigiocare la sequenza e vedere che il rinnovo del token è partito dopo la richiesta che ne aveva bisogno.

Quando te lo chiedono

Quasi sempre perché il problema è invisibile dall’esterno e capita solo a te.

  • Una pagina si carica da te e non da loro, o viceversa
  • Qualcosa fallisce in silenzio, senza che l’interfaccia lo dica
  • Una richiesta è lenta e nessuno sa dire se sia la rete, il server o il browser
  • Un’integrazione restituisce un errore solo in produzione, solo per un account

In tutti questi casi la risposta è di solito una riga in un file che nessuno ha guardato: un 403 dove ci si aspettava un 200, una richiesta che non è mai partita, un ciclo di redirect, un errore CORS che la pagina si è ingoiata.

Come registrarne uno

Chrome o Edge. Apri gli strumenti per sviluppatori con F12, oppure Cmd + Option + I su un Mac. Vai alla scheda Rete. Spunta Conserva log così un redirect non cancella quello che hai registrato. Riproduci il problema. Poi fai clic destro su una riga qualsiasi dell’elenco e scegli Salva tutto come HAR con contenuto.

Firefox. Strumenti per sviluppatori, scheda Rete, riproduci, poi clic destro su una riga e Salva tutto come HAR.

Safari. Attiva il menu Sviluppo nelle impostazioni, poi Sviluppo, Mostra Web Inspector, Rete ed Esporta.

Due cose che sfuggono. Comincia a registrare prima di fare quello che vuoi mostrare, perché la scheda Rete tiene solo quello che ha visto. E riproduci il problema una volta e fermati: un HAR di undici minuti di clic è un file che non leggerà nessuno.

Leggerlo senza strumenti

La strada più rapida è aprire il file nella scheda Rete di un browser: trascina l’HAR sul pannello Rete e si carica come se lo avessi registrato tu, ordinabile e filtrabile.

Cosa guardare, più o meno in quest’ordine:

Non questo per primo
Scorrere tutto l'elenco cercando qualcosa che sembri sbagliato
Prima questo
Filtrare per stato 400 e oltre, poi per le poche richieste più lente, poi guardare cos'è successo subito prima dell'errore

Un HAR è JSON, quindi ci lavora anche jq: jq '.log.entries[] | select(.response.status >= 400) | {url: .request.url, status: .response.status}' capture.har ti tira fuori gli errori in una riga.

Un HAR contiene solo le richieste fatte dal browser. Per ispezionare una richiesta che invia il tuo codice, puntalo all’endpoint di prova per i webhook, che ti dà un URL e ti mostra metodo, intestazioni, query string e corpo di quello che arriva.

La parte di cui nessuno ti avverte

Un file HAR di solito contiene credenziali. È la cosa più importante da sapere, e le istruzioni che ti mandano quasi mai la nominano.

Salvato con il contenuto, un HAR contiene ogni intestazione di richiesta, quindi cookie di sessione e token di autorizzazione, e ogni corpo di risposta, che può includere dati personali di chi era autenticato. Chi ha il file può spesso agire come quell’utente finché quei token non scadono.

Quindi:

  • Tratta un HAR come una password. Non incollarlo in un tracker pubblico, in un canale condiviso o in una catena di email destinata a essere inoltrata.
  • Ripuliscilo prima di condividerlo, se puoi. Alcuni strumenti tolgono i cookie e le intestazioni di autorizzazione; altrimenti apri il JSON e toglili a mano.
  • Registra in una finestra privata con un account di prova quando il problema lo consente: è quello che tiene i dati veri dei clienti completamente fuori dal file.
  • Cancellalo dopo. È la prova di un’indagine, non un documento.

Se sei tu a chiedere un HAR, scrivi tutto questo nella richiesta. Alla maggior parte delle persone che te ne mandano uno con il token di sessione ancora valido non lo aveva detto nessuno.

Averlo senza le istruzioni

Tutto quello che precede sono quattro paragrafi di istruzioni per qualcuno che vuole solo segnalare che una pagina è rotta, ed è per questo che i file HAR tanto spesso non arrivano affatto.

Session Replay

Estensione gratuita per Chrome. Un clic sulla pagina che si comporta male cattura lo screenshot, la console e il registro di rete, e ti restituisce un link da incollare nel ticket.

Installa l'estensione

Il registro di rete che cattura comprende un file HAR che puoi scaricare e aprire negli strumenti per sviluppatori, così chi prende in carico la segnalazione ha lo stesso file che avrebbe chiesto, senza aver dovuto chiederlo. Quello che non fa è decidere al posto tuo cosa oscurare: l’avvertenza qui sopra vale ancora per tutto ciò che condividi.

Per tutto quello che sta intorno al file - cosa ti aspettavi, cos’è successo e di che build si trattava - la guida alla segnalazione di bug ha il modello.