www.aleph1.co.uk Git - yaffs-website/blob - vendor/behat/mink-extension/doc/index.rst

   1 Mink Extension
   2 ==============
   3
   4 You can use Behat to describe anything, that you can describe in business
   5 logic. It’s tools, gui applications, web applications. Most interesting part
   6 is web applications. First, behavioral testing already exists in web world -
   7 it’s called functional or acceptance testing. Almost all popular frameworks
   8 and languages provide functional testing tools. Today we’ll talk about how to
   9 use Behat for functional testing of web applications. `Mink <http://mink.behat.org>`_
  10 is a tool exactly for that and this extension provides integration for it.
  11
  12 Basically, MinkExtension is an integration layer between Behat 3.0+ and Mink 1.4+
  13 and it provides:
  14
  15 * Additional services for Behat (``Mink``, ``Sessions``, ``Drivers``).
  16 * ``Behat\MinkExtension\Context\MinkAwareContext`` which provides ``Mink``
  17   instance for your contexts.
  18 * Base ``Behat\MinkExtension\Context\MinkContext`` context which provides base
  19   step definitions and hooks for your contexts or subcontexts. Or it could be
  20   even used as context on its own.
  21
  22 Installation
  23 ------------
  24
  25 This extension requires:
  26
  27 * Behat 3.0+
  28 * Mink 1.4+
  29
  30 Through Composer
  31 ~~~~~~~~~~~~~~~~
  32
  33 The easiest way to keep your suite updated is to use `Composer <http://getcomposer.org>`_:
  34
  35 1. Install with composer:
  36
  37     .. code-block:: bash
  38
  39         $ composer require --dev behat/mink-extension
  40
  41 2. Activate extension by specifying its class in your ``behat.yml``:
  42
  43     .. code-block:: yaml
  44
  45         # behat.yml
  46         default:
  47           # ...
  48           extensions:
  49             Behat\MinkExtension:
  50               base_url:  'http://example.com'
  51               sessions:
  52                 default:
  53                   goutte: ~
  54
  55 Usage
  56 -----
  57
  58 After installing extension, there would be 6 usage options available for you:
  59
  60 1. Extending ``Behat\MinkExtension\Context\RawMinkContext`` in your feature suite.
  61    This will give you ability to use a preconfigured `Mink` instance altogether with some
  62    convenience methods:
  63
  64    * ``getSession($name = null)``
  65    * ``assertSession($name = null)``
  66
  67    ``RawMinkContext`` doesn't provide any hooks or definitions, so you can inherit from it
  68    in as many contexts as you want - you'll never get ``RedundantStepException``.
  69
  70 2. Extending ``Behat\MinkExtension\Context\MinkContext`` with one of your contexts.
  71    Exactly like the previous option, but also provides lots of predefined step definitions out
  72    of the box. As this context provides step definitions and hooks, you can use it **only once**
  73    inside your feature context tree.
  74
  75     .. code-block:: php
  76
  77         <?php
  78
  79         use Behat\MinkExtension\Context\MinkContext;
  80
  81         class FeatureContext extends MinkContext
  82         {
  83             /**
  84              * @Then /^I wait for the suggestion box to appear$/
  85              */
  86             public function iWaitForTheSuggestionBoxToAppear()
  87             {
  88                 $this->getSession()->wait(5000, "$('.suggestions-results').children().length > 0");
  89             }
  90         }
  91
  92     .. warning::
  93
  94         Keep in mind, that you can not have multiple step definitions with the same regex.
  95         It will cause a ``RedundantException``. So, you can inherit from ``MinkContext``
  96         only with one of your context/subcontext classes.
  97
  98 3. Adding ``Behat\MinkExtension\Context\MinkContext`` as context in your suite.
  99    Exactly like previous option, but gives you the ability to keep your main context
 100    class clean.
 101
 102     .. code-block:: yaml
 103
 104         default:
 105           suites:
 106             my_suite:
 107               contexts:
 108                 - FeatureContext
 109                 - Behat\MinkExtension\Context\MinkContext
 110
 111     .. note::
 112
 113         Keep in mind, that you can not have multiple step definitions with the same regex.
 114         It will cause a ``RedundantException``. So, you can inherit from ``MinkContext``
 115         only with one of your context/subcontext classes.
 116
 117 4. Implementing ``Behat\MinkExtension\Context\MinkAwareContext`` with your context.
 118
 119 There are common things between these methods. In each of those, the target context will implement
 120 ``setMink(Mink $mink)`` and ``setMinkParameters(array $parameters)`` methods. Those methods would
 121 be automatically called **immediately after** each context creation before each scenario. And
 122 this ``$mink`` instance will be preconfigured based on the settings you've provided in your
 123 ``behat.yml``.
 124
 125 Configuration
 126 -------------
 127
 128 MinkExtension comes with a flexible configuration system, that gives you
 129 the ability to configure Mink inside Behat to fulfil all your needs.
 130
 131 Sessions
 132 --------
 133
 134 You can register as many Mink sessions as you want. For each session, you
 135 will need to choose the driver you want to use.
 136
 137 .. code-block:: yaml
 138
 139     default:
 140         extensions:
 141             Behat\MinkExtension:
 142                 sessions:
 143                     first_session:
 144                         selenium2: ~
 145                     second_session:
 146                         goutte: ~
 147                     third_session:
 148                         selenium2: ~
 149
 150 MinkExtension will set the default Mink session for each scenario based on
 151 the configuration settings ``default_session`` and ``javascript_session``
 152 and on scenario tags:
 153
 154 * A scenario tagged with ``@mink:foo`` will use ``foo`` as default session;
 155 * A scenario tagged with ``@javascript`` will use the javascript session as default session;
 156 * Other scenarios will use the default session.
 157
 158 The default session and the default javascript session can also be configured for
 159 each suite:
 160
 161 .. code-block:: yaml
 162
 163     default:
 164         suites:
 165             first:
 166                 mink_session: foo
 167                 mink_javascript_session: sahi
 168
 169 If it is not configured explicitly, the javascript session is set to the first
 170 session using a javascript driver in the order of the configuration (it would
 171 be ``first_session`` in the example above as ``selenium2`` supports Javascript).
 172 If it is not configured explicitly, the default session is set to the first
 173 session using a non-javascript driver if any, or to the first javascript session
 174 otherwise (it would be ``second_session`` above as ``goutte`` does not support
 175 javascript).
 176
 177 Drivers
 178 ~~~~~~~
 179
 180 First of all, there are drivers enabling configuration. MinkExtension comes
 181 with support for 6 drivers out of the box:
 182
 183 * ``GoutteDriver`` - headless driver without JavaScript support. In order to use
 184   it, modify your ``behat.yml`` profile:
 185
 186     .. code-block:: yaml
 187
 188         default:
 189             extensions:
 190                 Behat\MinkExtension:
 191                     sessions:
 192                         my_session:
 193                             goutte: ~
 194
 195   .. Tips : HTTPS and self-signed certificate
 196   In case you use Behat/Mink/Goutte to test your application, and want to test an
 197   application secured with HTTPS, but with a self-signed certificate, you can use
 198   the following parameters to avoid the validation error triggered by Guzzle:
 199
 200   * For ``Guzzle 4`` or later:
 201
 202       .. code-block:: yaml
 203
 204           default:
 205               extensions:
 206                   Behat\MinkExtension:
 207                       sessions:
 208                           my_session:
 209                               goutte:
 210                                   guzzle_parameters:
 211                                       verify: false
 212
 213   * For ``Guzzle 3`` or earlier:
 214
 215       .. code-block:: yaml
 216
 217           default:
 218               extensions:
 219                   Behat\MinkExtension:
 220                       sessions:
 221                           my_session:
 222                               goutte:
 223                                   guzzle_parameters:
 224                                       ssl.certificate_authority: false
 225
 226 * ``Selenium2Driver`` - javascript driver. In order to use it, modify your
 227   ``behat.yml`` profile:
 228
 229     .. code-block:: yaml
 230
 231         default:
 232             extensions:
 233                 Behat\MinkExtension:
 234                     sessions:
 235                         my_session:
 236                             selenium2: ~
 237
 238 * ``SauceLabsDriver`` - special flavor of the Selenium2Driver configured to use the
 239   selenium2 hosted installation of saucelabs.com. In order to use it, modify your
 240   ``behat.yml`` profile:
 241
 242     .. code-block:: yaml
 243
 244         default:
 245             extensions:
 246                 Behat\MinkExtension:
 247                     sessions:
 248                         my_session:
 249                             sauce_labs: ~
 250
 251 * ``BrowserStackDriver`` - special flavor of the Selenium2Driver configured to use the
 252   selenium2 hosted installation of browserstack.com. In order to use it, modify your
 253   ``behat.yml`` profile:
 254
 255     .. code-block:: yaml
 256
 257         default:
 258             extensions:
 259                 Behat\MinkExtension:
 260                     sessions:
 261                         my_session:
 262                             browser_stack: ~
 263
 264 * ``SeleniumDriver`` - javascript driver. In order to use it, modify your ``behat.yml``
 265   profile:
 266
 267     .. code-block:: yaml
 268
 269         default:
 270             extensions:
 271                 Behat\MinkExtension:
 272                     sessions:
 273                         my_session:
 274                             selenium: ~
 275
 276 * ``SahiDriver`` - javascript driver. In order to use it, modify your ``behat.yml``
 277   profile:
 278
 279     .. code-block:: yaml
 280
 281         default:
 282             extensions:
 283                 Behat\MinkExtension:
 284                     sessions:
 285                         my_session:
 286                             sahi: ~
 287
 288 * ``ZombieDriver`` - zombie.js javascript headless driver. In order to use it, modify
 289   your ``behat.yml`` profile:
 290
 291     .. code-block:: yaml
 292
 293         default:
 294             extensions:
 295                 Behat\MinkExtension:
 296                     sessions:
 297                         default:
 298                             zombie:
 299                                 # Specify the path to the node_modules directory.
 300                                 node_modules_path: /usr/local/lib/node_modules/
 301
 302 .. note::
 303
 304     The phar version of Mink comes bundled with all 5 drivers and you don't need to do
 305     anything except enabling them in order to use them.
 306
 307     But if you're using Composer, you need to install drivers that you need first:
 308
 309     - GoutteDriver - ``behat/mink-goutte-driver``
 310     - SeleniumDriver - ``behat/mink-selenium-driver``
 311     - Selenium2Driver (also used for Saucelabs) - ``behat/mink-selenium2-driver``
 312     - SahiDriver - ``behat/mink-sahi-driver``
 313     - ZombieDriver - ``behat/mink-zombie-driver``
 314
 315 .. note::
 316
 317     All drivers share the same API, which means that you could use multiple drivers
 318     for the same suite - which one fits your needs for concrete scenarios. Don't
 319     try to stick to a single driver as there's simply no universal solution - every
 320     driver has its pros and cons.
 321
 322 Additional Parameters
 323 ~~~~~~~~~~~~~~~~~~~~~
 324
 325 There's other useful parameters, that you can use to configure your suite:
 326
 327 * ``base_url`` - if you're using relative paths in your ``*.feature`` files
 328   (and you should), then this option will define which url to use as a basename
 329   for them.
 330 * ``files_path`` - there's a special step definition for file upload inputs
 331   usage. You can use relative paths in those steps. ``files_path`` defines
 332   base path in which Mink should search those relative files.
 333 * ``show_cmd`` - there's a special definition in MinkExtension, that saves
 334   currently opened page into temporary file and opens it with some browser
 335   utility (for debugging). This option defines command to be used for opening.
 336   For example: ``show_cmd: 'firefox %s'``.
 337 * ``show_tmp_dir`` - the temporary folder used to show the opened page (defaults
 338   to the system temp dir)
 339 * ``show_auto`` - Whether the opened page should be shown automatically when
 340   a step fails.
 341 * ``browser_name`` - meta-option, that defines which browser to use for Sahi,
 342   Selenium and Selenium2 drivers.
 343 * ``default_session`` - defines default session (driver) to be used for all
 344   untagged scenarios. Could be any enabled session name.
 345 * ``javascript_session`` - defines javascript session (driver) (the one, which
 346   will be used for ``@javascript`` tagged scenarios). Could be any enabled session
 347   name.
 348 * ``mink_loader`` - path to a file loaded to make Mink available (useful when
 349   using the PHAR archive for Mink, useless when using Composer)