Helper containers #974

everzet · 2016-12-20T22:16:29Z

Narrative

Since I introduced support for multiple contexts in 3.0, the most asked question among the Behat newcomers goes along the lines of "how do I share state between multiple contexts?". I was reluctant to provide a systematic, built-in answer to this question for two reasons:

Behat is not your dependency management framework. Wiring applications together is usually a responsibility of application frameworks. I considered that it is better left to Symfony2Extension and friends to provide servicing configuration.
I generally consider sharing state between contexts to be an anti-pattern. It often highlights wrongly drawn context boundaries and trades off organizational simplicity for a short-term convenience.

Late push for container interoperability made me believe I finally have an answer to sharing state without giving Behat responsibility it ultimately wasn't built for. On top of that, recently conducted by me coaching, pairing and conversations with people inside and across the communities (thanks @tooky) made me realize that state/behaviour sharing still has very legitimate use-cases in many situations. Especially for Modelling by Example and similar workflows.

I believe this PR to be an elegant answer to the need without breaking very clear responsibility context Behat has. This PR is me finally trying to answer the question most community members keep asking.

General principles

Before starting with the spec, I decided on two balancing principles that the solution must follow:

Convenience limited to simple cases. It should be simple enough to never get to the point where Behat gets confused with the application framework. Service sharing should work seamlessly for simple cases, but nudge people towards proper dependency management approaches in more complicated ones. If all you need is to instantiate an isolated environment with 1-2 independent, but shared services, you should be able to bootstrap in seconds.
Complex cases served via interoperability. In case of complex cases Behat must favour reuse. Whatever artefact Behat users end up producing as part of their service sharing procedure should be fairly decoupled from Behat and reusable with other, unaware of Behat frameworks. If you spend a lot of time wiring up your complex dependency tree for Behat, that work shouldn't be lost on your tests alone.

Enter helper containers

Helper containers are service containers that you can configure to provide shared services for your contexts. And those services indeed be shared between your contexts, with all state and behaviour. Here's simple rules I followed in designing them:

A single optional container is allowed per suite
Having container enables you to use its services as context arguments via @name syntax
Container is rebuilt and is isolated between scenarios
Container is configured via suite's services option
Container is a class implementing Interop\Container\ContainerInterface
There is a built-in container if you need a very simple service-sharing, configurable through the same services setting
There is an extension point that allows Behat extensions provide their own containers for end-users via @name syntax

How to use a helper container

The rest of this PR will go in more general details on how to use the feature. For more detailed info and examples, please read the feature file.

Built-in container

The simplest way of using helper container is to define a service (or services) that would be injected (and shared) between your contexts in the scope of a single scenario:

default:
  suites:
    default:
      contexts:
        - FirstContext:
          - "@shared_service"
        - SecondContext:
          - "@shared_service"

      services:
        shared_service: "SharedService"

This definition will make Behat automatically instantiate SharedService before each scenario and pass it as a first argument (via @... notation) to both FirstContext and SecondContext - exact same instance.

There's even a bit more verbose syntax that allows you to provide custom arguments and even factory method for each class:

      services:
        shared_service:
          class: "SharedService"
          factory_method: "fromNothing"
          arguments: []

Please note that built-in container does not allow you to use defined services as other service arguments. This is to both keep the built-in container away from becoming a full-blown service container and to nudge you towards external container in cases where you do need a deeply nested, highly-wired dependency tree.

External container class

Alternatively, you can use a custom container class that implements Interop\Container\ContainerInterface:

default:
  suites:
    default:
      contexts:
        - FirstContext:
          - "@shared_service"
        - SecondContext:
          - "@shared_service"

      services: "MyContainer"

Don't forget the class itself. You can even place it near you context classes (in features/bootstrap):

<?php

use Interop\Container\ContainerInterface;

final class MyContainer implements ContainerInterface
{
    // ...
}

And yes, you can utilise custom factory methods in those too:

