Lesson 12.1: The test suites
The kernel has hundreds of test files, and they are the best examples of how its classes are meant to be used. Learners who change code also need to know which tests to run before they share the change. This lesson shows where the tests are, how they are grouped, and how to run them without a database.
At a glance
| Course | Developers |
| Module | Module 12: Tests and quality |
| Duration | 40 minutes (15 presenting, 25 exercise) |
| Level | Intermediate |
| Audience | Developers |
| Prerequisites | Lesson 1.2: a Git installation with development dependencies |
Learning objectives
After this lesson, learners can:
- find the suites in
phpunit.xmland the tests intests/tests/; - run one suite with
vendor/bin/phpunit --testsuite <name>and one test file by its path; - explain that the default run excludes the
databasegroup and needs no database; - name the suites that need a live installation or servers;
- read PHPUnit's summary line.
Trainer's notes
How to present it
Source: Testing and continuous integration.
- Where (3 minutes).
phpunit.xmlin the root defines the suites;tests/tests/holds the tests, organized like the code (kernel/,lib/,extension/,design/,bin/).tests/bootstrap.phploads the autoloaders and the test toolkit; it does not boot the kernel. - Suites (4 minutes). Examples:
security,kernel-classes,lib(nothing needed);design(files only);kernel-search(database tests roll back);cjw_newsletter,ezoe(a live installation, skipped without one);mongodb-live(running servers). - Without a database (3 minutes).
vendor/bin/phpunitruns every suite with thedatabasegroup excluded.tests/runtests.php --dsn <dsn> --db-per-testruns against a throwaway database, as CI's database job does. - CI (3 minutes). GitHub Actions runs the suites on PHP 8.1 to 8.5 for every push and pull request to
main; a red run blocks. - Only the tests of a change (2 minutes).
tests/test-map.jsonmaps source files to the tests that cover them; the full run stays the check before a release.
Common questions
How long does the whole run take? Many minutes on a busy machine; that is why the tests of a change are run first. Run the full suite before a large pull request.
Do tests change my installation? DB-less tests do not; database tests need a throwaway database. Never point
runtests.php at a database you care about.
Where are tests of extensions? Some extensions have suites in phpunit.xml; an extension of your own keeps its
tests in its own repository (lesson 12.2).
Pitfalls
- Running on a shared server at full speed. Use
nice -n 15and one suite at a time. - Missing development dependencies.
vendor/bin/phpunitexists only after acomposer installwith development packages. - Reading only the dots. Read the summary line and every
F,E,WorSabove it.
Hands-on exercise
On the development installation, from its root folder.
- List the suites:
grep -o '<testsuite name="[^"]*"' phpunit.xml. - Count the test files:
find tests/tests -name "*Test.php" | wc -l. - Run the security suite:
nice -n 15 vendor/bin/phpunit --testsuite security --no-coverage. - Run one test file by its path, for example a test of the template engine: find one with
ls tests/tests/lib/eztemplate/ | headand run it withvendor/bin/phpunit <path>. - Find which tests cover the class
eZINIthrough the map:grep -n "ezini" tests/test-map.json | head. - Read one test of
eZINIand write down one method call you did not know. - Read the exclusions of the default run:
grep -n -A16 "<groups>" phpunit.xml.
Expected result
- Step 1 lists more than twenty suites.
- Step 3 ends with
OK (<n> tests, <m> assertions). - Step 4 ends with
OKor explains a skipped test withS. - Step 7 shows the excluded groups, among them
database. - The trainer asks each learner which suite they would run after changing a datatype.
Quiz
- Which file defines the test suites?
- Which group does the default run exclude?
A.
securityB.databaseC.designD.lib - How do you run only the
securitysuite? - What do live-installation suites do when no installed site is present?
- What is
tests/test-map.jsonfor?
Answers
phpunit.xmlin the installation root.- B.
database(withmail-live,mongodb-liveandnetwork-live). vendor/bin/phpunit --testsuite security.- They skip each class with a reason.
- It maps source files to the tests that cover them, so the tests of a change can be run first.
Further reading
- Testing and continuous integration.
- Quality checks: hooks, manifest, code style, PHPStan, the tests of a change.
- Continuous integration.
Related pages
- Module 12: Tests and quality
- Developers: course overview
- Trainers: start here
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.