For every patch that is uploaded to the Gerrit review server, a number of tests are run automatically using GitLab CI.
For more in-depth information about how TYPO3 runs the automatic tests with GitLab CI see the series “Testing TYPO3’s Core” on the TYPO3 Blog. You can find the links in this article: Serious software testing: TYPO3 runs its 20,000th build!
You can run these tests locally with docker using a similar setup.
Running all tests takes a considerable amount of time on a standard development machine, so it is not recommended to run all tests on your local platform for every patch you wish to submit. That’s what GitLab CI is for.
You might however want to run specific tests, for example for the following use cases:
- You wrote new tests or changed functionality that might break tests. You want to run specific tests and possibly debug them.
- You want to run some quick specific tests, for example to test for cgl (coding guideline) problems or syntax errors in PHP (lint) before you upload your patch.
How to Run the Tests¶
Tests can be run using the script
script provides a number of command line options for executing various tests
in different environments (PHP version, database engine, …). The script
automatically runs docker using an image which corresponds to the environment
you provide with the command line arguments.
Run Tests with runTests.sh using docker¶
You might want to run the script with the -h option to get up-to-date information about system requirements:
All examples expect to be executed from a git cloned working directory of master (as described in Top-level objects).
Running the script or a specific command line argument combination for the first time will take some time, because all necessary prerequisites for the docker images need to be fetched. The next runs should be faster.
Run all unit tests¶
Run unit tests with xdebug (uses default port 9000)¶
Run specific unit tests with xdebug¶
Build/Scripts/runTests.sh -x <directory or file>
Build/Scripts/runTests.sh -x typo3/sysext/core/Tests/Unit/LinkHandling/
Run functional tests¶
./Build/Scripts/runTests.sh -s functional
Run functional tests with PostgreSQL¶
./Build/Scripts/runTests.sh -s functional -d postgres
Run acceptance tests¶
./Build/Scripts/runTests.sh -s acceptance
Depending on the power of your local machine you can expect about 30 minutes or more for the acceptance tests.
Be sure to exclude the
typo3temp directory from indexing in your IDE (e.g. PhpStorm)
before starting the acceptance tests.
If something does not work as expected, it might help to run the script
with the additional
-v (for verbose output) option.
Before diagnosing problems in the script, make sure to check if docker is running smoothly on your system.
A quick test is to run the docker hello-world image:
docker run hello-world
You should see something like this message:
Hello from Docker! This message shows that your installation appears to be working correctly.
Also, see docker troubleshooting pages for more in-depth information, such as Docker for Mac: Logs and troublehooting
All results will be displayed on the screen. The script should exit with standard exit codes:
- 0 means all is ok
- != 0 means error
Reports of the acceptance tests will be stored in
typo3temp/var/tests/AcceptanceReports with screenshots from the browser.
Run tests directly without docker¶
If you have problems with docker, you can run some of the lowlevel scripts and
commands directly. However it does depend on your system, whether they run
successfully. The docker /
runTests.sh method gives us the possibility to have
a controlled environment where the tests run in. That also means, the databases
that the functional tests require are already created automatically. That is not
the case, if you run the tests locally on your current system.
That being said, running the tests directly is not being officially supported, but you can try this out yourself.
You can look in the source of
Build/Scripts/runTests.sh or rather in
Build/testing-docker/local/docker-compose.yml to see which commands the
script calls and run these directly. Not everything will work, because there may
be dependencies, that are only available in the docker container.
Also, you can run some of the scripts in
Run all unit tests¶
bin/phpunit -c vendor/typo3/testing-framework/Resources/Core/Build/UnitTests.xml
Run specific unit tests¶
bin/phpunit -c vendor/typo3/testing-framework/Resources/Core/Build/UnitTests.xml <directory or file>
bin/phpunit -c vendor/typo3/testing-framework/Resources/Core/Build/UnitTests.xml typo3/sysext/core/Tests/Unit/LinkHandling/
Run all functional tests¶
bin/phpunit -c vendor/typo3/testing-framework/Resources/Core/Build/FunctionalTests.xml
Check for Coding Guidelines¶
The cgl checking commands / scripts not only check, they repair as well!
You can use the already mentioned script cglFixMyCommit:
Mac / Linux:
Remember, cglFixMyCommit only checks files in latest commit, so you must have committed already. Commit again with –amend after you checked things and repaired the file, or call cglFixMyCommit.sh -h for alternatives.
- More details about the test system, test strategies, execution and set up can be found in TYPO3 explained.
- Writing unit tests in TYPO3 explained
- external: Serious software testing: TYPO3 runs its 20,000th build! for more information on how the automatic tests are run with GitLab CI for every patchset that is uploaded for the core