Come documentare un bug con screenshot passo dopo passo su Mac

Un bug report è utile quando un'altra persona riesce a riprodurre il bug senza doverti fare domande. Gli screenshot passo dopo passo eliminano la maggior parte delle ipotesi: lo sviluppatore vede ogni schermata che hai visto, nell'ordine in cui l'hai vista.

Questo articolo spiega cosa serve a un report riproducibile e come acquisire i passaggi su Mac con Action Capture di Temposhot.

Gli esempi seguono un caso concreto dall'inizio alla fine. Un'app web mostra un elenco di progetti, e rinominare un progetto non aggiorna l'elenco finché la pagina non viene ricaricata. Il caso usa un account di test, richiede 7 azioni per essere riprodotto e fallisce in 3 tentativi su 5.

Registra prima l'ambiente

Molti bug compaiono solo in una versione, in un browser o con un tipo di account. Annota l'ambiente prima di riprodurre il bug, mentre ricordi ancora la configurazione.

Dettaglio	Esempio
Versione dell'app o del sito	Numero di build dalla finestra About o dal piè di pagina
Versione di macOS	Da About This Mac (Informazioni su questo Mac)
Modello e chip del Mac	Da About This Mac (Informazioni su questo Mac)
Browser e versione	Per le app web, dalla pagina About del browser
Tipo di account o ruolo	Gratuito, a pagamento, amministratore, visualizzatore
Lingua e area	Se il bug riguarda testi, date o valute
Data e ora	Con fuso orario, così i log si possono confrontare

Copia i valori come testo. Uno screenshot della finestra About è una buona prova, ma gli sviluppatori non possono cercare dentro un'immagine.

Raccogli i valori che cambiano il risultato

Non ogni dettaglio conta per ogni bug. Registra i valori che, se fossero diversi, cambierebbero l'esito. Per il bug di rinomina contano la versione del browser e il ruolo dell'account, perché la vista elenco viene memorizzata in cache in modo diverso per i visualizzatori e per gli editor.

Un test rapido mostra quali dettagli contano. Cambia un valore, per esempio il browser, e riprova. Se il bug scompare, annotalo come risultato: "Si riproduce nel browser desktop, non nell'app mobile."

Tieni l'ambiente nella prima pagina

Inserisci il blocco dell'ambiente in cima al report, sopra i passaggi. Chi scorre un tracker legge il titolo e le prime righe prima di decidere se aprire gli allegati. Se l'ambiente si trova a pagina 6 di un PDF, lo sviluppatore potrebbe provare un altro browser e rispondere "non riproducibile".

Allega log e output della console come testo

Per un'app web, la console del browser spesso mostra un errore nel momento del guasto. Copia le righe dell'errore come testo e incollale sotto il blocco dell'ambiente. Uno screenshot della console è un'aggiunta utile, ma lo sviluppatore ha bisogno del testo per cercare il messaggio nel codice.

Conserva solo le righe vicine al guasto. Un dump della console di 400 righe con un solo errore rilevante costringe il lettore a cercarlo. Annota l'ora dell'errore, così può essere confrontata con il registro dei tentativi.

Per un'app Mac, l'equivalente è un crash report o una finestra di errore. Copia il testo della finestra esattamente com'è, incluso l'eventuale codice di errore, e acquisisci la finestra con la scorciatoia di cattura manuale durante l'esecuzione.

Indica il risultato atteso e quello effettivo

Due frasi brevi descrivono l'intero report:

• Atteso: "Dopo aver selezionato Save, il nuovo nome compare nell'elenco."
• Effettivo: "Dopo aver selezionato Save, l'elenco mostra ancora il vecchio nome. Ricaricando la pagina compare il nuovo nome."

Descrivi ciò che osservi, non la causa che immagini. "L'elenco non si aggiorna" è un'osservazione. "La cache è rotta" è un'ipotesi.

Scrivi osservazioni, non diagnosi

Le diagnosi in un bug report mandano lo sviluppatore nel posto sbagliato. Se la causa reale è un evento mancante e non una cache, "la cache è rotta" fa perdere tempo. Un'osservazione è qualcosa che chiunque può verificare sullo schermo.

Includi la soluzione alternativa come fatto, non come giudizio sulla gravità. Il team che smista il report decide la gravità.

Riproduci a partire da un punto di partenza noto

Un report che inizia con "apri l'app" quando eri già a metà di una sessione nasconde la configurazione reale. Parti da uno stato raggiungibile da chiunque: un accesso nuovo, un progetto nuovo, un URL preciso.

Riproduci il bug almeno due volte prima di registrarlo. Se compare solo a volte, annota la frequenza, per esempio "3 tentativi su 5".

