Fehler mit Schritt-für-Schritt-Screenshots auf dem Mac dokumentieren

Ein Fehlerbericht ist nur dann brauchbar, wenn ein anderer den Fehler daraus reproduzieren kann, ohne Ihnen eine Rückfrage zu stellen. Schritt-für-Schritt-Screenshots beseitigen den größten Teil des Rätselratens: Der Entwickler sieht jeden Bildschirm, den Sie gesehen haben, in der richtigen Reihenfolge.

Dieser Beitrag beschreibt, was ein reproduzierbarer Bericht enthalten muss, und wie Sie die Schritte auf dem Mac mit Temposhot Action Capture erfassen.

Die Beispiele unten folgen einem durchgehenden Fall von Anfang bis Ende. Eine Web-App zeigt eine Projektliste. Nach dem Umbenennen eines Projekts aktualisiert sich die Liste erst, wenn die Seite neu geladen wird. Der Fall verwendet ein Testkonto, benötigt 7 erforderliche Aktionen zur Reproduktion und schlägt in 3 von 5 Versuchen fehl.

Umgebung zuerst festhalten

Viele Fehler treten nur in einer bestimmten Version, in einem bestimmten Browser oder bei einem bestimmten Kontotyp auf. Notieren Sie die Umgebung vor der Reproduktion, solange Sie den Aufbau noch im Kopf haben.

Angabe	Beispiel
App- oder Site-Version	Build-Nummer aus dem Fenster „About“ oder aus der Fußzeile
macOS-Version	Aus „About This Mac“
Mac-Modell und Chip	Aus „About This Mac“
Browser und Version	Bei Web-Apps von der Seite „About“ des Browsers
Kontotyp oder Rolle	Free, Paid, Admin, Viewer
Sprache und Region	Wenn der Fehler Text, Datum oder Währung betrifft
Datum und Uhrzeit	Mit Zeitzone, damit sich Logs zuordnen lassen

Kopieren Sie die Werte als Text. Ein Screenshot des Fensters „About“ ist ein gutes Beweismittel, aber Entwickler können in einem Bild nicht suchen.

Werte erfassen, die das Ergebnis ändern

Nicht jede Angabe ist für jeden Fehler relevant. Erfassen Sie die Werte, die das Ergebnis verändern könnten, wenn sie anders wären. Beim Umbenennungsfehler sind die Browser-Version und die Kontorolle relevant, weil die Listenansicht für Viewer und Editoren unterschiedlich zwischengespeichert wird.

Ein kurzer Test zeigt, welche Angaben relevant sind. Ändern Sie einen Wert, etwa den Browser, und versuchen Sie es erneut. Verschwindet der Fehler, halten Sie das als Befund fest: „Tritt im Desktop-Browser auf, nicht in der mobilen App.“

Umgebung auf der ersten Seite halten

Setzen Sie den Umgebungsblock an den Anfang des Berichts, vor die Schritte. Ein Entwickler, der einen Tracker durchsieht, liest zuerst den Titel und die ersten Zeilen, bevor er entscheidet, ob er die Anhänge öffnet. Steht die Umgebung erst auf Seite 6 eines PDFs, testet der Entwickler möglicherweise einen anderen Browser und meldet „nicht reproduzierbar“.

Logs und Konsolenausgaben als Text anhängen

Bei einer Web-App zeigt die Browser-Konsole häufig einen Fehler im Moment des Auftretens. Kopieren Sie die Fehlerzeilen als Text und fügen Sie sie unter dem Umgebungsblock ein. Ein Screenshot der Konsole ist eine nützliche Ergänzung, der Entwickler braucht aber den Text, um die Meldung in der Codebasis zu suchen.

Behalten Sie nur die Zeilen in der Nähe des Fehlers. Ein Konsolen-Dump mit 400 Zeilen und einer relevanten Fehlermeldung zwingt den Leser zur Suche. Notieren Sie die Uhrzeit des Fehlers, damit er dem Versuchsprotokoll zugeordnet werden kann.

