Einrichtung von Cypress in meiner TYPO3-Testumgebung

Zum Testen und Weiterentwickeln von Extensions, aber auch zum Ausprobieren von Core-Funktionen, habe ich mir spezielle TYPO3-Installationen erstellt. Sie enthalten beispielsweise Seitenbäume zum Form Framework, in denen ich Beispiel-Formulare einrichten und absenden kann.

Das Frontend-Testing-Framework Cypress kreuzt aktuell ständig meinen Weg, zuletzt als Vortrag auf dem Web Camp Venlo. Daher habe ich jetzt die Chance ergriffen, das Tool in meinen Testumgebungen erstmalig einzurichten.

Dieser Artikel beschreibt meine Testumgebungen, die erforderlichen Tests für meine Extension "content_slug" sowie meine Konfiguration von Cypress.

Disclaimer zu Beginn: Cypress nutze ich hier für End-to-End-Tests (E2E), die eine vollständige Testumgebung zwingend voraussetzen. TYPO3-Extensions werden üblicherweise auf anderem Wege automatisiert getestet.

Meine TYPO3-Extension "content_slug" ermöglicht die Generierung menschen­lesbarer Sprungmarken (URL-Fragmente) für Inhaltselemente.

Ob und wie die Fragmente angewendet werden, ist aber von einigen Faktoren abhängig. Daher habe ich einen Testseitenbaum mit verschiedenen Konstellationen erstellt.

Bislang habe ich hier eine manuelle Funktions- und Sichtprüfung vorgenommen. Mit etwas CSS habe ich den Inhaltsbereich begrenzt (zur besseren Prüfung der Sprungmarken-Funktion) und lasse mir die href-Attribute von Links anzeigen.

Als statische TypoScript-Dateien werden EXT:fluid_styled_content sowie EXT:content_slug eingebunden.

Im Setup-Feld ist auf einfachem Wege etwas CSS ergänzt. Darunter folgt das zweite PAGE-Objekt, für das ich dann die Plugin-Konfiguration etwas anpasse. Der Präfix nutzt weiterhin die UID des Inhaltselements, beginnt nun aber mit dem String "custom". Falls ein Wert im Subheader-Feld gepflegt ist, wird dieser als Suffix angehängt. Der so zusammengefügte Wert wird am Ende noch einmal durch den Sanitizer geschickt. Dabei werden z.B. nicht unterstützte Leer- und Sonderzeichen im Subheader ersetzt.

page = PAGE
page.10 < styles.content.get
page.cssInline {
    10 = TEXT
    10.value = body { max-width: 400px; padding-bottom: 80rem; font-family: 'Source Sans Pro'; background: ghostwhite; margin: 3rem; }
  	20 = TEXT
    20.value = .frame { margin-bottom: 6rem; background: white; padding: 1rem; }
    30 = TEXT
    30.value = a[href]::after { content: " (" attr(href) ") "; color: grey; display: flex; font-size: .8em; }
}


// Page object with custom fragments
pageWithCustomFragment < page
pageWithCustomFragment {
  typeNum = 1
}

[getTSFE().type == 1]
    // Test custom fragment prefix:
    plugin.tx_contentslug.urlFragmentPrefix = TEXT
    plugin.tx_contentslug.urlFragmentPrefix {
        field = uid
        stdWrap.noTrimWrap = |custom|-|
        if.isTrue = {$plugin.tx_contentslug.settings.renderPrefix}
    }
    
    // Test optional suffix with value from second field:
    plugin.tx_contentslug.urlFragmentSuffix = TEXT
    plugin.tx_contentslug.urlFragmentSuffix {
        field = subheader
        if.isTrue.field = subheader
        stdWrap.noTrimWrap = |-||
    }
    
    // Sanitize fragment again because of subheader value:
    lib.contentElement.variables.fragmentIdentifier {
        stdWrap.postUserFunc = Sebkln\ContentSlug\Evaluation\FragmentEvaluation->sanitizeFragment
    }
[end]

Da ich bereits einen Route Enhancer für Seiten konfiguriert hatte, musste der typeNum "1" dort ergänzt werden:

routeEnhancers:
  PageTypeSuffix:
    type: PageType
    default: /
    index: ''
    map:
      /: 0
      withCustomFragment.html: 1

Aufgerufen wird das zweite PAGE-Objekt also nicht mit dem GET-Parameter type=1, sondern mit dem gewählten Suffix withCustomFragment.html

Da dieser Beitrag kein Cypress-Tutorial sein soll, verzichte ich auf die generelle Vorstellung des Tools. Die offizielle Dokumentation mit "Getting started"-Guides und Referenz ist da sehr hilfreich.

Aber: Ich war überrascht, wie schnell Cypress einsatzbereit war! Installiert habe ich das Tool mit Yarn, danach konnte ich Cypress starten und in der GUI "E2E Testing" auswählen. Dadurch wurden mir alle wichtigen Konfigurationsdateien automatisch im Projektverzeichnis angelegt. Beim ersten Start von Google Chrome (per Cypress) habe mir auch die Beispiel-Tests ("Specs") generieren lassen. So einfach kann's gehen!