Costruisci lo stato iniziale

Per il bug di rinomina, lo stato iniziale è una finestra del browser con l'utente disconnesso, sulla pagina di accesso. Disconnettersi prima cancella la sessione precedente, così lo sviluppatore parte dallo stesso punto di chi ha segnalato il bug.

Registra ogni tentativo

I bug intermittenti richiedono un breve registro dei tentativi. Annota l'ora di ogni tentativo e se è fallito, così lo sviluppatore può confrontare i tentativi con i log del server. Di solito bastano cinque tentativi per ottenere una frequenza.

Riduci il percorso al minimo

Il primo percorso che mostra un bug raramente è il più breve. Prima di registrare, prova a rimuovere un'azione alla volta e verifica se il bug compare ancora. Nell'esempio, aprire i dettagli del progetto prima di rinominarlo si è rivelato inutile, e questo ha ridotto il percorso da 9 azioni a 7.

Un percorso più corto aiuta in due modi. Lo sviluppatore spende meno tempo per ogni riproduzione, e con meno azioni ci sono meno punti in cui il lettore può prendere una strada diversa. Smetti di ridurre quando rimuovere un'altra azione fa scomparire il bug.

Se il bug non compare durante la registrazione, conserva comunque la registrazione. Ripeti le ultime azioni e premi la scorciatoia manuale quando compare il guasto. Una registrazione di un'esecuzione riuscita resta utile se mostra il percorso esatto.

Acquisisci uno screenshot per ogni azione richiesta

1. Apri Action Capture

   Premi Command+3 e seleziona Start Action Capture. Scegli Specific Window per una sola app, oppure Active Window se i passaggi attraversano più app.

2. Esegui i passaggi

   Ogni clic accettato salva la finestra subito prima del clic, così ogni pagina mostra il controllo prima che tu ci agisca.

3. Acquisisci il guasto

   Quando compare il risultato sbagliato, premi Shift+Command+2 o seleziona Capture now nella barra flottante. La schermata del guasto spesso compare senza un clic.

4. Termina l'acquisizione

   Seleziona Finish capture. Il Document si apre nell'editor con una pagina per ogni passaggio.

Con Parse clicked elements attivo, i titoli delle pagine iniziano con Click "[[element-name]]". Attiva Show cursor on click captures e Mark clicked area sotto Visual Annotations, così ogni pagina mostra dove hai cliccato. Se il bug è in Temposhot stesso, attiva Include toolbar in captures, così la barra flottante compare nei passaggi.

Configura l'esecuzione una volta

Le impostazioni in Configure Action Capture vengono salvate sul Mac e riutilizzate nelle esecuzioni successive. La configurazione creata per i bug resta attiva per il report successivo.

Scegli Specific Window per un bug all'interno di una sola finestra del browser. Un clic su un'altra finestra viene ignorato, a meno che Capture outside clicks non sia attivo. Scegli Active Window quando la riproduzione passa tra app diverse, per esempio da un link in una email a un browser.

Rientra nel limite di passaggi

Il piano gratuito prevede un limite di 5 passaggi per ogni esecuzione di Action Capture. Il bug di rinomina richiede 7 azioni più la schermata del guasto, quindi un'esecuzione gratuita si ferma dopo il quinto passaggio. I passaggi salvati fino a quel momento restano nell'esecuzione.

Ci sono due modi per gestirlo. Dividi la riproduzione in due esecuzioni in un punto naturale, per esempio dopo l'accesso, e aggiungi la seconda esecuzione allo stesso Document. Oppure attiva Temposhot Pro, che rimuove il limite e permette a una sola esecuzione di coprire tutti i passaggi.

Usa la tastiera durante l'esecuzione

Tenere le mani sulla tastiera durante una riproduzione evita clic in più che diventano pagine indesiderate. Le scorciatoie seguenti coprono l'esecuzione e la modifica successiva.

Temposhot ignora i clic che seguono troppo da vicino l'uno all'altro. Un doppio clic su un elemento dell'elenco produce un solo passaggio, non due.

Quando l'esecuzione perde dei clic

Un'esecuzione che salva meno passaggi del previsto ha poche cause possibili. Controllale in quest'ordine prima di registrare di nuovo.

• La barra flottante mostra Paused. Seleziona Resume capture; i clic fatti in pausa non vengono salvati.
• Il target è Specific Window e il clic è finito in un'altra finestra. Clicca dentro la finestra di destinazione, oppure attiva Capture outside clicks.
• Mouse click capture è impostato su una modalità che richiede o ignora un tasto tenuto premuto. Riportalo a Capture every mouse click per i report sui bug.
• Manca l'accesso per l'accessibilità. Sia Screen Recording sia Accessibility devono risultare Granted in Permissions Required.

