Doctrine Test Bundle

Because the bundle automatically rolls back all changes after a test, you cannot inspect the database state after a failure using standard tools. To debug, you can manually commit the transaction and terminate the process to persist the changes:

public function testMyTestCaseThatINeedToDebug()
{
    // ... database changes
    \DAMA\DoctrineTestBundle\Doctrine\DBAL\StaticDriver::commit();
    die;
    // The changes are now persisted in the DB for inspection
}

To enable automatic database rollbacks for every PHPUnit testcase, add the PHPUnitExtension to your phpunit.xml configuration:

<phpunit>
    ...
    <extensions>
        <bootstrap class="DAMA\DoctrineTestBundle\PHPUnit\PHPUnitExtension" />
    </extensions>
</phpunit>

Requirements & Compatibility:

• phpunit/phpunit must be a dev dependency (versions 11, 12, and 13 are supported via the built-in extension).
• Compatible with symfony/phpunit-bridge and its simple-phpunit script. If using the bridge, you may need to set the SYMFONY_PHPUNIT_VERSION environment variable to ensure a PHPUnit 10+ version is used.

To use the bundle for isolated database testing in Symfony, follow these steps:

1. Install via Composer:

   composer require --dev dama/doctrine-test-bundle

2. Enable the Bundle: If you are not using Symfony Flex, manually add the bundle to config/bundles.php:

   return [
       //...
       DAMA\DoctrineTestBundle\DAMADoctrineTestBundle::class => ['test' => true],
       //...
   ];

3. Configure DBAL (Version 8+ and DBAL < 4 only): Ensure use_savepoints is enabled for your relevant connections in your Doctrine configuration:

   doctrine:
       dbal:
           connections:
               default:
                   use_savepoints: true

To enable automatic database rollbacks for Behat scenarios, add the DoctrineExtension to your behat.yml configuration:

default:
   # ...
   extensions:
       DAMA\DoctrineTestBundle\Behat\ServiceContainer\DoctrineExtension: ~

Important Limitation: This only works if the tests are executed in the same process as Behat. It will not work when using tools like Selenium that call your application in a separate process.

The bundle manages driver connections statically in the current PHP process. You can control how these connections are reused by assigning connection_keys.

Reusing the same connection

If multiple DBAL connections are assigned the same key, they will share the same underlying internal driver connection instance.

dama_doctrine_test:
    connection_keys:
        default: custom_key
        foo: custom_key

Separate connections for Primary and Replicas

Since v8.1.0, the bundle uses the same driver connection for both primary and replicas by default. To force separate connections for primary and replicas, assign different keys:

dama_doctrine_test:
    connection_keys:
        default:
            primary: custom_key_primary
            replicas:
                replica_one: custom_key_replica

The bundle provides configuration keys to enable or disable its core features. By default, all features are enabled for all connections.

Default Configuration:

dama_doctrine_test:
    enable_static_connection: true
    enable_static_meta_data_cache: true
    enable_static_query_cache: true

Selective Connection Enabling: You can choose to enable the static connection only for specific connections instead of all of them:

dama_doctrine_test:
    enable_static_connection:
        connection_a: true

If your tests execute queries that cause an implicit commit (such as DDL statements like ALTER TABLE, DROP TABLE, etc.), the bundle's transaction management will fail.

Error Symptom: You will see a PDOException indicating a savepoint does not exist: Doctrine\DBAL\Driver\PDOException: SQLSTATE[42000]: Syntax error or access violation: 1305 SAVEPOINT DOCTRINE2_SAVEPOINT_2 does not exist

Cause: Implicit commits break the transaction wrapper provided by the bundle. Currently, there is no way for the bundle to work with these types of queries because they cannot be rolled back once the implicit commit occurs.

If you need to run a specific test without the bundle's automatic transaction rollback (e.g., for DDL queries or manual debugging), use the #[SkipDatabaseRollback] attribute. This can be applied at three levels:

1. Class level: Skips rollback for all tests within that class.
2. Abstract class level: Skips rollback for all tests in the class and its children.
3. Method level: Skips rollback for only that specific test method.

#[SkipDatabaseRollback]
public class MyTest extends \PHPUnit\Framework\TestCase {}

#[SkipDatabaseRollback]
abstract class MyAbstractTest extends \PHPUnit\Framework\TestCase {}

#[SkipDatabaseRollback]
public function testSingleMethod() {}

#[SkipDatabaseRollback] // applied to class, abstract class, or method

The DoctrineExtension allows you to integrate the Doctrine Test Bundle into your Behat testing suite. It registers a BehatListener which handles Doctrine-related events during test execution.

To use this extension, add it to your behat.yml configuration file under the key dama_doctrine.

default:
    extensions:
        DAMA\DoctrineTestBundle\Behat\ServiceContainer\DoctrineExtension:
            # Configuration options go here

When setKeepStaticConnections is enabled, you can control the transaction state of all active static connections simultaneously using the following static methods on StaticDriver:

• StaticDriver::beginTransaction(): Starts a transaction on all currently active static connections.
• StaticDriver::rollBack(): Rolls back the transaction on all currently active static connections.
• StaticDriver::commit(): Commits the transaction on all currently active static connections.

use DAMA\DoctrineTestBundle\Doctrine\DBAL\StaticDriver;

// Roll back all connections that were keyed with 'dama.connection_key'
StaticDriver::rollBack();