In der package.json habe ich zwei Skripte ergänzt, um Cypress-Tests auszuführen:

"scripts": {
    "cy:run:content-slug": "cypress run --spec 'cypress/e2e/production/content-slug/**/*'",
    "cy:open:content-slug": "cypress open --e2e --browser chrome"
}

Der erste Befehl yarn cy:run:content-slug startet alle Tests zur Extension im Headless Browser und liefert die Testergebnisse in der Kommandozeile zurück.
Der zweite Befehl öffnet direkt Google Chrome, ohne den Umweg über das Cypress-Launchpad. Hier kann ich einzelne Tests starten und debuggen – auch über die Browserkonsole, die von Cypress mit Informationen gefüttert wird.

Für die Prüfung der Links habe ich Fixtures verwendet. Das sind Dateien im JSON-Format, mit denen sich – grob gesagt – die Testdaten von den Testskripten trennen lassen. Die Testdaten (z.B. Logindaten eines Testnutzers) könnten dann statisch angelegt oder auch dynamisch erzeugt werden.

In meinem Fall brauchte ich die als Referenz genutzten Links so nur einmal definieren, um sie dann in mehreren Testskripten verwenden zu können.

Beispiel: Inhalt der Fixture-Datei mit Referenz-Links für die Header-Typen in TYPO3. Enthalten sind vier Arrays für die vorgenannten Testszenarien.

{
	"defaultEN": [
		"/content_slug/all-header-types/#c48-heading-with-default-layout",
		"/content_slug/all-header-types/#c52-heading-with-h1-layout",
		"/content_slug/all-header-types/#c54-heading-with-h2-layout",
		"/content_slug/all-header-types/#c56-heading-with-h3-layout",
		"/content_slug/all-header-types/#c58-heading-with-h4-layout",
		"/content_slug/all-header-types/#c60-heading-with-h5-layout",
		"/content_slug/all-header-types/#c62"
	],
	"defaultDE": [
		"/content_slug/de/alle-ueberschrift-typen/#c48-ueberschrift-mit-standard-layout",
		"/content_slug/de/alle-ueberschrift-typen/#c52-ueberschrift-mit-h1-layout",
		"/content_slug/de/alle-ueberschrift-typen/#c54-ueberschrift-mit-h2-layout",
		"/content_slug/de/alle-ueberschrift-typen/#c56-ueberschrift-mit-h3-layout",
		"/content_slug/de/alle-ueberschrift-typen/#c58-ueberschrift-mit-h4-layout",
		"/content_slug/de/alle-ueberschrift-typen/#c60-ueberschrift-mit-h5-layout",
		"/content_slug/de/alle-ueberschrift-typen/#c62"
	],
	"customEN": [
		"/content_slug/all-header-types/#custom48-heading-with-default-layout",
		"/content_slug/all-header-types/#custom52-heading-with-h1-layout",
		"/content_slug/all-header-types/#custom54-heading-with-h2-layout",
		"/content_slug/all-header-types/#custom56-heading-with-h3-layout",
		"/content_slug/all-header-types/#custom58-heading-with-h4-layout",
		"/content_slug/all-header-types/#custom60-heading-with-h5-layout",
		"/content_slug/all-header-types/#c62"
	],
	"customDE": [
		"/content_slug/de/alle-ueberschrift-typen/#custom48-ueberschrift-mit-standard-layout",
		"/content_slug/de/alle-ueberschrift-typen/#custom52-ueberschrift-mit-h1-layout",
		"/content_slug/de/alle-ueberschrift-typen/#custom54-ueberschrift-mit-h2-layout",
		"/content_slug/de/alle-ueberschrift-typen/#custom56-ueberschrift-mit-h3-layout",
		"/content_slug/de/alle-ueberschrift-typen/#custom58-ueberschrift-mit-h4-layout",
		"/content_slug/de/alle-ueberschrift-typen/#custom60-ueberschrift-mit-h5-layout",
		"/content_slug/de/alle-ueberschrift-typen/#c62"
	]
}

Diese vier Arrays werden dann jeweils passend zur Seiten-Variante geladen:

/// <reference types="cypress" />

describe('Links in content element of type Section Index', () => {
  const pages = [
    '/content_slug/',
    '/content_slug/de/',
    '/content_slug/withCustomFragment.html',
    '/content_slug/de/withCustomFragment.html'
  ];
  const jsonDataKeys = ['defaultEN', 'defaultDE', 'customEN', 'customDE'];

  jsonDataKeys.forEach((key, index) => {
    it(`should match on page ${pages[index]} using ${key} data`, () => {
      cy.fixture('content-slug/href-header-types.json').then((jsonData) => {
        const hrefValues = jsonData[key];
        cy.visit(pages[index]);
        cy.get('#c44 ul ul a').each(($element, index) => {
          cy.wrap($element).should('have.attr', 'href', hrefValues[index])
        })
      });
    });
  });
});