Se tutti i titoli analizzati riportano Click here, l'app di destinazione espone pochi dati di accessibilità per i suoi controlli. I passaggi vengono comunque salvati; cambia solo la necessità di riscrivere i titoli a mano.

Aggiungi testo che spiega i cambiamenti di stato

Gli screenshot mostrano le schermate, ma non sempre mostrano cosa è cambiato tra una e l'altra. Usa la Page description per questo: "Qui il contatore dovrebbe mostrare 4. Mostra 3."

Nella pagina del guasto disegna un Rectangle (R) intorno al valore sbagliato e aggiungi un'etichetta Text (T) con il valore atteso. Elimina le pagine dei clic involontari, così la sequenza contiene solo le azioni richieste. Modifica i titoli in passaggi semplici, per esempio "Seleziona Save". La guida all'editor elenca tutti gli strumenti e le scorciatoie.

Ripulisci l'esempio

La registrazione della rinomina ha prodotto 9 pagine. Una pagina deriva da un clic su una parte vuota dell'elenco, un'altra dal clic sulla barra degli indirizzi del browser. Entrambe sono state eliminate, mentre la pagina del guasto creata con la scorciatoia manuale è stata mantenuta: restano 7 pagine di azione più la pagina del guasto.

I titoli analizzati sono un punto di partenza. Click "Rename" diventa "Seleziona Rename nel menu del progetto", che indica anche dove si trova il controllo. Le pagine in cui il parser non ha trovato un nome mostrano Click here e richiedono sempre una riscrittura.

Schemi di descrizione per i cambiamenti di stato

Tre brevi schemi coprono la maggior parte delle descrizioni di pagina in un bug report. "Prima di questo passaggio, l'elenco mostra 12 progetti" registra un valore iniziale. "Attendi 2 secondi dopo la digitazione" registra un tempo che lo screenshot non può mostrare. "Qui l'elenco dovrebbe mostrare Q3 Budget" registra lo stato atteso nella pagina in cui il comportamento fallisce.

Mantieni ogni descrizione in una o due frasi. Le descrizioni lunghe spingono lo screenshot più in basso nel PDF e, con le descrizioni impostate su Before image, il lettore vede prima il testo.

Segna la pagina del guasto

La pagina del guasto contiene più informazioni, quindi riceve più annotazioni. Di solito bastano un rettangolo intorno al vecchio nome e un'etichetta di testo con il nuovo nome. Più di 3 annotazioni sulla stessa pagina rendono più difficile trovare il valore sbagliato.

Usa Framing con un livello come Close (livello 4) sulla pagina del guasto quando l'elenco è piccolo in una finestra grande. L'immagine originale resta invariata, e Show full image la ripristina se lo sviluppatore ha bisogno del contesto completo.

Proteggi le informazioni private

I bug report vengono copiati in tracker, thread di chat e ticket dei fornitori. Considera ogni screenshot come pubblico all'interno della tua organizzazione.

• Riproduci il bug con un account di test e dati di esempio, quando possibile.
• Ritaglia barre laterali, schede del browser e notifiche con Framing (F) e Custom.
• Sfoca nomi, indirizzi email, token e ID con Blur (B, Pro).
• Rimuovi token di sessione e chiavi API da qualsiasi URL o testo di log che incolli.

Controlla ogni pagina alla dimensione di esportazione

La sfocatura che nasconde un valore sulla tela al 50 percento di zoom può risultare leggibile a dimensione piena. Imposta Blur strength nell'Object Inspector su un valore a cui il testo non è leggibile; il valore predefinito è 12 su una scala da 2 a 80. Poi scorri l'anteprima di esportazione prima di inviare.

Gli URL nella barra degli indirizzi del browser sono una fuga di dati comune. Un link di condivisione o un token di reimpostazione nella barra è visibile su ogni pagina di una riproduzione nel browser, quindi ritaglia la barra degli indirizzi con l'inquadratura o sfocala in ogni pagina.

Usa questa struttura per il bug report

1. Titolo: cosa non funziona e dove. "L'elemento rinominato non si aggiorna nella vista elenco."
2. Ambiente: i valori della tabella sopra.
3. Passaggi per riprodurre: numerati, a partire da uno stato noto.
4. Risultato atteso e Risultato effettivo.
5. Frequenza: sempre, oppure con quale frequenza.
6. Prove: la guida in screenshot esportata, più eventuali log o errori della console come testo.
7. Soluzione alternativa: se esiste.