default:
  suites:
    default:
      contexts:
        - FirstContext:
          - "@shared_service"
        - SecondContext:
          - "@shared_service"

      services: "MyContainer::fromEnvironment"

Container from extension

The third and the last way is to use containers provided by your favourite extensions. Like that:

default:
  suites:
    default:
      contexts:
        - FirstContext:
          - "@shared_service"
        - SecondContext:
          - "@shared_service"

      services: "@symfony_extension.container"

The example above doesn't yet work, because it requires extension authors to actually provide that container explicitly from withing their config. But I hope they'll soon follow. Feel free to help them :).

Further details

For further details, as usual, I advise you to dive into the feature file itself. It provides ultimate information, reasoining and examples behind this feature. Oh, yeah, it also is a stellar automated test to make sure I implemented feature correctly in the first place :)

As usual, feedback is greatly appreciated.

stof · 2016-12-21T10:27:02Z

composer.json

+        "symfony/event-dispatcher":            "~2.1||~3.0",
+        "symfony/translation":                 "~2.3||~3.0",
+        "symfony/yaml":                        "~2.1||~3.0",
+        "symfony/class-loader":                "~2.1||~3.0",


I would actually stop aligning constraint to avoid such kind of diffs

Agreed. I grown to dislike this style too. Was just going through motions.

stof · 2016-12-21T10:37:00Z

src/Behat/Behat/HelperContainer/ServiceContainer/HelperContainerExtension.php

