Updated the doc

doc/index.rst

@@ -9,48 +9,24 @@ and languages provide functional testing tools. Today we’ll talk about how to
 use Behat for functional testing of web applications. `Mink <http://mink.behat.org>`_
 is a tool exactly for that and this extension provides integration for it.
 
-Basically, MinkExtension is an integration layer between Behat 2.4+ and Mink 1.4+
+Basically, MinkExtension is an integration layer between Behat 3.0+ and Mink 1.4+
 and it provides:
 
 * Additional services for Behat (``Mink``, ``Sessions``, ``Drivers``).
 * ``Behat\MinkExtension\Context\MinkAwareContext`` which provides ``Mink``
-  instance for your contexts or subcontexts.
+  instance for your contexts.
 * Base ``Behat\MinkExtension\Context\MinkContext`` context which provides base
   step definitions and hooks for your contexts or subcontexts. Or it could be
-  even used as subcontext on its own.
+  even used as context on its own.
 
 Installation
 ------------
 
 This extension requires:
 
-* Behat 2.4+
+* Behat 3.0+
 * Mink 1.4+
 
-Through PHAR
-~~~~~~~~~~~~
-
-You should first download 3 phar archives:
-
-* `behat.phar <http://behat.org/downloads/behat.phar>`_ - Behat itself
-* `mink.phar <http://behat.org/downloads/mink.phar>`_ - Mink framework
-* `mink_extension.phar <http://behat.org/downloads/mink_extension.phar>`_
-  - integration extension
-
-After downloading and placing them into project directory, you need to
-activate ``mink_extension.phar`` in your ``behat.yml``:
-
-.. code-block:: yaml
-
-    # behat.yml
-    default:
-      # ...
-      extensions:
-        mink_extension.phar:
-          mink_loader: 'mink-VERSION.phar'
-          base_url:    'http://example.com'
-          goutte:      ~
-
 Through Composer
 ~~~~~~~~~~~~~~~~
 
@@ -61,10 +37,10 @@ The easiest way to keep your suite updated is to use `Composer <http://getcompos
     .. code-block:: js
 
         {
-            "require": {
+            "require-dev": {
                 ...
 
-                "behat/mink-extension": "*"
+                "behat/mink-extension": "~2.0@dev"
             }
         }
 
@@ -72,8 +48,7 @@ The easiest way to keep your suite updated is to use `Composer <http://getcompos
 
     .. code-block:: bash
 
-        $ curl http://getcomposer.org/installer | php
+        $ composer update behat/mink-extension
-        $ php composer.phar install
 
 3. Activate extension by specifying its class in your ``behat.yml``:
 
@@ -92,23 +67,15 @@ Usage
 
 After installing extension, there would be 6 usage options available for you:
 
-1. Writing features with bundled steps only. In this case, you don't need to create
+1. Extending ``Behat\MinkExtension\Context\RawMinkContext`` in your feature suite.
-   ``bootstrap/`` folder or custom ``FeatureContext`` class - Behat will use default
-   ``MinkContext`` by default. To see all available steps, run:
-
-    .. code-block:: bash
-
-        $ bin/behat -di
-
-2. Subcontexting/extending ``Behat\MinkExtension\Context\RawMinkContext`` in your feature suite.
    This will give you ability to use preconfigured `Mink` instance altogether with some
    convenience methods:
    * ``getSession($name = null)``
    * ``assertSession($name = null)``
    ``RawMinkContext`` doesn't provide any hooks or definitions, so you can inherit from it
-   in as many subcontexts as you want - you'll never get ``RedundantStepException``.
+   in as many contexts as you want - you'll never get ``RedundantStepException``.
 
-3. Extending ``Behat\MinkExtension\Context\MinkContext`` with one of your contexts.
+2. Extending ``Behat\MinkExtension\Context\MinkContext`` with one of your contexts.
    Exactly like previous option, but also provides lot of predefined step definitions out
    of the box. As this context provides step definitions and hooks, you can use it **only once**
    inside your feature context tree.
@@ -136,24 +103,18 @@ After installing extension, there would be 6 usage options available for you:
         It will cause ``RedundantException``. So, you can inherit from ``MinkContext``
         only with one of your context/subcontext classes.
 
-4. Subcontexting ``Behat\MinkExtension\Context\MinkContext`` in your main context.
+3. Adding ``Behat\MinkExtension\Context\MinkContext`` as context in your suite.
    Exactly like previous option, but gives you ability to keep your main context
    class clean.
 
-    .. code-block:: php
+    .. code-block:: yaml
 
-        <?php
+        default:
-
+          suites:
-        use Behat\MinkExtension\Context\RawMinkContext;
+            my_suite:
-        use Behat\MinkExtension\Context\MinkContext;
+              contexts:
-
+                - FeatureContext
-        class FeatureContext extends RawMinkContext
+                - Behat\MinkExtension\Context\MinkContext
-        {
-            public function __construct(array $parameters)
-            {
-                $this->useContext('mink', new MinkContext);
-            }
-        }
 
     .. note::
 
