vercel-labs/dogfood

Was macht dogfood?

Systematisch eine Webanwendung erkunden, Probleme finden und einen Bericht mit vollständigen Reproduktionsnachweisen für jeden Fund erstellen.

Einrichtung

Nur die Ziel-URL ist erforderlich. Alles andere hat sinnvolle Standardwerte – verwenden Sie diese, sofern der Benutzer nicht explizit eine abweichende Angabe macht.

Parameter	Standardwert	Beispiel für Abweichung
Ziel-URL	(erforderlich)	vercel.com, http://localhost:3000
Session-Name	Slug der Domain (z. B. vercel.com -> vercel-com)	--session my-session
Ausgabeverzeichnis	./dogfood-output/	Output directory: /tmp/qa
Umfang	Gesamte App	Focus on the billing page
Authentifizierung	Keine	Sign in to [email protected]

Wenn der Benutzer etwas wie „dogfood vercel.com“ sagt, starten Sie sofort mit den Standardwerten. Stellen Sie keine klärenden Fragen, es sei denn, die Authentifizierung wird erwähnt, aber die Anmeldeinformationen fehlen.

Verwenden Sie immer direkt agent-browser – niemals npx agent-browser. Das direkte Binary verwendet den schnellen Rust-Client. npx leitet über Node.js und ist deutlich langsamer.

Arbeitsablauf

1. Initialisieren   Session, Ausgabeverzeichnisse, Berichtsdatei einrichten
2. Authentifizieren  Bei Bedarf anmelden, Zustand speichern
3. Orientieren       Zum Startpunkt navigieren, erste Momentaufnahme erstellen
4. Erkunden          Systematisch Seiten besuchen und Funktionen testen
5. Dokumentieren     Jedes Problem sofort mit Screenshot + Aufzeichnung festhalten
6. Abschließen       Zusammenfassungszahlen aktualisieren, Session schließen

1. Initialisieren

mkdir -p {OUTPUT_DIR}/screenshots {OUTPUT_DIR}/videos

Kopieren Sie die Berichtsvorlage in das Ausgabeverzeichnis und füllen Sie die Kopfzeilenfelder aus:

cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md

Starten Sie eine benannte Session:

agent-browser --session {SESSION} open {TARGET_URL}
agent-browser --session {SESSION} wait --load domcontentloaded

2. Authentifizieren

Falls die App eine Anmeldung erfordert:

agent-browser --session {SESSION} snapshot -i
# Formularreferenzen für die Anmeldung identifizieren, Anmeldeinformationen eingeben
agent-browser --session {SESSION} fill @e1 "{EMAIL}"
agent-browser --session {SESSION} fill @e2 "{PASSWORD}"
agent-browser --session {SESSION} click @e3
# Ersetzen Sie dies durch die URL, den Text oder die JS-Bedingung der Ziel-App nach der Anmeldung:
agent-browser --session {SESSION} wait --url "{POST_LOGIN_URL_PATTERN}"
# Oder:
# agent-browser --session {SESSION} wait --text "{POST_LOGIN_TEXT}"
# agent-browser --session {SESSION} wait --fn "{POST_LOGIN_CONDITION}"

Bei OTP/E-Mail-Codes: Fragen Sie den Benutzer, warten Sie auf seine Antwort und geben Sie dann den Code ein.

Nach erfolgreicher Anmeldung speichern Sie den Zustand für eine mögliche Wiederverwendung:

agent-browser --session {SESSION} state save {OUTPUT_DIR}/auth-state.json

3. Orientieren

Erstellen Sie einen ersten annotierten Screenshot und eine Momentaufnahme, um die App-Struktur zu verstehen:

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/initial.png
agent-browser --session {SESSION} snapshot -i

Identifizieren Sie die Hauptnavigationselemente und planen Sie die zu besuchenden Bereiche.

4. Erkunden

Lesen Sie references/issue-taxonomy.md für die vollständige Liste dessen, worauf Sie achten müssen, sowie für die Erkundungs-Checkliste.

Strategie – arbeiten Sie die App systematisch durch:

• Beginnen Sie mit der Hauptnavigation. Besuchen Sie jeden übergeordneten Bereich.
• Testen Sie innerhalb jedes Bereichs interaktive Elemente: Klicken Sie auf Schaltflächen, füllen Sie Formulare aus, öffnen Sie Dropdowns/Modals.
• Überprüfen Sie Randfälle: leere Zustände, Fehlerbehandlung, Grenzwerteingaben.
• Probieren Sie realistische End-to-End-Workflows aus (Erstellen, Bearbeiten, Löschen).
• Überprüfen Sie regelmäßig die Browser-Konsole auf Fehler.

