Download the PHP package rwslinkman/metronome without Composer

Metronome

This project is deprecated and should no longer be used.
Please read the DEPRECATION NOTICE for further information.

Metronome is a lightweight test utility for Symfony 3 and Symfony 4 (PHP) applications.
It provides a steady base for easy mocking and injection of the Symfony Container.
Let Metronome help you orchestrate the Symfony in your hands!

Metronome aims to make functional testing easier for Symfony projects.
It creates a custom Kernel and Container and injects everything you need for a fully set-up Symfony environment.
You application is automatically loaded using Symfony's WebTestCase and KernelBrowser client.

Metronome provides several builders to aid in your tests:

• MetronomeBuilder
• MetronomeDoctrineMockBuilder
• MetronomeFileSystemBuilder

Using the Metronome you can:

• Build a MetronomeEnvironment that sends GET and POST requests to test your Controller classes
• Build a mocked EntityManager to test classes that have database interactions
• Build a mocked ReferenceRepository to test your Fixture classes
• Build a mocked ManagerRegistry to test your EntityRepository classes
• Inject MetronomeLoginData to bypass your GuardAuthenticator protection
• Mock Symfony Forms using the MetronomeFormDataBuilder and MetronomeEntityFormDataBuilder
• Verify the contents of the Symfony FlashBag

DEPRECATION NOTICE

This project is no longer in active development.
Initially, the project was created in a time when Symfony did not fully support dependency injection for testing.
Also, it was difficult to create mocks that could be used in the Symfony kernel.
Testing your Symfony Controllers was pretty difficult at the time. This is no longer the case.

Over the years, both Symfony and PHPUnit have seen great improvements in these parts.
Metronome is therefor becoming more and more obsolete.
It becomes more of a burden than a benefit for projects.
Using the improved dependency injection system, testing Symfony Controllers can be done well without Metronome.

In case you want to migrate away from Metronome, take a look at mocking in PHPUnit.
These mocks can easily be passed in Controllers' constructors when testing.

Installation

You can install Metronome using composer to get the package from Packagist.

Metronome is not needed in the production environment, since it is a test utility.
The latest version is 3.0.0.
Older versions may work for Symfony 3 projects, but this may prove difficult and is not supported.
For bleeding edge development, point to the dev-develop or dev-master version.

Usage

Metronome is used in combination with PHPUnit and the Symfony WebTestCase, which extends PHPUnit's TestCase.

MetronomeBuilder

With the MetronomeBuilder, you can create a fully set-up environment of your application.
The connection to the database, EntityManager, is automatically mocked.
You can inject your own Kernel, or use the ready-made MetronomeKernel.
After setting this up, you inject services, repositories and other objects you need. Calling the build function returns a MetronomeEnvironment that allows to fire GET, POST, and PUT to your application.

Creating an environment for your application with no mocks (Doctrine excluded):

Testing a Controller

Setup a MetronomeEnvironment using the MetronomeBuilder.
The most basic test returns a Response from Symfony\HttpFoundation.
Make sure your test extents WebTestCase to make use of Symfony's Client for HTTP requests.

If you have custom services configured in Symfony's services.yaml, then you can mock those during tests.
This is convenient when testing Controllers. You can make use of the MetronomeDynamicMockBuilder that easily mocks classes.

For more static components that you inject as services, you can use ServiceInjector to return basic values.
Optionally, add some setters to set your desired outcome for the mocked function.
MetronomeBuilder has a special injectService() function to accept these type of injections.

Arguments and Definitions

When testing Controllers, you will need to deal with constructor arguments that are injected by Symfony.
Metronome provides the MetronomeArgument that injects a mock directory into the Controller contructor when Symfony needs it.
Provide the parameter name and the service you want to inject and call setupController on your MetronomeBuilder. Metronome provides a small catalog with premade Arguments.

Note: the services must be injected in the Container when building a MetronomeEnvironment.

Symfony might want to load system services earlier than calling the Controller.
In that case, add a MetronomeDefinition to the test client:

Mocking the database and EntityManager

Classes that use the Doctrine EntityManager can be tested using Metronome.
These are usually the services in your Symfony application.
You can inject RepoInjector classes to mock your EntityRepository.

The RepoInjector is very similar to the ServiceInjector.
It wraps around a single Doctrine Entity.

Testing Fixtures

Fixtures are part of the Doctrine FixtureBundle.
Metronome can be used to verify some of the Fixture behaviour.

Bypassing the Guard authentication system

When testing Controllers, you can bypass your GuardAuthenticator by injecting MetronomeLoginData into the environment builder.
According to the Symfony documentation, the authenticator is defined in your services.yaml.
This service identifier is used when creating MetronomeLoginData. Use this to bypass the firewall configured in security.yaml during tests.

Using the requiresLogin function is not mandatory. If you want to test your firewall, omit the call.

Testing forms in your Controllers

Most Symfony websites have forms in their Controllers, which can easily be tested with Metronome.
Metronome provides 2 builders, that build a MetronomeFormData object.
This data can be injected into the MetronomeBuilder to mock a form.

If you provide an instance of the object being modified to the Symfony FormBuilder, it is directly updated when submitting a valid form.
You can mock this updated object by using the MetronomeEntityFormDataBuilder.

If you have simpler forms, where you directly use the input data, you can make use of the MetronomeFormDataBuilder.
It allows to directly inject values into the form fields.

Using the built form data is done easily by injecting it into the MetronomeBuilder.

You can use injectForm multiple times.
The FormFactory mock will return the forms in the order they were injected.
There are cases where you want to write a test specified to the second form. To skip the first form, you can inject MetronomeNonSubmittedForm or MetronomeInvalidForm before your actual MetronomeFormData.

Please note that this example uses a CSS selector, which requires the symfony/css-selector dependency.

Verifying FlashBag data

The FlashBag in the user's session can be a convenient tool for your website.
Metronome allows you to access the FlashBag through the MetronomeEnvironment.
This can help you verify the outcome of your GET or POST request even better.

In the example below, assume that the page has no log messages to show and reports this in a flash message.

The getFlashBag function returns an associative array, with an entry for every key.
Each key entry is also an array, containing the flash messsages associated to that key.