tea/README.md

Tea example

This TYPO3 extension is an example of best practices in continuous integration and automated code checks, also writing unit and functional tests for Extbase/Fluid-based extensions for TYPO3 CMS using PHPUnit.

It also is an example for best practices for extbase/fluid.

For information on the different ways to execute the tests, please have a look at the handout to my workshops on test-driven development (TDD).

This manual is rendered for reading on docs.typo3.org.

Feature list

All of those checks are available in Github Actions and in Gitlab CI.

PHP Lint check by php -l

composer ci:php:lint

PHP code style fixer checks by php-cs-fixer

composer ci:php:cs-fixer

PHP code sniffing by phpcs

composer ci:php:sniff

PHP copy'n'paste check by phpcpd

composer ci:php:copypaste

PHP type checking by PHPStan

composer ci:php:stan

JSON Lint check by jsonlint

composer ci:json:lint

YAML Lint check by yaml-lint

composer ci:yaml:lint

TypoScript Lint by typoscript-lint

composer ci:ts:lint

Composer Normalize by composer-normalize

composer ci:composer:normalize

Running unit tests

composer ci:tests:unit

Running functional tests

composer ci:tests:functional

Running all tests

composer ci:tests

Running the tests in PhpStorm

File > Settings > Languages & Frameworks > PHP > Test Frameworks

• (*) Use Composer autoloader
• Path to script: select .Build/vendor/autoload.php in your project folder

In the Run configurations, edit the PHPUnit configuration and use these settings so this configuration can serve as a template:

• Directory: use the Tests/Unit directory in your project
• (*) Use alternative configuration file
• use .Build/vendor/nimut/testing-framework/res/Configuration/UnitTests.xml in your project folder
• add the following environment variables:
  • typo3DatabaseUsername
  • typo3DatabasePassword
  • typo3DatabaseHost
  • typo3DatabaseName

Unit tests configuration

In the Run configurations, copy the PHPUnit configuration and use these settings:

• Directory: use the Tests/Unit directory in your project

Functional tests configuration

In the Run configurations, copy the PHPUnit configuration and use these settings:

• Directory: use the Tests/Functional directory in your project
• (x) Use alternative configuration file
• use .Build/vendor/nimut/testing-framework/res/Configuration/FunctionalTests.xml

Running the acceptance tests

On the command line

1. make sure you have Chrome installed on your machine
2. composer update codeception/codeception (just in case)
3. download the latest version of ChromeDriver
4. unzip it
5. chromedriver --url-base=wd/hub
6. .Build/vendor/bin/codecept run (in another terminal)

In PhpStorm

1. make sure the "Codeception Framework" plugin is activated
2. right-click on Tests/Acceptance/StarterCest.php
3. Run 'Acceptance (Codeception)'

Developing locally

In order to work on the extension locally, you can use a local environment (local PHP, server) or use a widely adopted tool in TYPO3 Community, ddev, which we recommend.

Running Composer commands in the DDEV container

If you use ddev, then you can use the provided command in root of your repository. You don't need to manually startup containers, you can run commands straight away, and project will automatically boot up. Please remember to keep ddev up to date.

Example:

ddev composer ci:ts:lint

Running tests locally via DDEV

Unit tests

To run unit tests, type:

composer ci:tests:unit

Functional tests

To run functional tests, type:

composer ci:tests:functional

Running lints in CI

GitHub

For GitHub, we prepared two ways of running lints:

1. relies on executing composer scripts
2. using exported, prepared GitHub Actions in your workflow.

Composer scripts

You can run your lints using composer scripts. An example workflow is defined in ci-composer-scripts.yml.

Ready to use GitHub Actions

You can use prepared GitHub Actions. All of ready to use GitHub Actions are in TYPO3 Continuous Integration organisation. An example workflow is defined in ci.yml

GitLab

For GitLab, please use the pipeline that is defined in .gitlab-ci.yml.

Security

Libraries and extensions do not need the security check as they should not have any restrictions concerning the other libraries they are installed alongside with (unless those would create breakage), and they also do not have a composer.lock which usually is the source for security checks.

Instead, the projects (i.e., for TYPO3 installations) need to have the security checks.

Documentation rendering

In order to render documentation, first of all, clone repository

git clone https://github.com/TYPO3-Documentation/tea.git

then go to extension root

cd tea

and follow the TYPO3 documentation quickstart guide.

More Documentation

• Handout to my workshops on test-driven development (TDD)
• Handout for best practices with extbase and fluid

Other example projects

• Selenium demo for using Selenium with PHPUnit
• Anagram finder is the finished result of a code kata for TDD
• Coffee example is my starting point for demonstrating TDD with TYPO3 CMS
• TDD Seed for starting PHPUnit projects with Composer (without TYPO3 CMS)