Setting up Cypress in my TYPO3 testing environment

To test and develop extensions, but also to evaluate core functionality, I have created dedicated TYPO3 installations. They contain, for example, page trees for the Form Framework, in which I can set up and submit demo forms.

The frontend testing framework Cypress is currently crossing my path quite frequently, most recently as a session at Web Camp Venlo. As a result, I've now taken the chance to set up this tool in my test environments for the first time.

This article outlines my testing environments, the required tests for my extension "content_slug" as well as my initial configuration of Cypress.

Disclaimer at the beginning: I am using Cypress here for end-to-end (E2E) testing, which requires a fully functional test environment. Typically, TYPO3 extensions are tested in a different automated way.

My TYPO3 extension "content_slug" allows the creation of human-readable URL fragments for content elements.

However, if and how the fragments are applied depends on several factors. Therefore, I created a test page tree with different constellations.

So far I have done manual function and visual checks. With some CSS I limited the content area (to better check the jump link functionality) and and display the href attributes of links.

EXT:fluid_styled_content and EXT:content_slug are included as static TypoScript files.

In the setup field some CSS is added in a simple way. Below that follows the second PAGE object, for which I then modify the plugin configuration. The prefix still contains the UID of the content element, but now starts with the string "custom". Also, if a value is maintained in the subheader field, it will be appended as a suffix. The resulting value is then passed through the sanitizer again. In the process, e.g. unsupported spaces and special characters in the subheader are replaced.

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]

Since I had already configured a route enhancer for pages, the typeNum "1" had to be added there:

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

Consequently, the second PAGE object is not called with the GET parameter type=1, but with the chosen suffix withCustomFragment.html

Since this article is not intended to be a Cypress tutorial, it will not cover a general introduction to the tool. The official documentation with "Getting started" guides and reference is very helpful there.

But I was surprised how quickly Cypress was ready for use! I installed the tool with Yarn, after that I could start Cypress and select "E2E Testing" in the GUI. This automatically created all the important configuration files for me in the project directory. At the first start of Google Chrome (via Cypress) I also had the sample tests ("Specs") generated. It can be that easy!

I added two scripts in the package.json to run Cypress tests:

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

The first command yarn cy:run:content-slug starts all tests related to the extension in the headless browser and prints the test results on the command line.
The second command opens Google Chrome directly, without the detour via the Cypress launchpad. From here I can start and debug individual tests – also via the browser console, which is supplied with information by Cypress.

To test the links, I used fixtures. These are files in JSON format that can be used – roughly speaking – to separate the test data from the test scripts. The test data (e.g. login data of a test user) could then be created manually or generated dynamically.

The advantage in my case was that I only needed to define the reference links once to use them in multiple test scripts.

Example: Content of the fixture file with reference links for the header types in TYPO3. Included are four arrays for the afore-mentioned testing scenarios.

{
	"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:

These four arrays are then loaded to match the four page's variants:

/// <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])
        })
      });
    });
  });
});