Tests und Befehlsreferenz

Tests und Befehlsübersicht

Goat bündelt die häufigsten Entwicklungsoperationen in .goat-Skripten, die sich im Verzeichnis herd/ befinden.

Anstatt nacheinander Docker-, Generator-, Migrations-, Test- oder Frontend-Werkzeugbefehle manuell auszuführen, kannst du den gesamten Prozess als einen wiederholbaren Workflow beschreiben und mit einem einzigen Befehl starten.

Die Skripte werden mithilfe der Goat-Isolierungsschicht ausgeführt. Dadurch können die vom Projekt benötigten Abhängigkeiten und Werkzeuge in Containern laufen, ohne dass sie direkt auf dem Host-System installiert werden müssen.

Dieser Ansatz bietet mehrere Vorteile:

• Er vereinheitlicht die Art, das Projekt auf verschiedenen Betriebssystemen zu starten.
• Er reduziert die Abhängigkeit von der lokalen Konfiguration des Entwicklerrechners.
• Er ermöglicht die Kontrolle der Versionen von Go, Node.js, Browsern und anderen Werkzeugen.
• Er beschränkt den Umfang der von Skripten ausgeführten Änderungen auf die vom Projekt bereitgestellten Ressourcen.
• Er vereinfacht die Ausführung derselben Prozesse lokal und in CI.

Tägliche Arbeit

Die am häufigsten verwendeten Befehle:

goat run:script

Der Befehl run:script führt die angegebene Datei .goat aus:

bash child/dev.sh

Die Skriptdatei kann einen gesamten Prozess beschreiben, der aus mehreren Schritten besteht, zum Beispiel:

• Starten von Containern,
• Vorbereiten von Abhängigkeiten,
• Generieren von Code,
• Ausführen von Migrationen,
• Ausführen von Tests,
• Erstellen des Frontends,
• Starten der Anwendung.

Dadurch bleibt die Logik der Entwicklungsumgebung Teil des Projekts, anstatt zwischen Dokumentation, lokalen Skripten und den Rechnerkonfigurationen einzelner Entwickler verteilt zu sein.

goat re

Der Befehl:

goat re

startet den Prozess zur Generierung der Anwendung auf Grundlage des aktuellen Modells und der Projektkonfiguration erneut.

Du wirst ihn am häufigsten nach Änderungen an folgenden Komponenten verwenden:

• Domänenmodell,
• Entitätsdefinitionen,
• Beziehungen,
• Generatorkonfiguration,
• Vorlagen für generierten Code.

Der Generator sollte Änderungen kontrolliert vornehmen, damit die generierte Anwendung weiterhin manuell weiterentwickelt werden kann.

Nach der Regenerierung empfiehlt es sich, die Änderungen in Git vor dem Commit zu prüfen.

Tests

Die vollständige Testsuite startest du mit dem Befehl:

goat run:script --path=herd/test.goat

herd/test.goat definiert den vollständigen Prozess zur Überprüfung der Anwendung.

Bevor die eigentlichen Tests ausgeführt werden, erstellt das Skript den generierten Teil des Projekts erneut. Dadurch wird Code getestet, der dem aktuellen Anwendungsmodell entspricht, und nicht ein zufälliger lokaler Zustand generierter Dateien.

Anschließend werden unter anderem ausgeführt:

• Backend-Tests in Go,
• Build der Frontend-Anwendung,
• Frontend-Tests,
• E2E-Tests mit Playwright.

Wo möglich, können unabhängige Phasen parallel ausgeführt werden, wodurch sich die Gesamtdauer des Prozesses verkürzt.

Wiederholbare Testumgebung

Tests use containers to reduce differences between developers' environments and CI.

This applies in particular to components such as:

• Go,
• Node.js,
• npm,
• browsers used by Playwright,
• PostgreSQL,
• additional tools required when building the application.

As a result, test outcomes should not depend on which version of Node.js or Go a developer currently has installed on their computer.

This is particularly important for E2E tests, which are often sensitive to browser versions and system dependencies.

