f5bd8e3d1f
* Mark Goutte, Selenium, Sahi and Zombie driver/support as abandoned This marks the four drivers as abandoned where the driver implementations are no longer maintained. * Correctly indent notes so they don't break the enumeration list * Indent a few more notes that are part of a numerated list
355 lines
12 KiB
Markdown
355 lines
12 KiB
Markdown
# Mink Extension
|
|
|
|
You can use Behat to describe anything, that you can describe in business
|
|
logic. It's tools, gui applications, web applications. The most interesting part
|
|
is web applications. First, behavioral testing already exists in the web world -
|
|
it's called functional or acceptance testing. Almost all popular frameworks
|
|
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 3.0+ and Mink 1.4+
|
|
and it provides:
|
|
|
|
* Additional services for Behat (`Mink`, `Sessions`, `Drivers`).
|
|
* `Behat\MinkExtension\Context\MinkAwareContext` which provides a `Mink`
|
|
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 context on its own.
|
|
|
|
## Installation
|
|
|
|
This extension requires:
|
|
|
|
* Behat 3.0+
|
|
* Mink 1.4+
|
|
|
|
### Through Composer
|
|
|
|
The easiest way to keep your suite updated is to use [Composer](http://getcomposer.org):
|
|
|
|
1. Install with composer:
|
|
|
|
```bash
|
|
$ composer require --dev behat/mink-extension
|
|
```
|
|
|
|
2. Activate the extension by specifying its class in your `behat.yml`:
|
|
|
|
```yaml
|
|
# behat.yml
|
|
default:
|
|
# ...
|
|
extensions:
|
|
Behat\MinkExtension:
|
|
base_url: 'http://example.com'
|
|
sessions:
|
|
default:
|
|
goutte: ~
|
|
```
|
|
|
|
## Usage
|
|
|
|
After installing the extension, there are 4 usage options available:
|
|
|
|
1. Extending `Behat\MinkExtension\Context\RawMinkContext` in your feature suite.
|
|
This will give you the ability to use a preconfigured `Mink` instance 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 contexts as you want - you'll never get `RedundantStepException`.
|
|
|
|
2. Extending `Behat\MinkExtension\Context\MinkContext` with one of your contexts.
|
|
Exactly like the previous option, but also provides lots 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.
|
|
|
|
```php
|
|
<?php
|
|
|
|
use Behat\MinkExtension\Context\MinkContext;
|
|
|
|
class FeatureContext extends MinkContext
|
|
{
|
|
/**
|
|
* @Then /^I wait for the suggestion box to appear$/
|
|
*/
|
|
public function iWaitForTheSuggestionBoxToAppear()
|
|
{
|
|
$this->getSession()->wait(5000, "$('.suggestions-results').children().length > 0");
|
|
}
|
|
}
|
|
```
|
|
|
|
> [!NOTE]
|
|
> Keep in mind, that you can not have multiple step definitions with the same regex.
|
|
> It will cause a `RedundantException`. So, you can inherit from `MinkContext`
|
|
> only with one of your context/subcontext classes.
|
|
|
|
3. Adding `Behat\MinkExtension\Context\MinkContext` as a context in your suite.
|
|
Exactly like the previous option, but gives you the ability to keep your main context
|
|
class clean.
|
|
|
|
```yaml
|
|
default:
|
|
suites:
|
|
my_suite:
|
|
contexts:
|
|
- FeatureContext
|
|
- Behat\MinkExtension\Context\MinkContext
|
|
```
|
|
|
|
> [!NOTE]
|
|
> Keep in mind, that you can not have multiple step definitions with the same regex.
|
|
> It will cause a `RedundantException`. So, you can inherit from `MinkContext`
|
|
> only with one of your context/subcontext classes.
|
|
|
|
4. Implementing `Behat\MinkExtension\Context\MinkAwareContext` with your context.
|
|
|
|
There are common things between these methods. In each of those, the 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
|
|
`behat.yml`.
|
|
|
|
## Configuration
|
|
|
|
MinkExtension comes with a flexible configuration system, that gives you
|
|
the ability to configure Mink inside Behat to fulfil all your needs.
|
|
|
|
### Sessions
|
|
|
|
You can register as many Mink sessions as you want. For each session, you
|
|
will need to choose the driver you want to use.
|
|
|
|
```yaml
|
|
default:
|
|
extensions:
|
|
Behat\MinkExtension:
|
|
sessions:
|
|
first_session:
|
|
selenium2: ~
|
|
second_session:
|
|
goutte: ~
|
|
third_session:
|
|
selenium2: ~
|
|
```
|
|
|
|
MinkExtension will set the default Mink session for each scenario based on
|
|
the configuration settings `default_session` and `javascript_session`
|
|
and on scenario tags:
|
|
|
|
* A scenario tagged with `@mink:foo` will use `foo` as its default session;
|
|
* A scenario tagged with `@javascript` will use the `javascript` session as its default session;
|
|
* Other scenarios will use the default session.
|
|
|
|
The default session and the default `javascript` session can also be configured for
|
|
each suite:
|
|
|
|
```yaml
|
|
default:
|
|
suites:
|
|
first:
|
|
mink_session: foo
|
|
mink_javascript_session: sahi
|
|
```
|
|
|
|
If it is not configured explicitly, the `javascript` session is set to the first
|
|
session using a javascript driver in the order of the configuration (it would
|
|
be `first_session` in the example above as `selenium2` supports Javascript).
|
|
If it is not configured explicitly, the default session is set to the first
|
|
session using a non-javascript driver if any, or to the first javascript session
|
|
otherwise (it would be `second_session` above as `goutte` does not support
|
|
javascript).
|
|
|
|
### Drivers
|
|
|
|
First of all, there are drivers enabling configuration. MinkExtension comes
|
|
with support for 7 drivers out of the box:
|
|
|
|
* `GoutteDriver` - headless driver without JavaScript support. In order to use
|
|
it, modify your `behat.yml` profile:
|
|
|
|
> [!IMPORTANT]
|
|
> Support for this driver has been deprecated, since the driver package has been abandoned.
|
|
> It will be removed in the next major version of this extension.
|
|
|
|
```yaml
|
|
default:
|
|
extensions:
|
|
Behat\MinkExtension:
|
|
sessions:
|
|
my_session:
|
|
goutte: ~
|
|
```
|
|
|
|
**Tips: HTTPS and self-signed certificate**
|
|
|
|
If you use Behat/Mink/Goutte to test your application, and want to test an
|
|
application secured with HTTPS, but with a self-signed certificate, you can use
|
|
the following parameters to avoid the validation error triggered by Guzzle:
|
|
|
|
* For `Guzzle 4` or later:
|
|
|
|
```yaml
|
|
default:
|
|
extensions:
|
|
Behat\MinkExtension:
|
|
sessions:
|
|
my_session:
|
|
goutte:
|
|
guzzle_parameters:
|
|
verify: false
|
|
```
|
|
|
|
* For `Guzzle 3` or earlier:
|
|
|
|
```yaml
|
|
default:
|
|
extensions:
|
|
Behat\MinkExtension:
|
|
sessions:
|
|
my_session:
|
|
goutte:
|
|
guzzle_parameters:
|
|
ssl.certificate_authority: false
|
|
```
|
|
|
|
* `Selenium2Driver` - javascript driver. In order to use it, modify your
|
|
`behat.yml` profile:
|
|
|
|
```yaml
|
|
default:
|
|
extensions:
|
|
Behat\MinkExtension:
|
|
sessions:
|
|
my_session:
|
|
selenium2: ~
|
|
```
|
|
|
|
* `SauceLabsDriver` - special flavor of the Selenium2Driver configured to use the
|
|
selenium2 hosted installation of saucelabs.com. In order to use it, modify your
|
|
`behat.yml` profile:
|
|
|
|
```yaml
|
|
default:
|
|
extensions:
|
|
Behat\MinkExtension:
|
|
sessions:
|
|
my_session:
|
|
sauce_labs: ~
|
|
```
|
|
|
|
* `BrowserStackDriver` - special flavor of the Selenium2Driver configured to use the
|
|
selenium2 hosted installation of browserstack.com. In order to use it, modify your
|
|
`behat.yml` profile:
|
|
|
|
```yaml
|
|
default:
|
|
extensions:
|
|
Behat\MinkExtension:
|
|
sessions:
|
|
my_session:
|
|
browser_stack: ~
|
|
```
|
|
|
|
* `SeleniumDriver` - javascript driver. In order to use it, modify your `behat.yml`
|
|
profile:
|
|
|
|
> [!IMPORTANT]
|
|
> Support for this driver has been deprecated, since the driver package has been abandoned.
|
|
> It will be removed in the next major version of this extension.
|
|
|
|
```yaml
|
|
default:
|
|
extensions:
|
|
Behat\MinkExtension:
|
|
sessions:
|
|
my_session:
|
|
selenium: ~
|
|
```
|
|
|
|
* `SahiDriver` - javascript driver. In order to use it, modify your `behat.yml`
|
|
profile:
|
|
|
|
> [!IMPORTANT]
|
|
> Support for this driver has been deprecated, since the driver package has been abandoned.
|
|
> It will be removed in the next major version of this extension.
|
|
|
|
```yaml
|
|
default:
|
|
extensions:
|
|
Behat\MinkExtension:
|
|
sessions:
|
|
my_session:
|
|
sahi: ~
|
|
```
|
|
|
|
* `ZombieDriver` - zombie.js javascript headless driver. In order to use it, modify
|
|
your `behat.yml` profile:
|
|
|
|
> [!IMPORTANT]
|
|
> Support for this driver has been deprecated, since the driver package has been abandoned.
|
|
> It will be removed in the next major version of this extension.
|
|
|
|
```yaml
|
|
default:
|
|
extensions:
|
|
Behat\MinkExtension:
|
|
sessions:
|
|
default:
|
|
zombie:
|
|
# Specify the path to the node_modules directory.
|
|
node_modules_path: /usr/local/lib/node_modules/
|
|
```
|
|
|
|
> [!NOTE]
|
|
> The phar version of Mink comes bundled with all 5 drivers and you don't need to do
|
|
> anything except enabling them in order to use them.
|
|
|
|
But if you're using Composer, you need to install drivers that you need first:
|
|
|
|
- GoutteDriver - `behat/mink-goutte-driver`
|
|
- SeleniumDriver - `behat/mink-selenium-driver`
|
|
- Selenium2Driver (also used for SauceLabs and BrowserStack) - `behat/mink-selenium2-driver`
|
|
- SahiDriver - `behat/mink-sahi-driver`
|
|
- ZombieDriver - `behat/mink-zombie-driver`
|
|
|
|
> [!NOTE]
|
|
> All drivers share the same API, which means that you could use multiple drivers
|
|
> for the same suite - whichever one fits your needs for concrete scenarios. Don't
|
|
> try to stick to a single driver as there's simply no universal solution - every
|
|
> driver has its pros and cons.
|
|
|
|
### Additional Parameters
|
|
|
|
There's other useful parameters, that you can use to configure your suite:
|
|
|
|
* `base_url` - if you're using relative paths in your `*.feature` files
|
|
(and you should), then this option will define which url to use as a basename
|
|
for them.
|
|
* `files_path` - there's a special step definition for file upload inputs
|
|
usage. You can use relative paths in those steps. `files_path` defines
|
|
the base path in which Mink should search for those relative files.
|
|
* `show_cmd` - there's a special definition in MinkExtension, that saves
|
|
the currently opened page into a temporary file and opens it with some browser
|
|
utility (for debugging). This option defines the command to be used for opening.
|
|
For example: `show_cmd: 'firefox %s'`.
|
|
* `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 the default session (driver) to be used for all
|
|
untagged scenarios. This could be any enabled session name.
|
|
* `javascript_session` - defines the javascript session (driver) (the one, which
|
|
will be used for `@javascript` tagged scenarios). This could be any enabled session
|
|
name.
|
|
* `mink_loader` - path to a file loaded to make Mink available (useful when
|
|
using the PHAR archive for Mink, useless when using Composer)
|