Testdaten und Fixtures

Nach dem Erstellen eines Projekts mit:

goat init ./my-project \
  --name my-project \
  --git-repo git@github.com:your-user/my-project.git \
  --terminal-prefix MYAPP \
  --default-language en \
  --supported-languages en,pl \
  --template goatcms

erhältst du nicht nur die Anwendungsstruktur, sondern auch Beispieldaten und Dokumente, die auf die aktuelle Goat-Version abgestimmt sind.

Dadurch kannst du das Projekt sofort starten und eine funktionierende Anwendung mit Beispielinhalten sehen, ohne die Ausgangsdaten manuell vorbereiten zu müssen.

Fixtures erfüllen daher zwei Aufgaben:

  • Sie liefern die für lokale Entwicklung und Tests benötigten Daten.
  • Sie erstellen Beispieldokumentation, die mit der Version des Generators übereinstimmt, die du aktuell verwendest.

Dies ist besonders bei der Aktualisierung eines Projekts hilfreich. Dokumentation und Beispiele können gemeinsam mit dem Code versioniert werden, wodurch sich leichter überprüfen lässt, wie eine bestimmte Version der Anwendung funktioniert.

Haupt-Fixture des Projekts

Die Logik zum Laden von Daten befindet sich in:

herd/fixture.goat

Das Skript kann unter anderem Folgendes erstellen oder aktualisieren:

  • Dokumente,
  • Beispieldaten,
  • von der Anwendung benötigte Datensätze,
  • Demo-Inhalte,
  • während der lokalen Entwicklung benötigte Daten.

herd/fixture.goat wird beim Starten der Entwicklungsumgebung ausgeführt durch:

herd/dev.goat

Dadurch kann die lokale Anwendung nach dem Start des Projekts automatisch einen für den Betrieb benötigten Satz Daten erhalten.

Das Fixture kann auch manuell ausgeführt werden.

Dokumentation als Anwendungsdaten

Die Beispieldokumentation wird in Markdown-Dateien gespeichert.

Die Standardstruktur sieht wie folgt aus:

herd/fixtures/doc/<ver>/<lang>/<slug>.md

wobei:

  • <ver> die Dokumentationsversion festlegt,
  • <lang> die Sprache festlegt,
  • <slug> eine stabile Dokumentenkennung ist.

Beispiel:

herd/fixtures/doc/v1/pl/architektura.md

Dieser Ansatz ermöglicht es, die Dokumentation als gewöhnliche Textdateien zusammen mit dem Projekt zu speichern.

Du kannst sie:

  • in Git versionieren,
  • in Code Reviews prüfen,
  • in einem beliebigen Editor bearbeiten,
  • mit KI modifizieren,
  • übersetzen,
  • erneut in die Anwendung laden.

Die Dokumentation bleibt somit Teil des Quellcodes des Projekts und ist nicht Inhalt, der ausschließlich in der Datenbank existiert.

Laden von Markdown-Dokumenten

Markdown-Dateien werden geladen durch:

herd/fixture.goat

unter Verwendung des Befehls:

crud:doc:persist

Beispiel:

crud:doc:persist \
  --lang=pl \
  --slug="moj-dokument" \
  --title="Mój dokument" \
  --description="Krótki opis dla wyszukiwarek i udostępnień." \
  --body-markdown-file="herd/fixtures/doc/v1/pl/moj-dokument.md"

Der Dokumentinhalt wird direkt aus der Datei abgerufen, die durch Folgendes angegeben wird:

--body-markdown-file

Metadaten wie Titel, Sprache, Slug oder Beschreibung werden separat übergeben.

Dadurch lassen sich der eigentliche Markdown-Inhalt und Informationen trennen, die von der Anwendung, für SEO oder von Suchmechanismen verwendet werden.

persist statt Duplikate zu erstellen

Der Befehl:

crud:doc:persist

ist für die wiederholte Ausführung vorgesehen.

Statt jedes Mal einen neuen Datensatz zu erstellen, sucht er ein vorhandenes Dokument anhand seiner Kennung und aktualisiert es, falls es bereits existiert.

Dadurch können Fixtures idempotent sein — die mehrfache Ausführung desselben Skripts sollte zum selben erwarteten Datenzustand führen, anstatt weitere Kopien derselben Datensätze zu erstellen.

Bei Entitäten, die von content erben, basiert die Dokumentenidentifikation auf dem Paar:

lang + slug

Beispielsweise werden:

pl + architektura
en + architecture

als zwei unterschiedliche Dokumente behandelt.

Achte daher bei der Aktualisierung bestehender Inhalte auf konsistente Werte für lang und slug.

Eine Änderung des Slugs kann dazu führen, dass ein neuer Datensatz erstellt wird, anstatt den bestehenden zu aktualisieren.

Stabile Slugs

Ein Slug sollte als technischer Bezeichner eines Dokuments behandelt werden, nicht nur als vereinfachte Version seines Titels.

Ein guter Slug sollte:

  • kurz sein,
  • stabil sein,
  • in Kleinbuchstaben geschrieben sein,
  • keine Sonderzeichen enthalten,
  • durch Bindestriche getrennt sein.

Beispiele:

architektura
baza-danych
testowanie
model-i-generowanie

Ändere den Slug nicht nur deshalb, weil sich der Titel des Dokuments geändert hat.

Beispielsweise kann ein Dokument:

slug: architektura

später den Titel haben:

Architektura aplikacji Goat

ohne dass sein Bezeichner geändert werden muss.