Bei einer Mac-App entsprechen dem ein Absturzbericht oder ein Fehlerdialog. Kopieren Sie den Dialogtext genau, einschließlich eines Fehlercodes, und erfassen Sie den Dialog während des Ablaufs mit dem manuellen Tastenkürzel.

Erwartetes und tatsächliches Ergebnis angeben

Zwei kurze Sätze rahmen den gesamten Bericht ein:

• Erwartet: „Nach Auswahl von Save erscheint der neue Name in der Liste.“
• Tatsächlich: „Nach Auswahl von Save zeigt die Liste weiterhin den alten Namen. Nach dem Neuladen der Seite erscheint der neue Name.“

Beschreiben Sie, was Sie beobachten, nicht, was Ihrer Meinung nach die Ursache ist. „Die Liste aktualisiert sich nicht“ ist eine Beobachtung. „Der Cache ist kaputt“ ist eine Vermutung.

Beobachtungen statt Diagnosen schreiben

Diagnosen im Fehlerbericht führen den Entwickler in die falsche Richtung. Ist die eigentliche Ursache ein fehlendes Event und kein Cache, kostet „Der Cache ist kaputt“ Zeit. Eine Beobachtung ist etwas, das jeder auf dem Bildschirm prüfen kann.

Nennen Sie eine Umgehungslösung als Tatsache, nicht als Einstufung des Schweregrads. Das Team, das den Bericht sichtet, legt den Schweregrad fest.

Von einem bekannten Ausgangspunkt aus reproduzieren

Ein Bericht, der mit „Öffnen Sie die App“ beginnt, obwohl Sie bereits tief in einer Sitzung waren, verdeckt das eigentliche Setup. Beginnen Sie bei einem Zustand, den jeder erreichen kann: einer frischen Anmeldung, einem neuen Projekt oder einer bestimmten URL.

Reproduzieren Sie den Fehler mindestens zweimal, bevor Sie aufnehmen. Tritt er nur manchmal auf, notieren Sie die Häufigkeit, etwa „3 von 5 Versuchen“.

Ausgangszustand herstellen

Beim Umbenennungsfehler ist der Ausgangszustand ein abgemeldetes Browserfenster auf der Anmeldeseite. Die Abmeldung beendet die vorherige Sitzung, sodass der Entwickler am gleichen Punkt startet wie der Melder.

Jeden Versuch protokollieren

Sporadische Fehler brauchen ein kurzes Versuchsprotokoll. Notieren Sie die Uhrzeit jedes Versuchs und ob er fehlgeschlagen ist, damit ein Entwickler die Versuche mit Server-Logs abgleichen kann. Fünf Versuche reichen in der Regel für eine Häufigkeitsangabe.

Den Ablauf auf das Minimum reduzieren

Der erste Ablauf, der einen Fehler zeigt, ist selten der kürzeste. Entfernen Sie vor der Aufnahme jeweils eine Aktion und prüfen Sie, ob der Fehler weiterhin auftritt. Im Beispiel erwies sich das Öffnen der Projektdetails vor dem Umbenennen als unnötig. Dadurch sank der Ablauf von 9 auf 7 Aktionen.

Ein kürzerer Ablauf hilft auf zwei Arten. Der Entwickler braucht für jede Reproduktion weniger Zeit, und weniger Aktionen bedeuten weniger Stellen, an denen der Leser abbiegen kann. Hören Sie mit dem Reduzieren auf, sobald das Entfernen einer weiteren Aktion den Fehler verschwinden lässt.

Tritt der Fehler während des aufgezeichneten Ablaufs nicht auf, behalten Sie die Aufnahme trotzdem. Wiederholen Sie die letzten Aktionen und drücken Sie den manuellen Tastenkürzel, sobald der Fehler auftritt. Eine Aufnahme eines erfolgreichen Durchlaufs ist weiterhin nützlich, wenn sie den genauen Ablauf zeigt.