Esporta dal Document con Export PDF per un unico allegato, oppure con More export formats per le pagine PNG che i tracker mostrano in linea. I nomi dei file immagine seguono i titoli delle pagine. La guida all'esportazione elenca tutti i formati.

Scegli l'esportazione per il tracker

I tracker differiscono nel modo in cui mostrano gli allegati. Le pagine PNG in linea funzionano quando il tracker mostra le immagini nel corpo della segnalazione, perché lo sviluppatore legge i passaggi senza aprire un file. Un singolo PDF funziona quando il tracker elenca solo gli allegati, oppure quando il report va a un fornitore esterno.

Il formato ZIP package contiene in un unico archivio le pagine PNG renderizzate e un file document.json. È adatto a un ticket di fornitore che accetta un solo file e richiede sia le immagini sia il testo delle pagine.

Un esempio compilato

Il report di rinomina si presenta così nel tracker. Il titolo è "Il progetto rinominato mantiene il vecchio nome nell'elenco dei progetti fino al ricaricamento". Il blocco dell'ambiente riporta il numero di build, la versione di macOS, la versione del browser, il ruolo editor e gli orari dei tentativi, dalle 14:02 alle 14:20.

I passaggi sono 7 righe numerate, da "Accedi come qa-editor" a "Chiudi la finestra di rinomina". Risultato atteso ed effettivo sono le due frasi viste prima, e la frequenza è "3 tentativi su 5". La prova è un PDF di 8 pagine e la soluzione alternativa è "Ricarica la pagina".

Il PDF usa le impostazioni di esportazione predefinite: A4, Landscape, copertina attiva, numeri di passaggio attivi, numeri di pagina attivi, descrizioni prima dell'immagine. Personalizzare queste impostazioni richiede Temposhot Pro; i valori predefiniti sono già adatti a un bug report.

Scrivi anche i passaggi come testo

Incolla i passaggi numerati come testo nel corpo della segnalazione anche quando il PDF li contiene già. I passaggi di testo si possono cercare, citare nei commenti e copiare in un caso di test. Gli screenshot diventano così la prova di ogni passaggio, invece dell'unica traccia.

Verifica il report prima di inviarlo

Leggi il report dall'inizio come se non avessi mai visto il bug. Meglio ancora, chiedi a un collega di seguirlo sul suo Mac. Se riproduce il bug senza fare domande, il report è pronto.

Lacune comuni emerse in una prova a secco

Una prova a secco fatta da un collega di solito trova una di tre lacune. Manca lo stato iniziale, per esempio un progetto che deve già esistere. Un passaggio avviene senza un clic, per esempio una scorciatoia da tastiera, e non ha una pagina. Oppure il guasto dipende dal tempo, per esempio selezionare Save meno di 2 secondi dopo la digitazione.

Aggiungi lo stato mancante al primo passaggio, aggiungi una pagina per l'azione da tastiera con la scorciatoia manuale e indica i tempi nella descrizione della pagina. Poi ripeti la prova a secco.

Conserva il Document di origine

Il Document resta modificabile dopo l'esportazione. Se lo sviluppatore chiede un'altra schermata, apri il Document, aggiungi la pagina con Capture new images… ed esporta di nuovo. I file già esportati non si aggiornano da soli.

Domande frequenti

Un bug report deve includere video o screenshot?

Gli screenshot funzionano per la maggior parte dei bug e sono facili da scorrere e annotare. Il video aiuta per i problemi di tempistica e le animazioni. Vedi guida agli screenshot passo dopo passo rispetto alla registrazione dello schermo.

Quanti screenshot servono in un bug report?

Uno per ogni azione richiesta più la schermata del guasto. Rimuovi le pagine che non cambiano l'esito.

Dove si trovano gli screenshot dopo che invio il report?

Il Document resta sul tuo Mac. Temposhot non offre un link ospitato, quindi allega i file esportati al tracker o al ticket.

Cosa succede se il bug richiede più di 5 passaggi con il piano gratuito?

L'esecuzione si ferma al limite di passaggi e conserva i passaggi salvati fino a quel momento. Dividi la riproduzione in due esecuzioni e aggiungile allo stesso Document, oppure usa Temposhot Pro per registrare oltre il limite.

Posso acquisire un bug che compare senza alcun clic?

Sì. Premi la scorciatoia di cattura manuale, Shift+Command+2 per impostazione predefinita, quando compare lo stato sbagliato. Il passaggio viene salvato senza clic e riceve l'impostazione del marcatore di clic, se è configurata.

Trasforma i tuoi clic in una guida passo dopo passo chiara

Action Capture registra i passaggi di riproduzione mentre li esegui, con i segni dei clic e i titoli bozza. Scarica Temposhot e allega il prossimo bug report come guida ordinata.