@@ -161,17 +122,10 @@ After installing extension, there would be 6 usage options available for you:
         It will cause ``RedundantException``. So, you can inherit from ``MinkContext``
         only with one of your context/subcontext classes.
 
-    .. note::
+4. If you're on the php 5.4+, you can simply use ``Behat\MinkExtension\Context\MinkDictionary``
-
+   trait inside your ``FeatureContext``. This trait will provide all the needed methods,
-        Here, we are also extending our main context from ``RawMinkContext`` class.
+   hooks and definitions for you to start. You can use this trait **only once** inside
-        This class doesn't provide any definitions or hooks - just helper methods
+   your feature context tree, and it cannot be used at the same time than the ``MinkContext``.
-        for you to interact with Mink. It means, that you could extend ``RawMinkContext``
-        with as many context classes in your suite as you want.
-
-5. If you're on the php 5.4+, you can simply use ``Behat\MinkExtension\Context\MinkDictionary``
-   trait inside your ``FeatureContext`` or any of its subcontexts. This trait will provide
-   all the needed methods, hooks and definitions for you to start. You can use this trait **only
-   once** inside your feature context tree.
 
     .. code-block:: php
 
@@ -193,10 +147,9 @@ After installing extension, there would be 6 usage options available for you:
             }
         }
 
-6. Implementing ``Behat\MinkExtension\Context\MinkAwareContext`` with your context or its
+5. Implementing ``Behat\MinkExtension\Context\MinkAwareContext`` with your context.
-   subcontexts.
 
-There's common things between last 5 methods. In each of those, target context will implement
+There's common things these methods. In each of those, target context will implement
 ``setMink(Mink $mink)`` and ``setMinkParameters(array $parameters)`` methods. Those methods would
 be automatically called **immediately after** each context creation before each scenario. And
 this ``$mink`` instance will be preconfigured based on the settings you've provided in your
@@ -212,7 +165,7 @@ Drivers
 ~~~~~~~
 
 First of all, there's drivers enabling configuration. MinkExtension comes
-with support for 5 drivers out of the box:
+with support for 6 drivers out of the box:
 
 * ``GoutteDriver`` - default headless driver. It is used by default, which means
   that if you didn't changed ``default_session`` (another parameter) - you should
@@ -252,6 +205,20 @@ the following parameters to avoid the validation error triggered by Guzzle :
                 Behat\MinkExtension\Extension:
                     selenium2: ~
 
+* ``SaucelabsDriver`` - special flavor of the Selenium2Driver configured to use the
+  selenium2 hosted installation of saucelabs.com. You could use it by setting it in
+  ``javascript_session`` to ``saucelabs`` and by marking scenarios as ``@javascript``
+  or simply by marking scenarios with ``mink:saucelabs`` (no need to switch
+  ``javascript_session`` in this case). In order to enable it, modify your ``behat.yml``
+  profile:
+
+    .. code-block:: yaml
+
+        default:
+            extensions:
+                Behat\MinkExtension\Extension:
+                    saucelabs: ~
+
 * ``SeleniumDriver`` - another javascript driver. You could use it by setting it
   in ``javascript_session`` to ``selenium`` and by marking scenarios as ``@javascript``
   or simply by marking scenarios with ``mink:selenium`` (no need to switch
@@ -300,7 +267,7 @@ the following parameters to avoid the validation error triggered by Guzzle :
 
     - GoutteDriver - ``behat/mink-goutte-driver``
     - SeleniumDriver - ``behat/mink-selenium-driver``
-    - WebDriver - ``behat/mink-selenium2-driver``
+    - Selenium2Driver (also used for Saucelabs) - ``behat/mink-selenium2-driver``
     - SahiDriver - ``behat/mink-sahi-driver``
     - ZombieDriver - ``behat/mink-zombie-driver``
 
@@ -326,10 +293,16 @@ There's other useful parameters, that you can use to configure your suite:
   currently opened page into temporary file and opens it with some browser
   utility (for debugging). This option defines command to be used for opening.
   For example: ``show_cmd: 'firefox %s'``.
-* ``browser_name`` - metaoption, that defines which browser to use for Sahi,
+* ``show_tmp_dir`` - the temporary folder used to show the opened page (defaults
+  to the system temp dir)
+* ``show_auto`` - Whether the opened page should be shown automatically when
+  a step fails.
+* ``browser_name`` - meta-option, that defines which browser to use for Sahi,
   Selenium and Selenium2 drivers.
 * ``default_session`` - defines default session (driver) to be used for all
-  untagged scenarios. Could be any enabled driver name.
+  untagged scenarios. Could be any enabled driver name. Defaults to ``goutte``
 * ``javascript_session`` - defines javascript session (driver) (the one, which
   will be used for ``@javascript`` tagged scenarios). Could be any enabled driver
-  name.
+  name. Defaults to ``selenium2``
+* ``mink_loader`` - path to a file loaded to make Mink available (useful when
+  using the PHAR archive for Mink, useless when using Composer)