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 config

  • SYLIUS_TEST_APP_ROUTES_TO_IMPORT: Registers your plugin routes

  • SYLIUS_TEST_APP_BUNDLES_PATH: Loads only bundles specific to your plugin

  • SYLIUS_TEST_APP_BUNDLES_REPLACE_PATH: Replaces the default bundles entirely

  • SYLIUS_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 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\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?