Update einer TYPO3-Extension mit Rector und Behat

Musst Du Deine TYPO3-Extension regelmäßig pflegen und updaten - vielleicht sogar über mehrere TYPO3-Versionen hinweg? So machen wir das.

Die Vorgeschichte: Wir haben 2013 die TYPO3-Extension Addressmgmt entwickelt, Damals hatten wir noch keine Tests für diese Extension geschrieben und bis vor kurzem auch keine hinzugefügt. Da aber diese Extension relativ viel Funktionalität und Views bietet, war es bei jedem Update sehr zeitaufwändig die Extension manuell zu testen.

Mit dem Update von auf TYPO3 10 auf 11 und der Veröffentlichung der Extension, haben wir beschlossen diesen Aufwand nicht noch einmal zu betreiben und lieber Behat-Tests zu schreiben.

Die Idee war, die Extension mit möglichst wenig Aufwand möglichst intensiv zu testen. Außerdem sollten auch Nicht-TYPO3-Entwickler (aka Projektmanger*innen) beim Schreiben der Tests mitmachen können. Daher haben wir erstmal darauf verzichtet Unit und Functional Tests zu schreiben, sondern sind gleich mit Behavior Tests eingestiegen im folgenden Behat Tests genannt.

Behat ist ein in PHP geschriebenes Test-Framework für Behaviour-Driven-Development. Wer mehr dazu wissen will, lese gerne meinen Blogbeitrag dazu. Er gilt hier als Vorwissen ;-)

Um testen zu können, haben wir zunächst eine TYPO3-Demoseite (auf TYPO3-Bootstrap-Basis) aufgebaut, auf der die gesamte Funktionalität und alle Views unserer Extension im Frontend mit Beipieldaten einmal zu sehen sind. Unsere TYPO3-Extension Addressmgmt hat relativ viele Views, teilweise auch mit Login und Frontend-Eingaben. Ich werde mich hier aber nur auf eine einfache View beschränken um das Prinzip zu erklären.

Unter anderem hat die Extension eine solche Liste von Personen (siehe unten). Diese Liste ist per JavaScript nach den Anfangsbuchstaben des Nachnamens filterbar.

Zuerst die Tests schreiben ...

Addressmtmt A-Z-Liste
Addressmtmt A-Z-Liste

Wir wollen jetzt testen, dass zunächst die Liste funktioniert, bei der zwei Personen ausgegeben werden. Dann soll nach dem filtern nach »B« nur noch „Lusise Beinhard“ zu sehen sein.

Ein solcher Test kann mit Behat so aussehen:

Feature: Addressmgmt
  List of all people with A-Z browser

  Background:
    Given I am on "beispiele/a-z-liste-mitarbeiter-1"
    # check if the a-z form is displayed
Then I should see 1 ".letter-list" elements

  Scenario: Show all people on a-z list
  # two persons are shown
Then I should see 2 ".list-item" elements

  @javascript
Scenario: Show people with first letter b
    Then I should see 1 "#link-for-group-b" elements
    # click on the link with the letter b
Then I follow "link-for-group-b"
    And I should see "Lusie Beinhart"
    And I should not see "Peter Lustig"

Der Background beschreibt den „ist“ Zustand für jedes Szenario. Dieser wird für jedes Szenario immer wieder neu ausgeführt.

Es wird hier die Seite /beispiele/a-z-liste-mitarbeiter-1 aufgerufen. Dort soll ein Element .letter-list existieren. Das ist in diesem Fall der Filter. Dies muss für jedes Szenario gelten.

Das erste Szenario erwartet, dass es auf der Seite zwei .list-item Elemente gibt. Das ist in diesem Fall die CSS-Klasse der Person. Hier wird schon klar das hier noch viel mehr und auch besser getestet werden könnte, aber es soll ja erst mal einfach sein.

Das nächste Szenario prüft ob es den Link #link-for-group-b gibt und klickt diesen an, bzw. folgt ihm. Danach soll der Text Luise Beinhard zu sehen sein, Peter Lustig aber nicht mehr – sprich: alle Personen deren Nachnahme nicht mit B anfängt werden ausgefiltert.

Mit diesen recht einfachen Test kann bereits recht viel Funktionalität der Extension getestet werden. Am Ende können alle Tests (Features) mit einem Befehl getestet werden. Bei uns lautet der z.B. docker-compose run tests behat

Haben wir alle Tests geschrieben und laufen sie sauber durch, können wir uns sicher sein, dass die Extension unter TYPO3 10.4 zuverlässig läuft. Kommen wir nun also zum Update auf TYPO3 11.

.. dann das Extension-Update

Zunächst muss die gesamte Demoseite auf TYPO3 11 hochgezogen werden, wir benutzen dazu ein eigenes Docker Environment um auch schnell zwischen Versionen (via git-Branches) wechseln zu können, aber andere Umgebungen mit ddev würden natürlich auch funktionieren.

Ist das System auf TYPO3 11 umgestellt, können wir das Extension-Update angehen. Da wir ja jetzt bereits das Testen automatisiert haben, wäre es da nicht auch schön das Update auch zu automatisieren?

Ja das geht (in Grenzen). Dazu benutzen wir ein Tool namens rector.

TYPO3-Exension-Updates mit Rector

Das Tool Rector kann nämlich z.B. PHP Code lesen und syntaktisch „verstehen“ und dann nach gewissen Regeln umbauen. Das heißt es lässt sich mit einem Befehl ein Satz von Regeln auf unsere Extension anwenden. Die Verwendung von TYPO3+Rector (dank dieses Blogposts) hat uns die Arbeit extrem erleichtert: PHP-Klassen, veraltetes Typoscript, Conditions etc. werden größtenteils völlig automatisch auf den aktuellen TYPO3-Code-Standard umgeschrieben.

Dazu benötigen wir zunächst rector und das Regelset für TYPO3. Dies holen wir mit folgendem Composer-Befehl:

composer require --dev ssch/typo3-rector
composer require --dev rector/rector

Jetzt wird noch die Regelsetdefinition ins Arbeitsverzeichniss kopiert:

cp ./vendor/ssch/typo3-rector/templates/rector.php.dist rector.php

In in der rector.php ist definiert welche Regeln berücksichtigt werden sollen.
Zum Beispiel zu welcher TYPO3 Version geupdated werden soll (hier 11).

$rectorConfig->sets([
    Typo3LevelSetList::UP_TO_TYPO3_11,
]);

Jetzt können wir die Regeln auf eine Extension anwenden bzw. mit dry-run anzeigen lassen was gemacht werden würde.

./vendor/bin/rector process packages/my_custom_extension –dry-run

Ist der Code upgedatet, können die Behat Tests ausgeführt werden.

Sind alle Tests in Ordnung ist das Update abgeschlossen.

Weiterführende Links:


Kommentare

Keine Kommentare


Kommentar schreiben

* Diese Felder sind erforderlich