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 TestApplication 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 TestApplication Package

Update composer.json to allow experimental packages:

"minimum-stability": "dev",
"prefer-stable": true

Then, require the package:

composer require --dev sylius/test-application:~2.0.0

---

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%
CONFIGS_TO_IMPORT="@YourPlugin/tests/TestApplication/config/config.yaml"
ROUTES_TO_IMPORT="@YourPlugin/config/routes.yaml"
TEST_APP_BUNDLES_PATH="tests/TestApplication/config/bundles.php"
# Alternatively:
BUNDLES_TO_ENABLE="Your\\Bundle\\Namespace;"

📌 What these variables do:

• CONFIGS_TO_IMPORT: Loads your plugin config

• ROUTES_TO_IMPORT: Registers your plugin routes

• BUNDLES_TO_ENABLE or TEST_APP_BUNDLES_PATH: Loads your plugin’s bundle

---

3. Register Bundles (if needed)

Create tests/TestApplication/config/bundles.php:

<?php

return [
    Some\Dependency\Bundle::class => ['all' => true],
    Your\Bundle\Namespace::class => ['all' => true],
];

This works like Symfony’s main bundles.php and is only needed if BUNDLES_TO_ENABLE is not used.

---

4. Add Plugin Configuration

In tests/TestApplication/config/config.yaml:

imports:
    - { resource: "@YourPlugin/config/config.yaml" }
    - { resource: "services_test.php" }

twig:
    paths:
        '%kernel.project_dir%/../../../tests/TestApplication/templates': ~

parameters:
    your_plugin_param: '%kernel.project_dir%/../../../config/plugin_param/'

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 (Optional)

Create minimal controller definitions:

// YourPlugin/assets/shop/controllers.json
{
  "controllers": [],
  "entrypoints": []
}

// YourPlugin/assets/admin/controllers.json
{
  "controllers": [],
  "entrypoints": []
}

Extend tests/TestApplication/package.json with extra dependencies:

{
  "dependencies": {
    "trix": "^2.0.0",
    "swiper": "^11.2.6"
  }
}

These will be merged during yarn install.

---

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 or doctrine.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\TestApplication

Update composer.json:

"autoload-dev": {
    "psr-4": {
        "Tests\\Your\\Plugin\\TestApplication\\": "tests/TestApplication/src/"
    }
}

Then dump autoload:

composer dump-autoload

---

7. Ignore Local Overrides

In your .gitignore:

/tests/TestApplication/.env.local
/tests/TestApplication/.env.*.local

---

That’s it! Your plugin is now migrated and using the new TestApplication. For new plugins, check out the Plugin Setup Guide.