Isolation during testing and building

Running tools in containers also serves a security function.

Operations such as:

npm install
npm test
npm run build

do not need to be performed directly on the host.

Code executed by dependencies runs inside a controlled environment and receives access only to resources shared by Goat and the project configuration.

This helps reduce, among other things, the risk associated with dependency installation scripts such as preinstall, install, or postinstall.

At the same time, isolation does not replace dependency review. It is still worth:

• reviewing library updates,
• using a lockfile,
• controlling dependency sources,
• checking changes before committing them.

Checking changes after generation

After running:

goat re

or the full test process, it is worth checking the changes:

git status
git diff

This makes it possible to see exactly which parts of the application were modified by the generator.

This is particularly useful when changing the domain model. Instead of treating regeneration as an “overwrite the entire application” operation, Goat allows you to work with generated changes similarly to manually introduced changes.

You can commit only those files to the repository that should actually be included in a given commit.

Debugging scripts

If one of the workflows does not complete successfully, first run the corresponding script directly.

For example, migration issues can be reproduced using:

goat run:script --path=herd/db/migrate.goat

and test issues:

goat run:script --path=herd/test.goat

Splitting processes into smaller .goat scripts makes it easier to determine whether the problem concerns:

• generation,
• the database,
• the backend,
• the frontend,
• E2E tests,
• environment configuration.

Help for application commands

The generated application also includes its own CLI.

After building it, you can display documentation for individual commands using the --help flag.

For example:

myapp crud:doc:persist --help
myapp db:migrate --help
myapp serve --help

It is worth using --help instead of relying solely on examples from the documentation, because it shows the parameters available in the currently used version of the application.

Example: crud:doc:persist

The command:

myapp crud:doc:persist --help

displays options for creating or updating a document.

Available parameters include, among others:

• --lang,
• --slug,
• --title,
• --description,
• --body-markdown,
• --body-markdown-file.

For larger content, passing a file is more convenient:

myapp crud:doc:persist \
  --lang=pl \
  --slug=testowanie \
  --title="Testowanie" \
  --body-markdown-file=./doc/testowanie.md

This allows documentation content to be stored in the repository and synchronized with the application using the CLI.

Releases

The process for preparing a new release is described in the file:

RELEASING.md

It contains a procedure that includes, among other things:

• Auswahl und Festlegung der neuen Version,
• Vorbereitung der erforderlichen Schlüssel,
• Erstellung der Artefakte,
• Ausführung der Tests,
• Überprüfung der Pakete,
• Veröffentlichung des Releases.

Lassen Sie vor der Veröffentlichung nicht den vollständigen Testsatz aus.

Vor Beginn des Release-Prozesses sollte außerdem Folgendes überprüft werden:

git status

und sichergestellt werden, dass das Repository keine versehentlichen lokalen Änderungen enthält.

Ein Release sollte erst vorbereitet werden, wenn:

• der Generator für das aktuelle Modell korrekt funktioniert,
• die Backend-Tests erfolgreich durchlaufen,
• das Frontend korrekt gebaut wird,
• die E2E-Tests erfolgreich durchlaufen,
• die Konfiguration der Zielumgebung überprüft wurde,
• sich alle für das Release vorgesehenen Änderungen im Repository befinden.

Typischer Workflow

In der täglichen Arbeit genügt meist der folgende Zyklus:

# ändere das Anwendungsmodell
vim herd/_model.goat

# generiere die daraus resultierenden Änderungen
goat re

# überprüfe den generierten Code
git diff

# führe die Tests aus
goat run:script --path=herd/test.goat

# überprüfe den endgültigen Umfang der Änderungen
git status

Diese Arbeitsweise ermöglicht eine klare Aufgabentrennung:

Das Modell beschreibt die Absicht, der Generator erstellt wiederholbaren Code, die Tests überprüfen das Ergebnis, und Git bleibt die maßgebliche Informationsquelle darüber, was sich im Projekt tatsächlich geändert hat.