Erweitern / Entwicklung und Tests

18 — Entwicklung und Tests

Für alle, die an yavi_core oder einem Theme arbeiten.

Aufbau des Repositorys

text

<distribution>/
├── config/sites/<id>/settings.yaml   ← was das Backend-Modul schreibt
├── packages/
│   ├── yavi-core/                    Framework
│   └── yavi-lucerne/                 Theme
├── vendor/
└── init-yavi.sh                      lokales DDEV-Setup

Die Pakete sind über ein path-Repository von Composer eingebunden; eine Änderung in packages/ wirkt also ohne Neuinstallation.

Die tägliche Schleife

bash

# ein Template, eine SCSS-Datei oder eine PHP-Klasse bearbeiten
ddev exec vendor/bin/typo3 cache:flush
# neu laden

Fast jedes „meine Änderung tut nichts“ ist ein fehlender Cache-Flush: SCSS wird in eine gehashte Datei kompiliert, Fluid-Templates werden kompiliert, DI wird kompiliert, und die Importmap wird nur im Development-Kontext je Dateiänderung cache-invalidiert.

Tests

bash

ddev composer test                                  # alles
ddev exec php packages/yavi-core/Tests/run.php Unit # eine Suite

Der Runner kommt ohne Abhängigkeiten aus — kein PHPUnit — und endet bei einem Fehlschlag mit einem Exit-Code ungleich null; er taugt also als Pre-Commit- oder CI-Schranke. Tests/bootstrap.php versucht einen vollständigen TYPO3-Bootstrap und fällt auf reines Autoloading zurück, wenn keine Datenbank vorhanden ist; Tests, die den Container brauchen, melden sich selbst als übersprungen, statt zu scheitern.

Was die Suiten heute abdecken:

Bereich	Schützt vor
Lizenz	Vertrauen in den Cache, Alter der Signatur, Produktgeltung
Einstellungen	Dass jedes Layout-Feld rendert, auf eine CSS-Variable abbildet, den Schreibweg übersteht und sich löscht, sobald es auf die Vorgabe gesetzt wird
Tokens	`-base`-Eingaben der Abstände, Radien als Faktor gegen Länge, die SCSS-Listen, die über alle Themes hinweg synchron bleiben
Templates	Kein positives `tabindex`, jedes `<iframe>` hat einen Titel, jedes `aria-labelledby` zeigt auf eine vorhandene id
ViewHelpers	`FormatText`, `InlineIcon`, Startwerte der Verläufe, Auswertung des Eckenradius

Auf die Signatur der Assertion achten — der Name kommt zuerst:

php

$this->assertSame('round trip: ' . $key, $expected, $actual);

Einen Test hinzufügen

Er gehört nach Tests/Unit/ oder Tests/Integration/, die Klasse heißt …Test, und jeder Test wird nach dem Fehler benannt, vor dem er schützt. Ein Fehlschlag soll der nächsten Person sagen, was kaputt ist, nicht bloß, dass etwas kaputt ist.

Build-Skripte

bash

ddev exec php packages/yavi-core/Build/sync-theme-scss.php          # die SCSS-Listen jedes Themes neu erzeugen
ddev exec php packages/yavi-core/Build/sync-theme-scss.php --check  # scheitert bei Abweichung, von den Tests genutzt

Wo was liegt

Zu ändern	Nachsehen in
Das Markup eines Inhaltselements	`yavi-core/Resources/Private/Templates/ContentElements/`
Ein gemeinsamer Baustein	`yavi-core/Resources/Private/Partials/ContentElements/`
Die Geometrie einer Komponente	`yavi-core/Resources/Public/Scss/Structure/`
Farbe und Dekoration	`yavi-core/Resources/Public/Scss/Skin/` oder das `Skin/` des Themes
Ein Backend-Feld	`yavi-core/Configuration/TCA/Overrides/`
Eine Site-Einstellung	`yavi-core/Configuration/Sets/Full/settings.definitions.yaml`
Das Backend-Modul	`yavi-core/Classes/Controller/Backend/ThemeSettingsController.php` + `Resources/Private/Templates/Backend/ThemeSettings.html`
Dessen Gestaltung	`yavi-core/Resources/Public/Vendor/Backend/Css/backend-module.css`
Beschriftungen	`yavi-core/Resources/Private/Language/`

Eine Site-Einstellung hinzufügen

In settings.definitions.yaml deklarieren, mit Kategorie, Beschriftung und Beschreibung. Die Beschreibung ist nicht optional — ein Test erzwingt, dass jedes Feld sich selbst erklärt und mehr sagt als seine Beschriftung.
In ThemeCssVariablesRenderer::CSS_VARIABLE_MAP auf eine CSS Custom Property abbilden — ein weiterer Test scheitert, wenn ein Feld keine Variable erreicht.
Das Token im SCSS mit einem Rückfall lesen: var(--my-token, <die Vorgabe des Themes>).
Cache leeren, Tests laufen lassen.

Sprachdateien

Datei	Enthält
`Backend.xlf` / `de.Backend.xlf`	TCA-Beschriftungen, Backend-Modul
`locallang.xlf` / `de.locallang.xlf`	Frontend-Beschriftungen
`locallang_mod.xlf`, `locallang_be.xlf` (+ `de.`-Varianten)	Beschriftungen von Modul und Backend-Layouts
`locallang_db.xlf` / `de.locallang_db.xlf`	Beschriftungen der Formular-Finisher

Zwei Regeln, die man leicht falsch macht:

Eine Übersetzungsdatei heißt de.<datei>.xlf. <datei>.de.xlf wird stillschweigend ignoriert.
Eine Übersetzungsdatei braucht target-language="de" und ein <target> je Einheit. Eine Datei mit nur <source> ist keine Übersetzung.

Konventionen in dieser Codebasis

Kommentare erklären das Warum, nicht das Was. Sie sind im Quelltext auf Deutsch geschrieben und lesen sich als Prosa, nicht als Etiketten.
Keine Kommentare in Fluid-Templates oder SCSS, außer es ist wirklich etwas Überraschendes festzuhalten.
Ein Token, eine Bedeutung. Vor dem Hinzufügen einer Variablen prüfen, ob eine vorhandene diese Entscheidung bereits besitzt.
Löschen ist besser als abkündigen. Tote Vorschau-Templates, ungenutzte Paletten und verwaiste Partials werden entfernt, nicht „für alle Fälle“ behalten.