Merge pull request #49 from aik099/driver-selection-support

Mink driver selection ability in configuration

Author: Alexander Obuhovich

composer.json

@@ -14,7 +14,7 @@
 
 	"require": {
 		"php": ">=5.3.2",
-		"behat/mink": "~1.6",
+		"behat/mink": "~1.6@dev",
 		"behat/mink-selenium2-driver": "~1.2",
 		"symfony/event-dispatcher": "~2.4",
 		"pimple/pimple": "~2.0|~3.0",

composer.lock

@@ -21,7 +21,7 @@ configuration) in that test case class.
 
 .. literalinclude:: examples/configuration/config_via_browsers_property.php
    :linenos:
-   :emphasize-lines: 8,9,15
+   :emphasize-lines: 8,9,16
 
 .. note:: When several browser configurations are specified in ``$browsers`` array, then each test
           in a test case will be executed against each of browser configurations.
@@ -35,27 +35,38 @@ option (line 14) to the browser configuration.
 
 .. literalinclude:: examples/configuration/per_test_case_browser_config.php
        :linenos:
-       :emphasize-lines: 14
+       :emphasize-lines: 15
+
+Selecting the Mink Driver
+^^^^^^^^^^^^^^^^^^^^^^^^^
+With the help of ``driver`` and ``driverOptions`` browser configuration settings (since v2.1.0) it's possible to
+specify which `Mink`_ driver to use. This file demonstrates how to use each driver:
+
+.. literalinclude:: examples/configuration/driver_showcase.php
+       :linenos:
+       :emphasize-lines: 10,20,32,40
 
 Configuration Options
 ^^^^^^^^^^^^^^^^^^^^^
 Each browser configuration consists of the following settings (all optional):
 
-=======================  =================================================================================================
+=======================  ==================================================================================================
 Name                     Description
-=======================  =================================================================================================
-``host``                 host, where Selenium Server is located (defaults to ``localhost``)
-``port``                 port, on which Selenium Server is listening for incoming connections (defaults to ``4444``)
-``timeout``              connection timeout of the server in seconds (defaults to ``60``)
+=======================  ==================================================================================================
+``driver``               Mink driver name (defaults to ``selenium2``, since v2.1.0)
+``driverOptions``        Mink driver specific options (since v2.1.0)
+``host``                 host, where driver's server is located (defaults to ``localhost``)
+``port``                 port, on which driver's server is listening for incoming connections (determined by driver)
+``timeout``              connection timeout of the server in seconds ('selenium2' driver only, defaults to ``60``)
 ``browserName``          name of browser to use (e.g. ``firefox``, ``chrome``, etc., defaults to ``firefox``)
-``desiredCapabilities``  parameters, that specify additional browser configuration (e.g. browser version, platform, etc.),
-                         that will be used by Selenium server
+``desiredCapabilities``  parameters, that allow to fine-tune browser and other 'selenium2' driver options (e.g. 'tags',
+                         'project', 'os', 'version')
 ``baseUrl``              base url of website, that is tested
 ``sessionStrategy``      used session strategy (defaults to ``isolated``)
 ``type``                 type of configuration (defaults to ``default``, but can also be ``saucelabs`` or ``browserstack``)
-``api_username``         API username of used service (applicable to any but ``default`` configuration type)
-``api_key``              API key of used service (applicable to any but ``default`` configuration type)
-=======================  =================================================================================================
+``apiUsername``          API username of used service (applicable to 'saucelabs' and 'browserstack' browser configurations)
+``apiKey``               API key of used service (applicable to 'saucelabs' and 'browserstack' browser configurations)
+=======================  ==================================================================================================
 
 There are also corresponding setters (e.g. ``setHost``) and getters (e.g. ``getHost``) for each of mentioned
 above settings, that allow to individually change them from ``setUp`` method before test has started.

docs/configuration.rst

@@ -9,6 +9,7 @@ public function getBrowserAliases()
     {
         return array(
             'example_alias' => array(
+                'driver' => 'selenium2',
                 'host' => 'localhost',
                 'port' => 4444,
                 'browserName' => 'firefox',

docs/examples/browser_aliases.php

@@ -7,12 +7,14 @@ class PerTestCaseBrowserConfigTest extends BrowserTestCase
 
     public static $browsers = array(
         array(
+            'driver' => 'selenium2',
             'host' => 'localhost',
             'port' => 4444,
             'browserName' => 'firefox',
             'baseUrl' => 'http://www.google.com',
         ),
         array(
+            'driver' => 'selenium2',
             'host' => 'localhost',
             'port' => 4444,
             'browserName' => 'chrome',

docs/examples/configuration/config_via_browsers_property.php

@@ -16,8 +16,8 @@ protected function setUp()
         $browser = $this->createBrowserConfiguration(array(
             // required
             'type' => 'saucelabs',
-            'api_username' => 'sauce_username',
-            'api_key' => 'sauce_api_key',
+            'apiUsername' => 'sauce_username',
+            'apiKey' => 'sauce_api_key',
             // optional options goes here
         ));
 

docs/examples/configuration/config_via_setup_method.php

@@ -0,0 +1,53 @@
+<?php
+
+use aik099\PHPUnit\BrowserTestCase;
+
+class DriverShowCaseTest extends BrowserTestCase
+{
+
+    public static $browsers = array(
+        array(
+            'driver' => 'goutte',
+
+            // Defaults for this driver.
+            'driverOptions' => array(
+                'server_parameters' => array(),
+                'guzzle_parameters' => array(),
+            ),
+
+        ),
+        array(
+            'driver' => 'sahi',
+
+            // Defaults for this driver.
+            'port' => 9999,
+            'driverOptions' => array(
+                'sid' => null,
+                'limit' => 600,
+                'browser' => null,
+            ),
+        ),
+
+        array(
+            'driver' => 'selenium2',
+
+            // Defaults for this driver.
+            'port' => 4444,
+            'driverOptions' => array(),
+        ),
+
+        array(
+            'driver' => 'zombie',
+
+            // Defaults for this driver.
+            'port' => 8124,
+            'driverOptions' => array(
+                'node_bin' => 'node',
+                'server_path' => null,
+                'threshold' => 2000000,
+                'node_modules_path' => '',
+            ),
+        ),
+    );
+
+}

docs/examples/configuration/driver_showcase.php

@@ -7,6 +7,7 @@ class CommonBrowserConfigTest extends BrowserTestCase
 
     public static $browsers = array(
         array(
+            'driver' => 'selenium2',
             'host' => 'localhost',
             'port' => 4444,
             'browserName' => 'firefox',

docs/examples/configuration/per_test_case_browser_config.php

@@ -9,8 +9,8 @@ class BrowserConfigExampleTest extends BrowserTestCase
         // Sauce Labs browser configuration.
         array(
             'type' => 'saucelabs',
-            'api_username' => '...',
-            'api_key' => '...',
+            'apiUsername' => '...',
+            'apiKey' => '...',
             'browserName' => 'firefox',
             'baseUrl' => 'http://www.google.com',
         ),
@@ -24,6 +24,7 @@ class BrowserConfigExampleTest extends BrowserTestCase
         ),
         // Regular browser configuration.
         array(
+            'driver' => 'selenium2',
             'host' => 'localhost',
             'port' => 4444,
             'browserName' => 'chrome',

docs/examples/getting-started/cloud_selenium_configs.php

@@ -7,6 +7,7 @@ class GeneralTest extends BrowserTestCase
 
     public static $browsers = array(
         array(
+            'driver' => 'selenium2',
             'host' => 'localhost',
             'port' => 4444,
             'browserName' => 'firefox',