Auf jeder Seite:

agent-browser --session {SESSION} snapshot -i
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/{page-name}.png
agent-browser --session {SESSION} errors
agent-browser --session {SESSION} console

Verwenden Sie Ihr Urteilsvermögen, wie tief Sie gehen. Verbringen Sie mehr Zeit mit Kernfunktionen und weniger mit peripheren Seiten. Wenn Sie einen Fehlercluster in einem Bereich finden, untersuchen Sie ihn tiefer.

5. Probleme dokumentieren (Reproduktion zuerst)

Die Schritte 4 und 5 erfolgen zusammen – erkunden und dokumentieren in einem Durchgang. Wenn Sie ein Problem finden, stoppen Sie die Erkundung und dokumentieren Sie es sofort, bevor Sie fortfahren. Erkunden Sie nicht zuerst die gesamte App und dokumentieren Sie später.

Jedes Problem muss reproduzierbar sein. Wenn Sie etwas Falsches finden, notieren Sie es nicht nur – beweisen Sie es mit Nachweisen. Das Ziel ist, dass jemand, der den Bericht liest, genau sehen kann, was passiert ist, und es nachvollziehen kann.

Wählen Sie das richtige Nachweisniveau für das Problem:

Interaktive / verhaltensorientierte Probleme (funktional, UX, Konsolenfehler bei Aktionen)

Diese erfordern Benutzerinteraktion zur Reproduktion – verwenden Sie eine vollständige Reproduktion mit Video und schrittweisen Screenshots:

1. Starten Sie ein Reproduktionsvideo bevor Sie reproduzieren:

agent-browser --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.webm

2. Gehen Sie die Schritte in menschlichem Tempo durch. Warten Sie 1-2 Sekunden zwischen den Aktionen, damit das Video ansichtsbar ist. Machen Sie bei jedem Schritt einen Screenshot:

agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png
sleep 1
# Aktion ausführen (klicken, ausfüllen usw.)
sleep 1
agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png
sleep 1
# ...fortfahren, bis das Problem sichtbar wird

3. Erfassen Sie den fehlerhaften Zustand. Warten Sie, damit der Betrachter ihn sehen kann, und machen Sie dann einen annotierten Screenshot:

sleep 2
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}-result.png

4. Stoppen Sie das Video:

agent-browser --session {SESSION} record stop

5. Schreiben Sie nummerierte Reproduktionsschritte in den Bericht, die jeweils auf den zugehörigen Screenshot verweisen.

Statische / beim Laden sichtbare Probleme (Tippfehler, Platzhaltertext, abgeschnittener Text, Fehlausrichtungen, Konsolenfehler beim Laden)

Diese sind ohne Interaktion sichtbar – ein einzelner annotierter Screenshot ist ausreichend. Kein Video, keine mehrstufige Reproduktion:

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}.png

Schreiben Sie eine kurze Beschreibung und verweisen Sie im Bericht auf den Screenshot. Setzen Sie Repro Video auf N/A.

---

Für alle Probleme:

1. Hängen Sie den Bericht sofort an. Sammeln Sie Probleme nicht für später. Schreiben Sie jedes, sobald Sie es finden, damit nichts verloren geht, wenn die Session unterbrochen wird.

2. Erhöhen Sie den Problemzähler (ISSUE-001, ISSUE-002, ...).

6. Abschließen

Zielen Sie darauf ab, 5-10 gut dokumentierte Probleme zu finden, und schließen Sie dann ab. Die Tiefe der Nachweise ist wichtiger als die reine Anzahl – 5 Probleme mit vollständiger Reproduktion sind besser als 20 mit vagen Beschreibungen.

Nach der Erkundung:

1. Lesen Sie den Bericht erneut und aktualisieren Sie die zusammenfassenden Schweregradzahlen, sodass sie den tatsächlichen Problemen entsprechen. Jeder ### ISSUE--Block muss in den Summen berücksichtigt sein.
2. Schließen Sie die Session:

agent-browser --session {SESSION} close

3. Teilen Sie dem Benutzer mit, dass der Bericht fertig ist, und fassen Sie die Ergebnisse zusammen: Gesamtzahl der Probleme, Aufschlüsselung nach Schweregrad und die kritischsten Punkte.

Leitlinien