Einen Screenshot pro erforderlicher Aktion aufnehmen

1. Action Capture öffnen

   Drücken Sie Command+3 und wählen Sie Start Action Capture. Wählen Sie Specific Window für eine App oder Active Window, wenn die Schritte über mehrere Apps verlaufen.

2. Schritte ausführen

   Jeder akzeptierte Klick speichert das Fenster unmittelbar vor dem Klick, sodass jede Seite das Bedienelement zeigt, bevor Sie es betätigen.

3. Fehler erfassen

   Wenn das falsche Ergebnis erscheint, drücken Sie Shift+Command+2 oder wählen Sie Capture now in der schwebenden Symbolleiste. Der Fehlerbildschirm erscheint häufig ohne Klick.

4. Aufnahme beenden

   Wählen Sie Finish capture. Das Dokument öffnet sich im Editor mit einer Seite pro Schritt.

Ist Parse clicked elements aktiviert, beginnen die Seitentitel mit Click "[[element-name]]". Aktivieren Sie unter Visual Annotations Show cursor on click captures und Mark clicked area, damit jede Seite zeigt, wohin Sie geklickt haben. Liegt der Fehler in Temposhot selbst, aktivieren Sie Include toolbar in captures, damit die schwebende Symbolleiste in den Schritten erscheint.

Den Ablauf einmal konfigurieren

Einstellungen unter Configure Action Capture werden auf dem Mac gespeichert und bei späteren Läufen wiederverwendet. Ein für Fehlerberichte angelegtes Setup bleibt für den nächsten Bericht erhalten.

Wählen Sie Specific Window für einen Fehler in einem Browserfenster. Ein Klick in einem anderen Fenster wird dann ignoriert, sofern Capture outside clicks nicht aktiviert ist. Wählen Sie Active Window, wenn sich die Reproduktion zwischen Apps bewegt, etwa von einem Link in einer E-Mail in den Browser.

Den Ablauf in das Schrittlimit einpassen

Der kostenlose Tarif erlaubt höchstens 5 Schritte pro Action-Capture-Lauf. Der Umbenennungsfehler benötigt 7 erforderliche Aktionen plus den Fehlerbildschirm, daher pausiert ein kostenloser Lauf nach dem fünften Schritt. Die bis dahin gespeicherten Schritte bleiben im Lauf erhalten.

Dafür gibt es zwei Wege. Teilen Sie die Reproduktion an einer natürlichen Stelle, etwa nach der Anmeldung, in zwei Läufe auf und fügen Sie den zweiten Lauf demselben Dokument hinzu. Oder aktivieren Sie Temposhot Pro, das das Limit aufhebt, sodass ein Lauf alle Schritte abdeckt.

Während des Ablaufs die Tastatur verwenden

Bleiben die Hände während einer Reproduktion auf der Tastatur, entstehen keine zusätzlichen Klicks, die zu unerwünschten Seiten werden. Die folgenden Tastenkürzel decken den Ablauf und die anschließende Bearbeitung ab.

Temposhot ignoriert Klicks, die zu dicht aufeinander folgen. Ein Doppelklick auf einen Listeneintrag erzeugt einen Schritt, nicht zwei.

Wenn der Ablauf Klicks verpasst

Ein Ablauf, der weniger Schritte speichert als erwartet, hat eine kurze Liste möglicher Ursachen. Prüfen Sie sie in dieser Reihenfolge, bevor Sie erneut aufnehmen.

