Hi guys,<\/p>\n
Many TYPO3 extensions I open have no tests at all. When I ask why, the answer is nearly always the same: “the testing framework looks heavy”. I understand. The first time I saw The truth is that one functional test for a repository needs four small files. This post shows them for an extension that runs on TYPO3 13.4 and 14.3, and how to run the suite inside DDEV.<\/p>\n Imagine an events extension with a custom repository method. It returns the next upcoming events, sorted by start date, and ignores the storage page because the plugin shows events from everywhere:<\/p>\n The table is You could mock the query object and assert that The price is speed: a functional test case needs a second or two to set up its instance. For repository code that is a good deal.<\/p>\n For the example the layout inside the extension looks like this. Version 9 of the framework supports both TYPO3 13 and 14, with PHPUnit 11 or 12:<\/p>\n The framework itself says to copy these two files instead of using them from CSV data sets are the easiest way to describe database rows. The first line names the table, the next line the columns (with a leading comma), then one line per record. One file can hold several tables.<\/p>\n Record 2 lies in the past and must not appear. Records 3 and 1 lie in the future, and 3 comes first. I like to use timestamps far away from today, so the test does not break next year.<\/p>\n A few things are worth explaining:<\/p>\n If a row is missing or a value differs, PHPUnit prints a table with the difference. Much better than a The framework reads the database connection from environment variables. The quickest start is SQLite, if the Before a release I also run against MariaDB, because that is what production uses. Each test case creates its own database with a suffix, so the user needs the right to create databases. In DDEV the Put both commands into Composer scripts and you will never type them again.<\/p>\n Once the first test is green, the second one costs five minutes. That is the whole trick: get the first one running. Cheers!<\/p>\n Setting up typo3\/testing-framework for a v13\/v14 extension: a FunctionalTestCase, CSV fixtures, a custom repository query and a database assertion, run inside DDEV.<\/p>\n","protected":false},"author":1,"featured_media":61,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[17],"tags":[14,30,32,31,5],"class_list":["post-60","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-typo3","tag-extbase","tag-extension-development","tag-php-8","tag-testing","tag-typo3"],"yoast_head":"\ntypo3\/testing-framework<\/code>, I was also like a snail, reading bootstrap files instead of writing a test.<\/p>\nThe thing we want to test<\/h2>\n
<?php\n\ndeclare(strict_types=1);\n\nnamespace MyVendorMyEventsDomainRepository;\n\nuse MyVendorMyEventsDomainModelEvent;\nuse TYPO3CMSExtbasePersistenceQueryInterface;\nuse TYPO3CMSExtbasePersistenceQueryResultInterface;\nuse TYPO3CMSExtbasePersistenceRepository;\n\n\/**\n * @extends Repository<Event>\n *\/\nfinal class EventRepository extends Repository\n{\n \/**\n * @return QueryResultInterface<int, Event>\n *\/\n public function findUpcoming(DateTimeInterface $now, int $limit = 3): QueryResultInterface\n {\n $query = $this->createQuery();\n $query->getQuerySettings()->setRespectStoragePage(false);\n\n return $query\n ->matching($query->greaterThanOrEqual('startDate', $now))\n ->setOrderings(['startDate' => QueryInterface::ORDER_ASCENDING])\n ->setLimit($limit)\n ->execute();\n }\n}<\/code><\/pre>\ntx_myevents_domain_model_event<\/code> with title<\/code> and start_date<\/code> (a datetime field stored as integer timestamp). A query like this is exactly where bugs hide: wrong operator, wrong sort direction, a forgotten storage page setting. A unit test cannot catch them, because the real work happens in the database.<\/p>\nWhy not a unit test with mocks?<\/h2>\n
greaterThanOrEqual()<\/code> was called with startDate<\/code>. That test would pass, and it would prove almost nothing. It tests that the code was written the way it was written. It does not test that Extbase converts the date to the right timestamp, that the column is mapped correctly, or that the sorting does what you think. A functional test boots a real TYPO3 instance with a real database, imports rows, and runs the real query. When it is green, the feature works.<\/p>\nWhere the files go<\/h2>\n
Fixtures<\/code> holds the data to import, Assertions<\/code> the expected database state after a write:<\/p>\nTests\/Functional\/Domain\/Repository\/\n\u251c\u2500\u2500 EventRepositoryTest.php\n\u251c\u2500\u2500 Fixtures\/\n\u2502 \u2514\u2500\u2500 Events.csv\n\u2514\u2500\u2500 Assertions\/\n \u2514\u2500\u2500 EventAdded.csv<\/code><\/pre>\nStep 1: Install the testing framework<\/h2>\n
ddev composer require --dev \"typo3\/testing-framework:^9\"\nmkdir -p Build\/phpunit\ncp vendor\/typo3\/testing-framework\/Resources\/Core\/Build\/FunctionalTests.xml Build\/phpunit\/\ncp vendor\/typo3\/testing-framework\/Resources\/Core\/Build\/FunctionalTestsBootstrap.php Build\/phpunit\/<\/code><\/pre>\nvendor\/<\/code>. In the copied XML, change the test suite directory to your extension, for example ..\/..\/Tests\/Functional\/<\/code>.<\/p>\nStep 2: The CSV fixture<\/h2>\n
\"pages\"\n,\"uid\",\"pid\",\"title\"\n,1,0,\"Root\"\n,5,1,\"Events\"\n\"tx_myevents_domain_model_event\"\n,\"uid\",\"pid\",\"title\",\"start_date\",\"hidden\",\"deleted\"\n,1,5,\"TYPO3 meetup\",1924984800,0,0\n,2,5,\"Old barcamp\",1577872800,0,0\n,3,5,\"Code sprint\",1893448800,0,0<\/code><\/pre>\nStep 3: The test case<\/h2>\n
<?php\n\ndeclare(strict_types=1);\n\nnamespace MyVendorMyEventsTestsFunctionalDomainRepository;\n\nuse MyVendorMyEventsDomainModelEvent;\nuse MyVendorMyEventsDomainRepositoryEventRepository;\nuse PHPUnitFrameworkAttributesTest;\nuse TYPO3CMSCoreCoreSystemEnvironmentBuilder;\nuse TYPO3CMSCoreHttpServerRequest;\nuse TYPO3CMSExtbaseConfigurationConfigurationManagerInterface;\nuse TYPO3CMSExtbasePersistenceGenericPersistenceManager;\nuse TYPO3TestingFrameworkCoreFunctionalFunctionalTestCase;\n\nfinal class EventRepositoryTest extends FunctionalTestCase\n{\n protected array $testExtensionsToLoad = [\n 'myvendor\/my-events',\n ];\n\n private EventRepository $subject;\n\n protected function setUp(): void\n {\n parent::setUp();\n \/\/ Extbase reads its configuration from a request; give it a minimal one\n $request = (new ServerRequest())\n ->withAttribute('applicationType', SystemEnvironmentBuilder::REQUESTTYPE_BE);\n $this->get(ConfigurationManagerInterface::class)->setRequest($request);\n\n $this->importCSVDataSet(__DIR__ . '\/Fixtures\/Events.csv');\n $this->subject = $this->get(EventRepository::class);\n }\n\n #[Test]\n public function findUpcomingReturnsFutureEventsSortedByStartDate(): void\n {\n $now = new DateTimeImmutable('@1735689600');\n\n $titles = array_map(\n static fn(Event $event): string => $event->getTitle(),\n $this->subject->findUpcoming($now)->toArray()\n );\n\n self::assertSame(['Code sprint', 'TYPO3 meetup'], $titles);\n }\n\n #[Test]\n public function addedEventIsWrittenToTheDatabase(): void\n {\n $event = new Event();\n $event->setPid(5);\n $event->setTitle('Release party');\n $event->setStartDate(new DateTimeImmutable('@1956520800'));\n\n $this->subject->add($event);\n $this->get(PersistenceManager::class)->persistAll();\n\n $this->assertCSVDataSet(__DIR__ . '\/Assertions\/EventAdded.csv');\n }\n}<\/code><\/pre>\n\n
$testExtensionsToLoad<\/code> accepts the Composer package name when the extension is required in the root composer.json<\/code>. Its TCA and database schema are set up in a fresh test instance.<\/li>\n$this->get()<\/code> fetches services from the container, including non-public ones, so you test the real repository with real dependencies.<\/li>\nsetUp()<\/code> is the same pattern the core uses in its own Extbase tests. Without it, the configuration manager has no context to work with.<\/li>\nsetPid(5)<\/code> keeps the new record on the events folder instead of depending on a storage pid from TypoScript, which the test instance does not have.<\/li>\n<\/ul>\nStep 4: Assert the database state<\/h2>\n
assertCSVDataSet()<\/code> compares only the columns you list. That keeps the assertion readable:<\/p>\n\"tx_myevents_domain_model_event\"\n,\"uid\",\"pid\",\"title\",\"start_date\"\n,1,5,\"TYPO3 meetup\",1924984800\n,2,5,\"Old barcamp\",1577872800\n,3,5,\"Code sprint\",1893448800\n,4,5,\"Release party\",1956520800<\/code><\/pre>\nvar_dump<\/code> in a controller.<\/p>\nStep 5: Run it in DDEV<\/h2>\n
pdo_sqlite<\/code> extension is available in your web container:<\/p>\nddev exec typo3DatabaseDriver=pdo_sqlite \n vendor\/bin\/phpunit -c Build\/phpunit\/FunctionalTests.xml<\/code><\/pre>\nroot<\/code> user can do that:<\/p>\nddev exec typo3DatabaseDriver=mysqli typo3DatabaseHost=db \n typo3DatabaseUsername=root typo3DatabasePassword=root typo3DatabaseName=func \n vendor\/bin\/phpunit -c Build\/phpunit\/FunctionalTests.xml<\/code><\/pre>\nProblems you will probably meet<\/h2>\n
\n
setRespectStoragePage(false)<\/code>.<\/li>\n$now<\/code> into the method instead of calling new DateTime()<\/code> inside makes it testable. Small design change, big win.<\/li>\nstart_date<\/code>), not Extbase property names (startDate<\/code>). Mixing them up gives a confusing failure.<\/li>\n<\/ul>\nFurther reading<\/h2>\n
\n