+    {
+        if (method_exists($definition, 'isShared')) {
+            return $definition->isShared();
+        } else if (method_exists($definition, 'getScope')) {


if is enough thanks to the return. And I'm not even sure we need this second check

To stop static analysis tools (like Scrutinizer) from complaining about non-existing method :(

stof · 2016-12-21T10:37:42Z

src/Behat/Behat/HelperContainer/ServiceContainer/HelperContainerExtension.php

+     *
+     * @return bool
+     *
+     * @deprecated remove after upgrading to Symfony 2.8+


you should not mark it as deprecated, as you should not call deprecated APIs internally. And this is a private function anyway.
This looks more like a TODO than a deprecation here btw

Good shout. I kinda use these interchangeably.

stof · 2016-12-21T10:38:39Z

src/Behat/Behat/HelperContainer/ServiceContainer/HelperContainerExtension.php

+        $references = $this->processor->findAndSortTaggedServices($container, self::HELPER_CONTAINER_TAG);
+
+        foreach ($references as $reference) {
+            if ($this->isDefinitionShared($container->getDefinition($reference))) {


should be (string) $reference as getDefinition expects a string (the id), not a Reference object

Implicit conversion VS explicit conversion. I'm easier with this case than the one you mentioned next. In this particular case it is indeed unclear that what I am expected to pass to $container->getDefinition(...) is a string, not an object. I'd be happy to make it explicit.

Thus Symfony never explicitly mentions that getDefinition supports castable objects. If it works today, it is purely because of an implementation detail (probably because of using lowercase which supports it). So it means that passing a castable object is not covered by the BC policy (as it is a case not respecting the documented contract). So making it explicit is necessary to be future-proof

Thanks for explanation. Makes perfect sense and I would change it in this case.

stof · 2016-12-21T10:38:53Z

src/Behat/Behat/HelperContainer/ServiceContainer/HelperContainerExtension.php

+        foreach ($references as $reference) {
+            if ($this->isDefinitionShared($container->getDefinition($reference))) {
+                throw new WrongServicesConfigurationException(sprintf(
+                    'Container services must not be configured as shared, but `@%s` is.', $reference


same here about using the string

This again can be considered implicit VS explicit. Except in this case I obviously tell sprintf I need a string (@%s). Hence, I'd argue conversion is already explicit here and additional conversion would only confuse things.

That is unless you have a different tech/clarity reason I haven't thought of yet :)

yeah, I was not sure about it being necessary here.

Cool. I'll introduce casting only to the getDefinition(...) case then.

stof · 2016-12-21T10:41:55Z

src/Behat/Behat/HelperContainer/ServiceContainer.php

+ *
+ * @author Konstantin Kudryashov <ever.zet@gmail.com>
+ */
+interface ServiceContainer extends ContainerInterface


what is the goal of this interface, when the code actually expects Interop\Container\ContainerInterface anyway ?

I was trying to give people who don't care about Interop\Container\ContainerInterface a clear, transparent entry.

I'm actually not super-attached to it.

Actually, having separate interface breaks the second general principle. So I'll go ahead and drop Behat\Behat\HelperContainer\ServiceContainer.

everzet · 2016-12-21T15:36:32Z

@stof thanks for your feedback, as always. I fixed everything you highlighted.

ciaranmcnulty

This looks good - have you checked to see how it interacts with Symfony2Extension?

Specialised syntax in the config file, i.e. @-prefixed values, may not come under the normal BC rules but we should consider this.

ciaranmcnulty · 2016-12-21T15:45:21Z

features/helper_containers.feature

+
+  Rules:
+    - A single optional container is allowed per suite
+    - Having container enables you to use its services as context arguments via `@name` syntax


'Having a container"

ciaranmcnulty · 2016-12-21T15:48:17Z

src/Behat/Behat/Context/Argument/AggregateFactory.php

+ *
+ * @author Konstantin Kudryashov <ever.zet@gmail.com>
+ */
+final class AggregateFactory implements SuiteScopedResolverFactory


I'd rather this was called Composite, after the design pattern. Aggregate risks confusion with the DDD concept, or other usages where an aggregate is a collection

ciaranmcnulty · 2016-12-21T15:49:53Z

src/Behat/Behat/Context/Argument/NullFactory.php

+ *
+ * @author Konstantin Kudryashov <ever.zet@gmail.com>
+ */
+final class NullFactory implements SuiteScopedResolverFactory


There might be better naming - noop from the comment makes sense, or maybe empty?

If we follow the pattern naming from the previous comment, we keep following it for null objects :)

ciaranmcnulty · 2016-12-21T15:55:58Z

src/Behat/Behat/HelperContainer/Argument/ServicesResolverFactory.php

+     */
+    private function createContainerFromString($settings)
+    {
+        if ('@' === mb_substr($settings, 0, 1)) {


A similar check takes place in ServicesResolverFactory - can these be done in one place? Perhaps a value object?

Potentially. But that's too small of an op to worry about reuse at this point.

everzet · 2016-12-21T16:05:41Z

Specialised syntax in the config file, i.e. @-prefixed values, may not come under the normal BC rules but we should consider this.

@ciaranmcnulty @ prefix only works when you have services: configuration option provided. So no problems for BC

ciaranmcnulty · 2016-12-21T16:07:37Z

If I have services option and the symfony2extension is there fallback, or are all @-params interpreted as non-Symfony services?

everzet · 2016-12-21T16:15:44Z

@ciaranmcnulty service-based resolvers come first as they are more specific (as in local to suites). I'd avoid using services with Symfony2Extension until it is updated to support new functionality in proper way.

Step to remove initializers, and use real contexts Behat/Behat#974 https://github.com/Behat/Behat/blob/master/features/helper_containers.feature#L239

everzet added 3 commits December 20, 2016 18:22

Describe how helper containers expected to work

72e45c3

Add SuiteScopedResolverFactory extension point to Context

764b893

Introduce HelperContainer extension

95f7b6d

everzet added the Feature label Dec 20, 2016

everzet added 2 commits December 20, 2016 22:34

Cleanup styling/complexity

37c1eaf

Add support for Symfony prior to 2.8

7e3b84e

everzet force-pushed the feature/helper-containers branch from 4282186 to 7e3b84e Compare December 20, 2016 22:46

Flip check for deprecated code

91d0b72

everzet force-pushed the feature/helper-containers branch from 2050b58 to 91d0b72 Compare December 20, 2016 23:02

stof reviewed Dec 21, 2016

View reviewed changes

everzet added 4 commits December 21, 2016 14:59

Clear unnecessary alignment from composer.json

3b768aa

Explicitly case Reference to string before getDefinition

546ad65

Switch deprecation message to todo

023ff9d

Drop Behat's own ServiceContainer interface

03bf9b1

ciaranmcnulty reviewed Dec 21, 2016

View reviewed changes

Fix typo in the helper_containers.feature

cd4bd36

Rename AggregateFactory to CompositeFactory

0ae3f9f

everzet added 2 commits December 25, 2016 13:34

Merge branch 'master' into feature/helper-containers

ad5858a

Updated CHANGELOG

ab5a441

everzet merged commit 5957537 into master Dec 25, 2016

everzet deleted the feature/helper-containers branch December 25, 2016 13:39

Taluu added a commit to Taluu/Behapi that referenced this pull request Jan 25, 2017

Add a HelperContainer

180f415

Step to remove initializers, and use real contexts Behat/Behat#974 https://github.com/Behat/Behat/blob/master/features/helper_containers.feature#L239

Taluu added a commit to Taluu/Behapi that referenced this pull request Jan 26, 2017

Add a HelperContainer

71fc449

Step to remove initializers, and use real contexts Behat/Behat#974 https://github.com/Behat/Behat/blob/master/features/helper_containers.feature#L239

Taluu mentioned this pull request Jan 26, 2017

HelperContainer Taluu/Behapi#10

Merged

gorghoa mentioned this pull request Jul 26, 2017

Decouple steps argument injection and the store gorghoa/ScenarioStateBehatExtension#30

Open

everzet mentioned this pull request Sep 2, 2017

Services autowiring #1071

Merged

DonCallisto mentioned this pull request Oct 10, 2018

Enable Symfony DI autowiring Behat/Symfony2Extension#128

Closed

tentacode mentioned this pull request Mar 22, 2019

Behat dependency injection is not working, replaced by Laravel's DI laracasts/Behat-Laravel-Extension#84

Open

Helper containers #974

Helper containers #974

everzet commented Dec 20, 2016 •

edited

stof Dec 21, 2016

everzet Dec 21, 2016 •

edited

stof Dec 21, 2016

everzet Dec 21, 2016

stof Dec 21, 2016

everzet Dec 21, 2016

stof Dec 21, 2016

everzet Dec 21, 2016 •

edited

stof Dec 21, 2016

everzet Dec 21, 2016

stof Dec 21, 2016

everzet Dec 21, 2016

stof Dec 21, 2016

everzet Dec 21, 2016

stof Dec 21, 2016

everzet Dec 21, 2016

everzet Dec 21, 2016

everzet Dec 21, 2016 •

edited

everzet commented Dec 21, 2016

ciaranmcnulty left a comment

ciaranmcnulty Dec 21, 2016

ciaranmcnulty Dec 21, 2016

ciaranmcnulty Dec 21, 2016

everzet Dec 21, 2016

ciaranmcnulty Dec 21, 2016

everzet Dec 21, 2016

everzet commented Dec 21, 2016 •

edited

ciaranmcnulty commented Dec 21, 2016

everzet commented Dec 21, 2016

Helper containers #974

Helper containers #974

Conversation

everzet commented Dec 20, 2016 • edited

Narrative

General principles

Enter helper containers

How to use a helper container

Built-in container

External container class

Container from extension

Further details

Choose a reason for hiding this comment

everzet Dec 21, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

everzet Dec 21, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

everzet Dec 21, 2016 • edited

Choose a reason for hiding this comment

everzet commented Dec 21, 2016

ciaranmcnulty left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

everzet commented Dec 21, 2016 • edited

ciaranmcnulty commented Dec 21, 2016

everzet commented Dec 21, 2016

everzet commented Dec 20, 2016 •

edited

everzet Dec 21, 2016 •

edited

everzet Dec 21, 2016 •

edited

everzet Dec 21, 2016 •

edited

everzet commented Dec 21, 2016 •

edited