• Die schwebende Symbolleiste zeigt Paused. Wählen Sie Resume capture. Klicks während der Pause werden nicht gespeichert.
• Das Ziel ist Specific Window, und der Klick landete in einem anderen Fenster. Klicken Sie innerhalb des Ziels oder aktivieren Sie Capture outside clicks.
• Mouse click capture steht auf einem Modus, der eine gehaltene Taste voraussetzt oder ignoriert. Stellen Sie für Fehlerberichte wieder Capture every mouse click ein.
• Die Berechtigung für Bedienungshilfen fehlt. Unter Permissions Required müssen sowohl Screen Recording als auch Accessibility den Status Granted zeigen.

Lauten alle geparsten Titel Click here, stellt die Zielapp für ihre Bedienelemente nur wenige Bedienungshilfen-Daten bereit. Die Schritte werden trotzdem gespeichert. Nur die Titel müssen manuell umgeschrieben werden.

Text hinzufügen, der Zustandsänderungen erklärt

Screenshots zeigen Bildschirme. Sie zeigen nicht immer, was sich zwischen ihnen geändert hat. Verwenden Sie dafür die Page description: „Der Zähler sollte hier 4 zeigen. Er zeigt 3.“

Zeichnen Sie auf der Fehlerseite ein Rectangle (R) um den falschen Wert und fügen Sie eine Text-Beschriftung (T) mit dem erwarteten Wert hinzu. Löschen Sie Seiten aus ungewollten Klicks, damit die Abfolge nur erforderliche Aktionen enthält. Bearbeiten Sie die Titel zu einfachen Schritten, etwa „Save auswählen“. Der Editor-Leitfaden listet jedes Werkzeug und jeden Shortcut auf.

Das Beispiel bereinigen

Die aufgezeichnete Umbenennung erzeugte 9 Seiten. Eine Seite stammte von einem Klick auf einen leeren Bereich der Liste, eine weitere von einem Klick auf die Adressleiste des Browsers. Beide Seiten wurden gelöscht. Die Fehlerseite aus dem manuellen Tastenkürzel blieb erhalten. Übrig blieben 7 Aktionsseiten plus die Fehlerseite.

Geparste Titel sind ein Ausgangspunkt. Aus Click "Rename" wird „Rename im Projektmenü auswählen“, was dem Leser zusätzlich zeigt, wo das Bedienelement liegt. Seiten, bei denen der Parser keinen Namen fand, zeigen Click here und müssen immer umgeschrieben werden.

Beschreibungsmuster für Zustandsänderungen

Drei kurze Muster decken die meisten Seitenbeschreibungen in einem Fehlerbericht ab. „Vor diesem Schritt zeigt die Liste 12 Projekte“ hält einen Ausgangswert fest. „2 Sekunden nach dem Tippen warten“ hält eine Zeitangabe fest, die der Screenshot nicht zeigen kann. „Hier sollte die Liste Q3 Budget zeigen“ hält den erwarteten Zustand auf der Seite fest, auf der der Fehler auftritt.

Halten Sie jede Beschreibung auf ein oder zwei Sätze. Lange Beschreibungen schieben den Screenshot im PDF nach unten. Bei Beschreibungen mit Before image liest der Leser zuerst den Text.

Die Fehlerseite markieren

Die Fehlerseite enthält die meisten Informationen und erhält deshalb die meisten Anmerkungen. Ein Rechteck um den alten Namen und eine Textbeschriftung mit dem erwarteten Namen reichen meist aus. Mehr als 3 Anmerkungen auf einer Seite erschweren es, den falschen Wert zu finden.

Verwenden Sie Framing mit einer Stufe wie Close (Stufe 4) auf der Fehlerseite, wenn die Liste bei einem großen Fenster klein dargestellt wird. Das Quellbild bleibt unverändert. Show full image stellt es wieder her, falls der Entwickler den vollen Kontext braucht.

Private Informationen schützen

Fehlerberichte werden in Tracker, Chat-Threads und Tickets bei Dienstleistern kopiert. Behandeln Sie jeden Screenshot als innerhalb Ihrer Organisation öffentlich.