Dies hilft, stabile URLs beizubehalten und Datensätze über persist korrekt zu aktualisieren.

Versionierung der Dokumentation

Das Verzeichnis:

herd/fixtures/doc/<ver>/

ermöglicht die Speicherung von Dokumentation, die einer bestimmten Version des Projekts oder Generators zugeordnet ist.

Dies kann nützlich sein, wenn aufeinanderfolgende Goat-Versionen Folgendes ändern:

  • die Projektstruktur,
  • die Modellsyntax,
  • verfügbare Befehle,
  • das Verhalten des Generators,
  • die Art der Anwendungskonfiguration.

Dadurch kann der Benutzer mit einer Dokumentation arbeiten, die der Codeversion entspricht, die ihm tatsächlich vorliegt.

Das ist sicherer, als sich ausschließlich auf externe Dokumentation zu verlassen, die möglicherweise eine neuere oder ältere Version des Tools beschreibt.

Manuelles Ausführen von Fixtures

Nach dem Build der Anwendung kann das Fixture manuell über die CLI der generierten Anwendung geladen werden:

myapp run:script --path=herd/fixture.goat

Dies ist nützlich, wenn:

  • du die Dokumentation geändert hast,
  • du neue Beispieldaten hinzugefügt hast,
  • du den lokalen Zustand der Anwendung aktualisieren möchtest,
  • du die Funktionsweise des Fixtures testest,
  • du nicht die gesamte Entwicklungsumgebung erneut starten möchtest.

Da die Daten über Operationen vom Typ persist geladen werden, sollte ein erneutes Ausführen des Fixtures in erster Linie bestehende Datensätze aktualisieren, statt Duplikate zu erstellen.

Fixtures in der täglichen Arbeit

Ein typischer Workflow bei der Bearbeitung von Dokumentation kann wie folgt aussehen:

Änderung einer Markdown-Datei
        ↓
Ausführung von herd/fixture.goat
        ↓
Aktualisierung des Dokuments in der Datenbank
        ↓
Überprüfung des Ergebnisses in der Anwendung

Beispielsweise:

vim herd/fixtures/doc/v1/pl/architektura.md

myapp run:script --path=herd/fixture.goat

Du musst Inhalte nicht manuell in die Datenbank kopieren oder Datensätze über das Administrationspanel bearbeiten.

Fixtures und Tests

Fixtures sollten einen vorhersehbaren Ausgangszustand erzeugen.

Gute Testdaten sind:

  • deterministisch,
  • mehrfach ladbar,
  • unabhängig von Produktionsdaten,
  • unempfindlich gegenüber der Reihenfolge manueller Vorgänge,
  • ausreichend vollständig, um grundlegende Anwendungsszenarien auszuführen.

Vermeide nach Möglichkeit die Generierung zufälliger Daten, wenn konkrete Werte später von Tests verwendet werden.

Stabile Daten erleichtern:

  • E2E-Tests,
  • Debugging,
  • die Reproduktion von Fehlern,
  • die Vorbereitung der Umgebung für neue Entwickler,
  • den Vergleich des Verhaltens aufeinanderfolgender Anwendungsversionen.

Beispieldaten und Produktionsdaten

Fixtures sind in erster Linie für Entwicklungs-, Test- und Demonstrationsumgebungen vorgesehen.

Füge ihnen nicht Folgendes hinzu:

  • echte Benutzerdaten,
  • Passwörter,
  • Tokens,
  • API-Schlüssel,
  • Secrets,
  • Kopien von Produktionsdaten, die vertrauliche Informationen enthalten.

Daten, die in herd/fixtures/ gespeichert werden, sollten als Teil des Repositorys behandelt werden. Es sollte davon ausgegangen werden, dass sie für jeden zugänglich sein können, der Zugriff auf den Projektcode hat.

Redaktionelle Hinweise für die Dokumentation

Jede Markdown-Datei sollte Inhalte in einer einzigen Sprache enthalten.

Bestimme die Dokumentsprache anhand der Verzeichnisstruktur sowie des Parameters:

--lang

Verwende stabile Slugs und mache sie nicht von geringfügigen Titeländerungen abhängig.

Speichere Titel und Beschreibung im Fixture:

--title="Mój dokument"
--description="Krótki opis dokumentu."

Dadurch werden die Metadaten zusammen mit der Datendefinition gespeichert und können unter anderem verwendet werden für:

  • SEO,
  • die Suche,
  • Dokumentlisten,
  • das Teilen von Inhalten,
  • zukünftige Sprachversionen.

Speichere den eigentlichen Inhalt hingegen in einer separaten Markdown-Datei.

Dokumentation ab dem ersten Start verfügbar

Einer der Vorteile der von goat init bereitgestellten Fixtures ist die Möglichkeit, das Projekt zusammen mit der Dokumentation zu starten, die seiner Version entspricht.

Der Workflow sieht vereinfacht so aus:

goat init
    ↓
Projektgenerierung
    ↓
Starten der Umgebung
    ↓
Laden der Fixtures
    ↓
fertige Anwendung mit Dokumentation und Beispieldaten

Dadurch beginnt ein neues Projekt nicht mit einer leeren Anwendung.

Ab dem ersten Start kannst du funktionierende Beispiele, die Datenstruktur sowie die für die verwendete Goat-Version vorbereitete Dokumentation sehen.

Dadurch sind Fixtures nicht nur ein Mechanismus zum Laden von Testdaten, sondern auch ein Bestandteil eines selbstdokumentierenden Projekts.