Come documentare un bug con screenshot passo passo sul Mac

Questa guida spiega come raccogliere prove tramite screenshot per un bug software che un'altra persona possa riprodurre. Registrerai l'ambiente, definirai il risultato atteso e quello effettivo, acquisirai le azioni necessarie, ripulirai le prove e proverai la segnalazione un'ultima volta prima di inviarla.

In breve: una segnalazione utile combina uno stato iniziale chiaro, passaggi di riproduzione precisi, risultati attesi ed effettivi, frequenza, dati sull'ambiente e prove del primo errore visibile.

Registra prima l'ambiente

L'ambiente indica dove si verifica il bug. Annota la versione dell'app, la versione di macOS, il tipo di dispositivo, lo stato dell'account o dei permessi e ogni impostazione che modifica il comportamento.

Le informazioni devono essere abbastanza precise da ricreare le condizioni. «Ultima versione» diventa ambiguo al rilascio successivo; «Shotomatic 1.8.2 su macOS 15.5» resta utile anche in seguito.

Includi questi campi quando sono pertinenti:

• versione dell'app e della build;
• versione di macOS;
• modello del Mac o architettura del processore;
• tipo di account o piano;
• browser e relativa versione;
• schermo o dispositivo di input collegato;
• permessi e impostazioni delle funzioni rilevanti;
• stato della rete.

Indica il risultato atteso e quello effettivo

La coppia di risultati definisce il problema prima che chi lo esamina legga i passaggi. Scrivi una frase su ciò che dovrebbe accadere e una su ciò che accade invece.

Descrivi risultati osservabili, non una diagnosi. «Il pulsante Export PDF non produce alcun effetto» è una prova. «Il servizio di esportazione è guasto» presume una causa non ancora verificata.

Per esempio:

Atteso: selezionando Export PDF si apre una finestra di salvataggio.

Effettivo: selezionando Export PDF il menu si chiude, ma non compare alcuna finestra di salvataggio e non viene creato nessun file.

Aggiungi la frequenza accanto al risultato. Specifica se il problema si verifica sempre, saltuariamente o soltanto dopo una particolare azione precedente.

Riproduci il problema da un punto di partenza noto

Un punto di partenza noto elimina dalla segnalazione le configurazioni nascoste. Chiudi e riapri l'app, crea nuovi dati di prova oppure ripristina l'impostazione interessata prima di acquisire la sequenza.

Verifica il bug una volta partendo da quello stato. Se non si presenta più, annota che cosa è cambiato invece di ricostruire a memoria una sequenza presentata come certa.

Acquisisci uno screenshot per ogni azione necessaria

Ogni screenshot deve aiutare a ripetere l'azione successiva o a riconoscere l'errore. Acquisisci lo stato iniziale, ogni clic o dato richiesto, il primo stato errato e qualsiasi messaggio che possa aiutare la diagnosi.

Tralascia le azioni che non influiscono sul risultato. Spostare una finestra o aprire un pannello estraneo aggiunge rumore, a meno che non faccia parte della condizione che innesca il bug.

Se usi Action Capture, parti dallo stato pulito e riproduci il problema a velocità normale. Shotomatic salva lo stato di destinazione subito prima di ogni clic accettato e ne indica la posizione, fornendo una prima bozza dei passaggi. Le sessioni Free consentono 5 passaggi salvati; Pro elimina il limite per sessione.

Aggiungi il testo che spiega i cambiamenti di stato

Il testo breve deve spiegare ciò che lo screenshot da solo non mostra. Indica il comando, il valore da inserire e il passaggio atteso dopo l'azione.

Scrivi i passaggi in questa forma:

1. Azione: seleziona Export PDF.
2. Verifica attesa: si apre una finestra di salvataggio.
3. Risultato osservato: il menu si chiude e non compare alcuna finestra.

Evita frasi che ripetono soltanto un indicatore visibile, come «fai clic qui». L'indicatore mostra già il punto. La frase deve dire che cos'è il comando e che cosa controllare dopo.

Proteggi le informazioni private

Le informazioni private vanno rimosse prima che la segnalazione esca dall'ambiente di prova. Quando puoi, usa account e dati di esempio: sostituire i dati all'origine è più sicuro che coprirli in seguito.

Se non puoi evitare dati reali, ritaglia le aree estranee e sfoca nomi, indirizzi email, messaggi, token, dettagli della licenza, dati dei clienti e anteprime delle notifiche. Mantieni abbastanza interfaccia intorno al soggetto da rendere riconoscibile la schermata.

Per decidere come usare ritaglio, sfocatura e dati di esempio, esegui un controllo separato dedicato alla rimozione delle informazioni sensibili.

Usa questa struttura per la segnalazione

La struttura seguente mantiene completa la segnalazione senza trasformarla in un racconto lungo:

Titolo:

Ambiente:
- Versione app/build:
- macOS/dispositivo:
- Stato account o permessi:
- Impostazioni rilevanti:

Risultato atteso:

Risultato effettivo:

Frequenza:

Prerequisiti:

Passaggi per riprodurre il problema:
1.
2.
3.

Prove:
- Screenshot per ogni azione necessaria
- Primo errore visibile
- Messaggio di errore o log, se pertinente

Soluzione temporanea:

Note aggiuntive:

È una struttura di scrittura, non un modello importabile in Shotomatic. Copiala nel sistema di gestione dei problemi o nell'ambiente di assistenza già usato dal tuo team.

Prova la segnalazione prima di inviarla

Un'ultima riproduzione fa emergere le premesse mancanti. Parti dall'ambiente indicato nella segnalazione e segui soltanto i passaggi scritti, senza affidarti alla memoria.

La segnalazione è pronta quando la stessa sequenza raggiunge il risultato indicato, sono presenti tutti i valori necessari e gli screenshot mostrano le schermate giuste nell'ordine corretto. Se un passaggio dipende dalla tempistica o dal movimento, allega un breve video come prova aggiuntiva, ma mantieni la sequenza scritta come riferimento principale.

Action Capture può raccogliere la sequenza di clic, ma la segnalazione deve comunque includere ambiente, risultato atteso, risultato effettivo e frequenza. Per il flusso generale di acquisizione e modifica, consulta Come creare una guida passo passo dai clic sul Mac.