• Reproduzieren Sie den Fehler nach Möglichkeit mit einem Testkonto und Beispieldaten.
• Schneiden Sie Seitenleisten, Browser-Tabs und Benachrichtigungen mit Framing (F) und Custom ab.
• Machen Sie Namen, E-Mail-Adressen, Tokens und IDs mit Blur (B, Pro) unkenntlich.
• Entfernen Sie Session-Tokens und API-Schlüssel aus jeder URL oder jedem Log-Text, den Sie einfügen.

Jede Seite in Exportgröße prüfen

Unschärfe, die einen Wert auf der Arbeitsfläche bei 50 Prozent Zoom verdeckt, kann in voller Größe lesbar bleiben. Stellen Sie Blur strength im Object Inspector auf einen Wert, bei dem der Text nicht lesbar ist. Der Standard ist 12 auf einer Skala von 2 bis 80. Blättern Sie danach durch die Exportvorschau, bevor Sie den Bericht senden.

URLs in der Adressleiste des Browsers sind eine häufige Datenquelle für Lecks. Ein Freigabelink oder ein Reset-Token in der Leiste ist auf jeder Seite einer browserbasierten Reproduktion sichtbar. Schneiden Sie die Adressleiste deshalb mit Framing ab oder machen Sie sie auf jeder Seite unkenntlich.

Diesen Aufbau für den Fehlerbericht verwenden

1. Titel: was fehlschlägt und wo. „Umbenanntes Element wird in der Listenansicht nicht aktualisiert.“
2. Umgebung: die Tabellenwerte von oben.
3. Schritte zur Reproduktion: nummeriert, ab einem bekannten Zustand.
4. Erwartetes Ergebnis und Tatsächliches Ergebnis.
5. Häufigkeit: immer, oder wie oft.
6. Belege: der exportierte Screenshot-Leitfaden sowie Logs oder Konsolenfehler als Text.
7. Umgehungslösung: falls vorhanden.

Exportieren Sie aus dem Dokument mit Export PDF für einen einzelnen Anhang oder mit More export formats für PNG-Seiten, die Tracker inline anzeigen. Die Bilddateinamen folgen den Seitentiteln. Der Export-Leitfaden listet alle Formate auf.

Den Export für den Tracker wählen

Tracker unterscheiden sich darin, wie sie Anhänge anzeigen. Inline-PNG-Seiten funktionieren, wenn der Tracker Bilder im Issue-Text vorschaut, weil der Entwickler die Schritte liest, ohne eine Datei zu öffnen. Ein einzelnes PDF funktioniert, wenn der Tracker nur Anhänge auflistet oder der Bericht an einen externen Dienstleister geht.

Das Format ZIP package enthält gerenderte PNG-Seiten und eine Datei document.json in einem Archiv. Es eignet sich für ein Dienstleisterticket, das eine einzige Datei akzeptiert und sowohl die Bilder als auch den Seitentext benötigt.

Ein ausgefülltes Beispiel

So liest sich der Umbenennungsbericht im Tracker. Der Titel lautet „Umbenanntes Projekt behält seinen alten Namen in der Projektliste bis zum Neuladen.“ Der Umgebungsblock nennt die Build-Nummer, die macOS-Version, die Browser-Version, die Rolle Editor und die Versuchszeiten von 14:02 bis 14:20.

Die Schritte sind 7 nummerierte Zeilen, von „Als qa-editor anmelden“ bis „Den Umbenennen-Dialog schließen“. Erwartetes und tatsächliches Ergebnis sind die beiden Sätze von oben, die Häufigkeit lautet „3 von 5 Versuchen“. Der Beleg ist ein PDF mit 8 Seiten, die Umgehungslösung lautet „Seite neu laden“.

Das PDF verwendet die Standard-Exporteinstellungen: A4, Landscape, Titelseite aktiviert, Schrittnummern aktiviert, Seitenzahlen aktiviert und Beschreibungen vor dem Bild. Anpassungen dieser Einstellungen erfordern Temposhot Pro. Die Standardwerte passen bereits zu einem Fehlerbericht.

