Code testing

Introduction

Egroupware uses PHPUnit in order to test server side codes and Web Test Runner for webComponent testing. There is usually a test folder in each module or section which holds test codes. Test codes are written in the matching language as the code under test (PHP or TypeScript). See the test framework docs for more information about testing with that framework.

To run the full PHPUnit test suite:

php vendor/bin/phpunit --configuration doc/phpunit.xml

To run the full WTR test suite:

npm run jstest

How to run a test

Dependencies

PHPUnit is a composer dev-dependency, so composer install already put it at vendor/bin/phpunit - there is nothing separate to install. For the web component tests you need Playwright's browsers:

npx playwright install --with-deps chromium firefox

Where to run it

The tests run against a real, installed EGroupware rather than a throwaway fixture, so whatever you run PHPUnit from has to reach that installation: its database, and - for the tests that speak HTTP, such as the REST and CalDAV suites - a web server serving it. doc/phpunit.xml points the latter at EGW_URL.

On a native installation just run it. On a Docker based one it depends on how db_host is set in header.inc.php: if it is a container-internal name such as db, run the tests in the app container, which already has everything configured -

docker exec -w /var/www/egroupware egroupware vendor/bin/phpunit -c doc/phpunit.xml

(the container name differs per installation - check docker ps). If it is an address the host can reach, either works.

Run a test in CLI

Always pass the configuration, which supplies the bootstrap and the test user settings:

vendor/bin/phpunit -c doc/phpunit.xml

Add a path to run just one file or directory:

vendor/bin/phpunit -c doc/phpunit.xml api/tests/DateTimeTest.php

PHPUnit 12.5.23 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.5.8
Configuration: /var/www/egroupware/doc/phpunit.xml

...                                                                 3 / 3 (100%)

Time: 00:00.009, Memory: 18.00 MB

OK (3 tests, 13 assertions)

For the web component tests:

npm run jstest                    # everything
npm run jstest -- --group api     # one app's group

Per-installation settings

doc/phpunit.xml is committed, so anything specific to your installation belongs in a git-ignored doc/phpunit.local.php returning an array. Above all the sysop password, which is generated fresh at install time and therefore cannot be committed:

<?php
return [
	'EGW_ADMIN_PASSWORD' => 'the sysop password from your install',
];

The real environment always wins over this file, so CI, which passes such values in explicitly, is unaffected. Tests that need admin rights switch to that account rather than granting them to the ordinary test user.

Continuous integration

Every push and pull request to EGroupware runs the whole suite on GitHub Actions, and apps kept in their own repository can run the same workflow themselves - it builds a full EGroupware instance, installs the app into it and runs that app's tests. This works for third-party apps too.

See doc/app-ci.md for how to call it from your own repository.