Migrating existing plugins to Test Application
In older versions of Sylius plugins, each plugin included a full Sylius + Symfony application in a tests/Application
directory. This local test app was used to run automated tests against the plugin.
While functional, this setup had serious drawbacks:
The entire Sylius app was duplicated in every plugin
Updates to Sylius core required manual syncing
Config drift and inconsistencies caused debugging issues
Setting it up required deep Symfony knowledge
With Sylius 2.x, this approach is considered outdated. Plugins should now use the shared Test Application provided by the sylius/test-application
package. It's faster to set up, easier to maintain, and works out of the box with CI.
This guide walks you step by step through migrating your plugin.
1. Install the Test Application Package
Require the package:
composer require --dev sylius/test-application:^2.0.0@alpha
2. Create Plugin-Specific Configuration
Make a new directory:
mkdir -p tests/TestApplication/config
Create .env
:
DATABASE_URL=mysql://[email protected]/test_application_%kernel.environment%
SYLIUS_TEST_APP_CONFIGS_TO_IMPORT="@YourPlugin/config/config.yaml"
SYLIUS_TEST_APP_ROUTES_TO_IMPORT="@YourPlugin/config/routes.yaml"
SYLIUS_TEST_APP_BUNDLES_PATH="tests/TestApplication/config/bundles.php"
# Optionally, replace the default bundles entirely
SYLIUS_TEST_APP_BUNDLES_REPLACE_PATH="tests/TestApplication/config/bundles.php"
# Optionally, use a semicolon-separated list to add needed bundles
SYLIUS_TEST_APP_BUNDLES_TO_ENABLE="Your\Bundle\Namespace\Plugin"
π What these variables do:
SYLIUS_TEST_APP_CONFIGS_TO_IMPORT
: Loads your plugin configSYLIUS_TEST_APP_ROUTES_TO_IMPORT
: Registers your plugin routesSYLIUS_TEST_APP_BUNDLES_PATH
: Loads only bundles specific to your pluginSYLIUS_TEST_APP_BUNDLES_REPLACE_PATH
: Replaces the default bundles entirelySYLIUS_TEST_APP_BUNDLES_TO_ENABLE
: Loads only bundles specific to your plugin using a semicolon-separated list
3. Register Bundles (if needed)
Create tests/TestApplication/config/bundles.php
:
<?php
return [
Some\Dependency\Bundle::class => ['all' => true],
Your\Bundle\Namespace\Plugin::class => ['all' => true],
];
This works like Symfonyβs main bundles.php
and is only needed if SYLIUS_TEST_APP_BUNDLES_PATH
is used.
4. Add Plugin Configuration
In tests/TestApplication/config/config.yaml
:
imports:
- { resource: "@YourPlugin/config/config.yaml" }
- { resource: "services_test.php" }
parameters:
your_plugin_param: '%kernel.project_dir%/../../../config/plugin_param/'
twig:
paths:
'%kernel.project_dir%/../../../tests/TestApplication/templates': ~
Create services_test.php
to load test-only services:
<?php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
return function (ContainerConfigurator $container) {
$env = $_ENV['APP_ENV'] ?? 'dev';
if (str_starts_with($env, 'test')) {
$container->import('../../../vendor/sylius/sylius/src/Sylius/Behat/Resources/config/services.xml');
$container->import('@YourPlugin/tests/Behat/Resources/services.xml');
}
};
5. Add JavaScript Integration
Create a symlink to node_modules
in Test Application:
ln -s vendor/sylius/test-application/node_modules node_modules
Create minimal controller definitions:
// YourPlugin/assets/shop/controllers.json
{
"controllers": [],
"entrypoints": []
}
// YourPlugin/assets/admin/controllers.json
{
"controllers": [],
"entrypoints": []
}
Optionally extend tests/TestApplication/package.json
with extra dependencies if your plugin requires additional JavaScript dependencies. You can also remove existing dependencies from the default package.json.dist
using the removeDependencies
and removeDevDependencies
keys:
{
"dependencies": {
"trix": "^2.0.0"
},
"devDependencies": {
"swiper": "^11.2.6"
},
"removeDependencies": [
"@symfony/ux-autocomplete"
],
"removeDevDependencies": [
"tom-select"
]
}
This file will be merged during yarn install
with the main TestApplication package.json
, while any packages listed under removeDependencies
or removeDevDependencies
will be omitted.
6. Handle Entity Extensions (If Needed)
If your plugin overrides Sylius entities:
Place extended classes in
tests/TestApplication/src/Entity
Register the mapping in
config.yaml
ordoctrine.yaml
:
doctrine:
orm:
entity_managers:
default:
mappings:
TestApplication:
is_bundle: false
type: attribute
dir: '%kernel.project_dir%/../../../tests/TestApplication/src/Entity'
prefix: Tests\Your\Plugin\Namespace
Update composer.json
:
"autoload-dev": {
"psr-4": {
"Tests\\Your\\Plugin\\Namespace\\": "tests/TestApplication/src/"
}
}
Then dump autoload:
composer dump-autoload
7. Define Public Directory
Configure public directory in your composer.json
:
"extra": {
"public-dir": "vendor/sylius/test-application/public"
}
8. Ignore Local Overrides And /var Directory
In your .gitignore
:
/tests/TestApplication/.env.local
/tests/TestApplication/.env.*.local
/var/
The default recommended structure of the Test Application and related directories should look like this:
your_plugin/
ββ assets/
β ββ admin/
β β ββ controllers.json
β ββ shop/
β ββ controllers.json
ββ node_modules/ (symlink)
ββ tests/
β ββ TestApplication/
β ββ config/
β β ββ config.yaml
β β ββ routes.yaml
β β ββ services.yaml
β β ββ services_test.php
β ββ src/
β β ββ Entity/
β β ββ [Your custom entities if needed]
β ββ templates/
β β ββ .gitkeep
β ββ .env
β ββ .env.local (not committed)
β ββ .env.test
β ββ .env.test.local (not committed)
β ββ bundles.php
β ββ package.json
ββ var
ββ cache/
ββ log/
Thatβs it! Your plugin is now migrated and using the new Test Application. For new plugins, check out the Plugin Setup Guide.
Last updated
Was this helpful?