Die Schritte zusätzlich als Text schreiben

Fügen Sie die nummerierten Schritte auch als Text in den Issue-Text ein, selbst wenn das PDF sie enthält. Textschritte lassen sich durchsuchen, in Kommentaren zitieren und in einen Testfall kopieren. Die Screenshots dienen dann als Beleg für jeden Schritt und sind nicht die einzige Aufzeichnung.

Den Bericht vor dem Versand testen

Lesen Sie den Bericht von oben, als hätten Sie den Fehler nie gesehen. Noch besser: Bitten Sie einen Kollegen, ihn auf seinem Mac nachzuvollziehen. Reproduziert er den Fehler, ohne eine Rückfrage zu stellen, ist der Bericht fertig.

Typische Lücken bei einem Probelauf

Ein Probelauf durch einen Kollegen deckt meist eine von drei Lücken auf. Der Ausgangszustand fehlt, etwa ein Projekt, das bereits existieren muss. Ein Schritt geschieht ohne Klick, etwa durch einen Tastenkürzel, und hat keine Seite. Oder der Fehler hängt vom Timing ab, etwa wenn Save weniger als 2 Sekunden nach dem Tippen ausgewählt wird.

Ergänzen Sie den fehlenden Zustand im ersten Schritt, fügen Sie eine Seite für die Tastaturaktion mit dem manuellen Tastenkürzel hinzu und nennen Sie das Timing in der Seitenbeschreibung. Wiederholen Sie danach den Probelauf.

Das Quell-Dokument aufbewahren

Das Dokument bleibt nach dem Export bearbeitbar. Wünscht der Entwickler einen weiteren Bildschirm, öffnen Sie das Dokument, fügen Sie die Seite mit Capture new images… hinzu und exportieren Sie erneut. Bereits exportierte Dateien aktualisieren sich nicht von selbst.

Häufig gestellte Fragen

Sollte ein Fehlerbericht Video oder Screenshots enthalten?

Screenshots eignen sich für die meisten Fehler und lassen sich leicht durchsehen und annotieren. Video hilft bei Timing-Problemen und Animationen. Siehe Schritt-für-Schritt-Screenshot-Anleitung im Vergleich zur Bildschirmaufnahme.

Wie viele Screenshots braucht ein Fehlerbericht?

Einen pro erforderlicher Aktion plus den Fehlerbildschirm. Entfernen Sie Seiten, die das Ergebnis nicht verändern.

Wo liegen die Screenshots nach dem Versand des Berichts?

Das Dokument bleibt auf Ihrem Mac. Temposhot bietet keinen gehosteten Link. Hängen Sie die exportierten Dateien deshalb an das Issue im Tracker oder an das Ticket an.

Was gilt, wenn der Fehler im kostenlosen Tarif mehr als 5 Schritte braucht?

Der Lauf pausiert am Schrittlimit und behält die bis dahin gespeicherten Schritte. Teilen Sie die Reproduktion in zwei Läufe auf und fügen Sie beide demselben Dokument hinzu, oder verwenden Sie Temposhot Pro, um über das Limit hinaus aufzunehmen.

Lässt sich ein Fehler erfassen, der ohne Klick auftritt?

Ja. Drücken Sie den manuellen Aufnahme-Tastenkürzel, standardmäßig Shift+Command+2, sobald der falsche Zustand erscheint. Der Schritt wird ohne Klick gespeichert und erhält die Klickmarkierung, falls eine konfiguriert ist.

Verwandeln Sie Ihre Klicks in eine klare Schritt-für-Schritt-Anleitung

Action Capture zeichnet die Reproduktionsschritte während der Ausführung auf, mit Klickmarkierungen und Entwurfstiteln. Laden Sie Temposhot herunter und hängen Sie Ihren nächsten Fehlerbericht als geordnete Anleitung an.