--- title: "Running functional tests" manual: "TYPO3 Explained" version: "main" permalink: "https://docs.typo3.org/permalink/t3coreapi:testing-functional-run@main" source: "Testing/FunctionalTesting/Running.rst" rendered: "2026-09-23T17:05:17+00:00" --- # Running functional tests {#testing-functional-run} Functional tests execute test cases within a fully initialized TYPO3 instance. Unlike unit tests, functional tests interact with the TYPO3 framework, service container, and an active database connection. Before running functional tests, ensure that the TYPO3 testing framework ([`typo3/testing-framework`](https://packagist.org/packages/typo3/testing-framework)) and PHPUnit ([`phpunit/phpunit`](https://packagist.org/packages/phpunit/phpunit)) are installed as Composer development dependencies. For version compatibility between TYPO3, PHP, and the testing framework, see [Install PHPUnit and the TYPO3 testing framework](https://docs.typo3.org/permalink/t3coreapi:testing-unit-run-install@main). ## Quick setup with extension kickstarter {#testing-functional-run-kickstarter} If you are developing a TYPO3 extension, the fastest way to set up the test environment is using the Extension Kickstarter ([`friendsoftypo3/kickstarter`](https://packagist.org/packages/friendsoftypo3/kickstarter)): ```bash composer require --dev friendsoftypo3/kickstarter vendor/bin/typo3 make:testenv [extension_key] ``` The command generates: - `Build/phpunit/FunctionalTests.xml` and `Build/phpunit/FunctionalTestsBootstrap.php` - `Build/phpunit/UnitTests.xml` and `Build/phpunit/UnitTestsBootstrap.php` - `Build/Scripts/runTests.sh` (the containerized test runner) - Standard configuration files for coding guidelines and static analysis (such as `.php-cs-fixer.dist.php` and `phpstan.neon`) - Enriches `composer.json` with the necessary `require-dev` and `autoload-dev` definitions For more information, see [Testing extensions](https://docs.typo3.org/permalink/t3coreapi:testing-extensions@main). ## Provide configuration files for functional tests {#testing-functional-run-configure} If you set up testing manually or need to customize an existing configuration, the TYPO3 testing framework provides template files: - [vendor/typo3/testing-framework/Resources/Core/Build/FunctionalTests.xml](https://github.com/TYPO3/testing-framework/blob/main/Resources/Core/Build/FunctionalTests.xml) - [vendor/typo3/testing-framework/Resources/Core/Build/FunctionalTestsBootstrap.php](https://github.com/TYPO3/testing-framework/blob/main/Resources/Core/Build/FunctionalTestsBootstrap.php) Copy these files into your project under `Build/phpunit/`. Open `FunctionalTests.xml` and adjust the path in the `` definition to point to your functional test directory. Because the configuration file is located two directory levels deep in `Build/phpunit/`, use `../../` to navigate back to the root directory. By convention, functional tests reside in `Tests/Functional/`: **FunctionalTests.xml for extension testing** ```diff - ../../../../../../typo3/sysext/*/Tests/Functional/ + ../../Tests/Functional/ ``` For testing within a full project with local extensions in `packages/`: **FunctionalTests.xml for project testing** ```diff - ../../../../../../typo3/sysext/*/Tests/Functional/ + ../../Tests/Functional/ + ../../packages/*/Tests/Functional/ ``` The bootstrap file `FunctionalTestsBootstrap.php` instantiates `\TYPO3\TestingFramework\Core\Testbase`, resolves paths, and ensures the temporary directories `typo3temp/var/tests` and `typo3temp/var/transient` exist before executing test suites. ## Run functional tests with runTests.sh {#testing-functional-run-runtests} The recommended and standardized approach for running tests across TYPO3 extensions is `Build/Scripts/runTests.sh`. It starts dedicated Docker containers with all required dependencies and manages database containers automatically. When using `runTests.sh`, you do not need to configure database credentials or set environment variables manually. The script takes care of starting the database service (SQLite, MariaDB, or PostgreSQL) and injecting all necessary configuration variables into the test environment. Run all functional tests using the default database (SQLite): ```bash Build/Scripts/runTests.sh -s functional ``` Run tests against a specific database system: ```bash Build/Scripts/runTests.sh -s functional -d mariadb Build/Scripts/runTests.sh -s functional -d postgres ``` Run tests with a specific PHP version: ```bash Build/Scripts/runTests.sh -s functional -p 8.4 ``` Run a single test file: ```bash Build/Scripts/runTests.sh -s functional -- \ Tests/Functional/Domain/Repository/MyRepositoryTest.php ``` For more details on `runTests.sh` options and workflows, see [Test runners](https://docs.typo3.org/permalink/t3coreapi:testing-organization@main). ## Run functional tests on the host system or with DDEV {#testing-functional-run-ddev} If you choose not to use `runTests.sh` and execute PHPUnit directly on your host system or inside DDEV, you must provide the database connection details yourself via environment variables. Functional tests create the database schema based on the TCA configuration and complementary [`ext_tables.sql`](../../ExtensionArchitecture/FileStructure/ExtTablesSql.md#file-extension-ext-tables-sql) definitions of all loaded extensions, and truncate database tables between tests. Without `runTests.sh` managing the environment, the test bootstrap requires the following environment variables: - **`typo3DatabaseDriver`** Specifies the database driver: - `pdo_sqlite`: Uses an SQLite file database. This is the simplest driver for local execution because it requires no database server setup or credentials. SQLite creates database files on the fly in `typo3temp/var/tests/functional-sqlite-dbs/`. - `mysqli`: Connects to a MySQL or MariaDB database server. - `pdo_pgsql`: Connects to a PostgreSQL database server. If using `mysqli` or `pdo_pgsql`, the following additional connection variables must be supplied: - `typo3DatabaseHost` (e.g. `127.0.0.1` or `db`) - `typo3DatabasePort` (e.g. `3306`) - `typo3DatabaseUsername` - `typo3DatabasePassword` - `typo3DatabaseName` These variables can either be passed inline when executing PHPUnit, or defined in the `` section of `Build/phpunit/FunctionalTests.xml`: **Build/phpunit/FunctionalTests.xml (excerpt)** ```xml ``` Running with SQLite on DDEV: ```bash ddev exec typo3DatabaseDriver=pdo_sqlite \ php vendor/bin/phpunit -c Build/phpunit/FunctionalTests.xml ``` Running with MariaDB or MySQL on DDEV: ```bash ddev exec \ typo3DatabaseDriver=mysqli \ typo3DatabaseHost=db \ typo3DatabasePort=3306 \ typo3DatabaseUsername=db \ typo3DatabasePassword=db \ typo3DatabaseName=db_test \ php vendor/bin/phpunit -c Build/phpunit/FunctionalTests.xml ``` To run a single test method or test case, use the `--filter` option: ```bash ddev exec typo3DatabaseDriver=pdo_sqlite \ php vendor/bin/phpunit -c Build/phpunit/FunctionalTests.xml \ --filter "MyFunctionalTest" ```