Running Unit tests

Install PHPUnit and the TYPO3 testing framework

In order to run unit tests within an extension or project you can require PHPUnit and the testing framework via Composer as a development dependency:

composer require --dev \
  "typo3/testing-framework":"^8.0.9" \
  "phpunit/phpunit":"^10.5"

Which versions to use depends on the PHP and TYPO3 versions to be supported.

The following matrix can help you to choose the correct versions.

Testing framework <= 6.x is no longer maintained.

Provide configuration files for unit tests

The TYPO3 testing framework comes with a predefined unit test configuration and a bootstrapping file. You should copy these files into your project so you can adjust them as needed:

Copy the files vendor/typo3/testing-framework/Resources/Core/Build/UnitTests.xml and vendor/typo3/testing-framework/Resources/Core/Build/UnitTestsBootstrap.php

Open file UnitTests.xml and adjust the paths to the path (or multiple paths) where the unit tests are stored. By convention many extensions store them in the directory Tests/Unit and subdirectories thereof:

<testsuites>
    <testsuite name="Unit tests">
-        <directory>../../../../../../typo3/sysext/*/Tests/Unit/</directory>
+        <directory>../../Tests/Unit/</directory>
    </testsuite>
</testsuites>

If you are testing in a project you will probably have a directory from where local extensions like site packages and client-specific extensions are installed , so you can also include them:

<testsuites>
    <testsuite name="Unit tests">
-        <directory>../../../../../../typo3/sysext/*/Tests/Unit/</directory>
+        <directory>../../Tests/Unit/</directory>
+        <directory>../../packages/*/Tests/Unit/</directory>
    </testsuite>
</testsuites>

Run the unit tests on your system or with DDEV

If you have the required PHP version installed on your host system, you can run the unit tests directly:

php vendor/bin/phpunit -c Build/phpunit/UnitTests.xml

Or you can run them on ddev:

ddev exec php vendor/bin/phpunit -c Build/phpunit/UnitTests.xml

If you are using DDEV, you can also create a custom command so you can run these tests again and again.

If you want to only run a specific test case (test class) or test (method in a test class) you can use the filter option:

php vendor/bin/phpunit -c Build/phpunit/UnitTests.xml --filter "MyTest"

You can of course define a Composer script <https://getcomposer.org/doc/articles/scripts.md> as well, so that this command can be executed easily on the host, within a DDEV container and also in GitHub Actions or Gitlab CI.

Run the unit tests with runTests.sh

If you are using a runTests.sh like the one used by the t3docs/blog-example you can run the tests with:

Build/Script/runTests.sh -s unit

It is also possible to choose the PHP version to run the tests with:

Build/Script/runTests.sh -s unit -p 8.2

You can start by copying the runTests.sh of blog_example and adjust it to your needs.

There are different solutions to store and execute these commands. For details see Test Runners: Organize and execute tests.

runTests.sh is a script that originates from the TYPO3 Core repository and is used as a test and tool execution runner. It is based on running individual Docker containers with several bash commands, and also allows Xdebug integration, different database environments and much more. Once you copy such a file to your repository you need to take care of maintaining it when possible bugfixes or changes occur upstream.