From 914e2af9df03413ef8dcdfdd0245c9aec6fc6616 Mon Sep 17 00:00:00 2001 From: Kamil Kokot Date: Fri, 12 Feb 2016 11:40:04 +0100 Subject: [PATCH] Initial documentation for Behat w/ service support --- behat/how-to-add-new-context.rst | 27 ++++++++++++ behat/how-to-add-new-page.rst | 43 +++++++++++++++++++ behat/how-to-define-new-suite.rst | 5 +++ behat/index.rst | 12 ++++++ .../introduction-to-containers-and-scopes.rst | 34 +++++++++++++++ behat/map.rst.inc | 4 ++ contributing/code/index.rst | 1 + index.rst | 12 ++++++ 8 files changed, 138 insertions(+) create mode 100644 behat/how-to-add-new-context.rst create mode 100644 behat/how-to-add-new-page.rst create mode 100644 behat/how-to-define-new-suite.rst create mode 100644 behat/index.rst create mode 100644 behat/introduction-to-containers-and-scopes.rst create mode 100644 behat/map.rst.inc diff --git a/behat/how-to-add-new-context.rst b/behat/how-to-add-new-context.rst new file mode 100644 index 0000000..1898f31 --- /dev/null +++ b/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 + + + + + +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``. diff --git a/behat/how-to-add-new-page.rst b/behat/how-to-add-new-page.rst new file mode 100644 index 0000000..c9d9096 --- /dev/null +++ b/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 + + + +.. 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'; + } + } diff --git a/behat/how-to-define-new-suite.rst b/behat/how-to-define-new-suite.rst new file mode 100644 index 0000000..7613264 --- /dev/null +++ b/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``. diff --git a/behat/index.rst b/behat/index.rst new file mode 100644 index 0000000..d67233e --- /dev/null +++ b/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 diff --git a/behat/introduction-to-containers-and-scopes.rst b/behat/introduction-to-containers-and-scopes.rst new file mode 100644 index 0000000..201192e --- /dev/null +++ b/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 + + + + + + + diff --git a/behat/map.rst.inc b/behat/map.rst.inc new file mode 100644 index 0000000..e432efa --- /dev/null +++ b/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` diff --git a/contributing/code/index.rst b/contributing/code/index.rst index 45ff956..96d12c8 100644 --- a/contributing/code/index.rst +++ b/contributing/code/index.rst @@ -10,5 +10,6 @@ Contributing Code bdd standards conventions + behat_guide git license diff --git a/index.rst b/index.rst index 9ab8b43..008b079 100644 --- a/index.rst +++ b/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 ---------------