index.rst 12 KB

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