Merge pull request #414 from pamil/behat-guide

Initial documentation for Behat with service support

behat/how-to-add-new-context.rst

@@ -0,0 +1,27 @@
+How to add a new context?
+=========================
+
+To add a new context it is needed to add an service in Behat container in ``etc/behat/services/contexts.xml`` file:
+
+.. code-block:: xml
+
+    <service id="sylius.behat.context.CONTEXT_CATEGORY.CONTEXT_NAME" class="%sylius.behat.context.CONTEXT_CATEGORY.CONTEXT_NAME.class%" scope="scenario">
+        <tag name="sylius.behat.context" />
+    </service>
+
+Then you can use it in your suite configuration:
+
+.. code-block:: yaml
+
+    default:
+        suites:
+            SUITE_NAME:
+                contexts_as_services:
+                    - "sylius.behat.context.CONTEXT_CATEGORY.CONTEXT_NAME"
+
+                filters:
+                    tags: "@SUITE_TAG"
+
+.. note::
+
+    The context categories are usually one of ``hook``, ``setup``, ``ui`` and ``domain``.

behat/how-to-add-new-page.rst

@@ -0,0 +1,43 @@
+How to add a new page object?
+=============================
+
+Sylius uses a solution inspired by ``SensioLabs/PageObjectExtension``, which provides an infrastructure to create
+pages that encapsulates all the user interface manipulation in page objects.
+
+To create a new page object it is needed to add an service in Behat container in ``etc/behat/services/pages.xml`` file:
+
+.. code-block:: xml
+
+    <service id="sylius.behat.page.PAGE_NAME" class="%sylius.behat.page.PAGE_NAME.class%" parent="sylius.behat.symfony_page" scope="scenario" public="false" />
+
+.. note::
+
+    There are some boilerplates for common pages, which you may use. The available parents are ``sylius.behat.page`` (``Sylius\Behat\Page\Page``)
+    and ``sylius.behat.symfony_page`` (``Sylius\Behat\Page\SymfonyPage``). It is not required for a page to extend any class as
+    pages are POPOs (Plain Old PHP Objects).
+
+Then you will need to add that service as a regular argument in context service.
+
+The simplest Symfony-based page looks like:
+
+.. code-block:: php
+
+    use Sylius\Behat\Page\SymfonyPage;
+
+    class LoginPage extends SymfonyPage
+    {
+        public function logIn($email, $password)
+        {
+            $document = $this->getDocument();
+
+            $document->fillField('Email', $email);
+            $document->fillField('Password', $password);
+
+            $document->pressButton('Login');
+        }
+
+        protected function getRouteName()
+        {
+            return 'sylius_user_security_login';
+        }
+    }

behat/how-to-define-new-suite.rst

@@ -0,0 +1,5 @@
+How to define a new suite?
+==========================
+
+To define a new suite it is needed to create a suite configuration file in ``etc/behat/suites``
+directory based on existing files in there and then register that file in ``etc/behat/suites.yml``.

behat/index.rst

@@ -0,0 +1,12 @@
+Behat guide
+===========
+
+.. toctree::
+    :hidden:
+
+    how-to-add-new-context
+    how-to-add-new-page
+    how-to-define-new-suite
+    introduction-to-containers-and-scopes
+
+.. include:: /behat/map.rst.inc

behat/introduction-to-containers-and-scopes.rst

@@ -0,0 +1,34 @@
+Introduction to containers and scopes
+=====================================
+
+In order to provide support for defining contexts and pages in Behat container with dependencies from Symfony application
+container, our service definitions may contain some extra features.
+
+There are 3 available containers:
+
+  - ``behat`` (the default one) - the container which holds all Behat services, its extensions services, our contexts,
+    pages and helper services used by them
+
+  - ``symfony`` - the container which holds all the services defined in the application, the services retrieved from this
+    container are isolated between scenarios, belongs to ``scenario`` scope
+
+  - ``symfony_shared`` - the container which holds all the services defined in the application, created only once,
+    the services retrieved from this container are not isolated between scenarios
+
+There is one additional scope, ``scenario``, which ensures, that no service shared through entire Behat execution uses
+the one that is only available in specific scenario. Every service retrieved from ``symfony`` container has this scope.
+
+Usually, most of contexts and pages are defined in ``scenario`` scope as it's the most safe decision. You would need a
+really got reason not to follow this convention.
+
+Right now, you can only inject services from foreign containers into the default containers. To do so, use ``container``
+option within ``argument`` element:
+
+.. code-block:: xml
+
+    <service id="service.id" class="Class">
+        <argument type="service" id="behat.service.id" />
+        <argument type="service" id="another.behat.service.id" container="behat" />
+        <argument type="service" id="symfony.service.id" container="symfony" /> <!-- to use this container, your service must be in scenario scope too -->
+        <argument type="service" id="shared.symfony.service.id" container="symfony_shared" />
+    </service>

behat/map.rst.inc

@@ -0,0 +1,4 @@
+* :doc:`/behat/how-to-add-new-context`
+* :doc:`/behat/how-to-add-new-page`
+* :doc:`/behat/how-to-define-new-suite`
+* :doc:`/behat/introduction-to-containers-and-scopes`

contributing/code/index.rst

@@ -10,5 +10,6 @@ Contributing Code
     bdd
     standards
     conventions
+    behat_guide
     git
     license

index.rst

@@ -73,6 +73,18 @@ Learn about how Sylius integrates with third-party applications.
 
 .. include:: /integrations/map.rst.inc
 
+The Behat Guide
+---------------
+
+Learn how to write clean and reusable features, contexts and pages.
+
+.. toctree::
+   :hidden:
+
+   behat/index
+
+.. include:: /behat/map.rst.inc
+
 Migration Guide
 ---------------