• Reproduktion ist alles. Jedes Problem braucht einen Nachweis – aber passen Sie den Nachweis an das Problem an. Interaktive Bugs brauchen Video und schrittweise Screenshots. Statische Bugs (Tippfehler, Platzhaltertext, visuelle Fehler, die beim Laden sichtbar sind) benötigen nur einen einzigen annotierten Screenshot.
• Überprüfen Sie die Reproduzierbarkeit, bevor Sie Nachweise sammeln. Bevor Sie Video aufzeichnen oder Screenshots machen, vergewissern Sie sich, dass das Problem mit mindestens einem Wiederholungsversuch reproduzierbar ist. Wenn es nicht konsistent reproduziert werden kann, ist es kein gültiges Problem.
• Nehmen Sie kein Video für statische Probleme auf. Ein Tippfehler oder abgeschnittener Text profitiert nicht von einem Video. Heben Sie sich Video für Probleme auf, die Benutzerinteraktion, Timing oder Zustandsänderungen beinhalten.
• Machen Sie bei interaktiven Problemen einen Screenshot von jedem Schritt. Erfassen Sie das Vorher, die Aktion und das Nachher – damit jemand die gesamte Abfolge sehen kann.
• Schreiben Sie Reproduktionsschritte, die zu Screenshots passen. Jeder nummerierte Schritt im Bericht sollte auf den entsprechenden Screenshot verweisen. Ein Leser sollte in der Lage sein, die Schritte visuell zu verfolgen, ohne einen Browser zu berühren.
• Verwenden Sie den richtigen Snapshot-Befehl.
  • snapshot -i — zum Finden von klickbaren/ausfüllbaren Elementen (Schaltflächen, Eingabefelder, Links)
  • snapshot (ohne Flag) — zum Lesen von Seiteninhalten (Text, Überschriften, Datenlisten)
• Seien Sie gründlich, aber verwenden Sie Ihr Urteilsvermögen. Sie folgen keinem Testskript – Sie erkunden wie ein echter Benutzer. Wenn sich etwas falsch anfühlt, untersuchen Sie es.
• Schreiben Sie die Ergebnisse inkrementell auf. Hängen Sie jedes Problem an den Bericht an, sobald Sie es entdecken. Wenn die Session unterbrochen wird, bleiben die Ergebnisse erhalten. Sammeln Sie niemals alle Probleme für das Ende.
• Löschen Sie niemals Ausgabedateien. Führen Sie während der Session kein rm für Screenshots, Videos oder den Bericht durch. Schließen Sie die Session nicht und starten Sie nicht neu. Arbeiten Sie vorwärts, nicht rückwärts.
• Lesen Sie niemals den Quellcode der Ziel-App. Sie testen als Benutzer, nicht als Code-Auditor. Lesen Sie kein HTML, JS oder Konfigurationsdateien der zu testenden App. Alle Ergebnisse müssen aus dem stammen, was Sie im Browser beobachten.
• Überprüfen Sie die Konsole. Viele Probleme sind in der UI unsichtbar, zeigen sich aber als JS-Fehler oder fehlgeschlagene Anfragen.
• Testen Sie wie ein Benutzer, nicht wie ein Roboter. Versuchen Sie gängige Workflows von Anfang bis Ende. Klicken Sie auf Dinge, auf die ein echter Benutzer klicken würde. Geben Sie realistische Daten ein.
• Tippen Sie wie ein Mensch. Wenn Sie während der Videoaufnahme Formularfelder ausfüllen, verwenden Sie type anstelle von fill – es tippt Zeichen für Zeichen. Verwenden Sie fill nur außerhalb der Videoaufnahme, wenn Geschwindigkeit wichtig ist.
• Tempo der Reproduktionsvideos für Menschen anpassen. Fügen Sie sleep 1 zwischen den Aktionen und sleep 2 vor dem endgültigen Ergebnis-Screenshot ein. Videos sollten bei 1-facher Geschwindigkeit ansichtsbar sein – ein Mensch, der den Bericht durchgeht, muss sehen, was passiert ist, und nicht eine verschwommene Abfolge von sofortigen Zustandsänderungen.
• Seien Sie effizient mit Befehlen. Fassen Sie mehrere agent-browser-Befehle in einem einzigen Shell-Aufruf zusammen, wenn sie unabhängig sind (z. B. agent-browser ... screenshot ... && agent-browser ... console). Verwenden Sie agent-browser --session {SESSION} scroll down 300 zum Scrollen – verwenden Sie nicht key oder evaluate zum Scrollen.

Referenzen

Referenz	Wann lesen
references/issue-taxonomy.md	Zu Beginn der Session – darauf einstellen, wonach gesucht wird, Schweregrade, Erkundungs-Checkliste

Vorlagen

Vorlage	Zweck
templates/dogfood-report-template.md	In das Ausgabeverzeichnis kopieren, um die Berichtsdatei zu erstellen