Skip to content

Commit 9936d50

Browse files
stofstof
committed
Reorganize the documentation into multiple chapters
The content is still the same. This change is focusing on moving it around to split the doc into multiple pages. The order of the toctree is also meant to put the emphasis on the Session and Element rather than on the driver like previously, because the driver is the internal API of Mink and beginners should never need to deal with it except for the instantiation.
1 parent 0c2f7fd commit 9936d50

12 files changed

Lines changed: 796 additions & 752 deletions

‎at-a-glance.rst‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
Mink at a Glance
2+
================
3+
4+
There's huge amount of browser emulators out there, like `Goutte`_, `Selenium`_,
5+
`Sahi`_ and others. They all do the same job, but do it very differently.
6+
They behave differently and have very different API's. But, what's more important,
7+
there is actually 2 completely different types of browser emulators out there:
8+
9+
* Headless browser emulators
10+
* Browser controllers
11+
12+
First type browsers are simple pure HTTP specification implementations, like
13+
`Goutte`_. Those browser emulators send a real HTTP requests against an application
14+
and parse the response content. They are very simple to run and configure,
15+
because this type of emulators can be written in any available programming
16+
language and can be run through console on servers without GUI. Headless
17+
emulators have both advantages and disadvantages. Advantages are simplicity,
18+
speed and ability to run it without the need of a real browser. But this
19+
type of browsers has one big disadvantage, they have no JS/AJAX support.
20+
So, you can't test your rich GUI web applications with headless browsers.
21+
22+
Second browser emulators type are browser controllers. Those emulators aims
23+
to control the real browser. That's right, a program to control another program.
24+
Browser controllers simulate user interactions on browser and are able to
25+
retrieve actual information from current browser page. `Selenium`_ and `Sahi`_
26+
are the two most famous browser controllers. The main advantage of browser
27+
controllers usage is the support for JS/AJAX interactions on page. Disadvantage
28+
is that such browser emulators require the installed browser, extra configuration
29+
and are usually much slower than headless counterparts.
30+
31+
So, the easy answer is to choose the best emulator for your project and use
32+
its API for testing. But as we've already seen, both browser types have both
33+
advantages and disadvantages. If you choose headless browser emulator, you
34+
will not be able to test your JS/AJAX pages. And if you choose browser controller,
35+
your overall test suite will become very slow at some point. So, in real
36+
world we should use both! And that's why you need a **Mink**.
37+
38+
**Mink** removes API differences between different browser emulators providing
39+
different drivers (read in :doc:`/guides/drivers` chapter) for
40+
every browser emulator and providing you with the easy way to control the
41+
browser (:doc:`/guides/session`), traverse pages
42+
(:doc:`/guides/traversing-pages`) or manipulate page elements
43+
(:doc:`/guides/manipulating-pages`).
44+
45+
.. _Goutte: https://github.com/FriendsOfPHP/Goutte
46+
.. _Sahi: http://sahi.co.in/w/
47+
.. _Selenium: http://seleniumhq.org/

‎drivers/goutte.rst‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
GoutteDriver
2+
============
3+
4+
GoutteDriver provides a bridge for the `Goutte`_ headless browser. Goutte
5+
is a classical pure-php headless browser, written by the creator of the Symfony
6+
framework Fabien Potencier.
7+
8+
In order to talk with Goutte, you should instantiate a
9+
``Behat\Mink\Driver\GoutteDriver``:
10+
11+
.. code-block:: php
12+
13+
$driver = new \Behat\Mink\Driver\GoutteDriver();
14+
15+
Also, if you want to configure Goutte more precisely, you could do the full
16+
setup by hand:
17+
18+
.. code-block:: php
19+
20+
$client = new \Goutte\Client();
21+
// Do more configuration for the Goutte client
22+
23+
$driver = new \Behat\Mink\Driver\GoutteDriver($client);
24+
25+
.. tip::
26+
27+
GoutteDriver is compatible with both Goutte 1.x which relies on `Guzzle 3`_
28+
and Goutte 2.x which relies on `Guzzle 4+`_ for the underlying HTTP implementation.
29+
30+
.. _Goutte: https://github.com/FriendsOfPHP/Goutte
31+
.. _Guzzle 3: http://guzzle3.readthedocs.org/en/latest/
32+
.. _Guzzle 4+: http://docs.guzzlephp.org/en/latest/

‎drivers/sahi.rst‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
SahiDriver
2+
==========
3+
4+
SahiDriver provides a bridge for the `Sahi`_ browser controller. Sahi is
5+
a new JS browser controller, that fast replaced old Selenium testing suite.
6+
It's both easier to setup and to use than classical Selenium. It has a GUI
7+
installer for each popular operating system out there and is able to control
8+
every systems browser through a special bundled proxy server.
9+
10+
In order to talk with a real browser through Sahi, you should install and
11+
configure Sahi first:
12+
13+
1. Download and run the Sahi jar from the `Sahi project website`_ and run
14+
it. It will run the installer, which will guide you through the installation
15+
process.
16+
17+
2. Run Sahi proxy before your test suites (you can start this proxy during
18+
system startup):
19+
20+
.. code-block:: bash
21+
22+
cd $YOUR_PATH_TO_SAHI/bin
23+
./sahi.sh
24+
25+
After installing Sahi and running the Sahi proxy server, you will be able
26+
to control it with ``Behat\Mink\Driver\SahiDriver``:
27+
28+
.. code-block:: php
29+
30+
$driver = new \Behat\Mink\Driver\SahiDriver('firefox');
31+
32+
.. note::
33+
34+
Notice, that first argument of ``SahiDriver`` is always a browser name,
35+
`supported by Sahi`_.
36+
37+
If you want more control during the driver initialization, like for example
38+
if you want to configure the driver to talk with a proxy on another machine,
39+
use the more verbose version with a second client argument:
40+
41+
.. code-block:: php
42+
43+
$driver = new \Behat\Mink\Driver\SahiDriver(
44+
'firefox',
45+
new \Behat\SahiClient\Client(
46+
new \Behat\SahiClient\Connection($sid, $host, $port)
47+
)
48+
);
49+
50+
.. note::
51+
52+
``$sid`` is a Sahi session ID. It's a unique string, used by the driver
53+
and the Sahi proxy in order to be able to talk with each other. You should
54+
fill this with ``null`` if you want Sahi to start your browser automatically
55+
or with some unique string if you want to control an already started
56+
browser.
57+
58+
``$host`` simply defines the host on which Sahi is started. It is ``localhost``
59+
by default.
60+
61+
``$port`` defines a Sahi proxy port. The default one is ``9999``.
62+
63+
.. _Sahi: http://sahi.co.in/w/
64+
.. _Sahi project website: http://sourceforge.net/projects/sahi/files/
65+
.. _supported by Sahi: http://sahi.co.in/w/browser-types-xml

‎drivers/selenium.rst‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
SeleniumDriver
2+
==============
3+
4+
SeleniumDriver provides a bridge for the famous `Selenium`_ tool. If you
5+
need legacy Selenium, you can use it right out of the box in your Mink test
6+
suites.
7+
8+
In order to talk with the selenium server, you should install and configure
9+
it first:
10+
11+
1. Download the Selenium Server from the `project website`_.
12+
13+
2. Run the server with the following command (update the version number to
14+
the one you downloaded):
15+
16+
.. code-block:: bash
17+
18+
$ java -jar selenium-server-standalone-2.44.0.jar
19+
20+
That's it, now you can use SeleniumDriver:
21+
22+
.. code-block:: php
23+
24+
$client = new \Selenium\Client($host, $port);
25+
$driver = new \Behat\Mink\Driver\SeleniumDriver(
26+
'firefox', 'base_url', $client
27+
);
28+
29+
.. _project website: http://seleniumhq.org/download/
30+
.. _Selenium: http://seleniumhq.org/

‎drivers/selenium2.rst‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
Selenium2Driver
2+
===============
3+
4+
Selenium2Driver provides a bridge for the `Selenium2 (webdriver)`_ tool.
5+
If you just love Selenium2, you can now use it right out of the box too.
6+
7+
In order to talk with selenium server, you should install and configure it
8+
first:
9+
10+
1. Download the Selenium Server from the `project website`_.
11+
12+
2. Run the server with the following command (update the version number to
13+
the one you downloaded):
14+
15+
.. code-block:: bash
16+
17+
$ java -jar selenium-server-standalone-2.44.0.jar
18+
19+
That's it, now you can use Selenium2Driver:
20+
21+
.. code-block:: php
22+
23+
$driver = new \Behat\Mink\Driver\Selenium2Driver('firefox');
24+
25+
.. _project website: http://seleniumhq.org/download/
26+
.. _Selenium2 (webdriver): http://seleniumhq.org/

‎drivers/zombie.rst‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
ZombieDriver
2+
============
3+
4+
ZombieDriver provides a bridge for the `Zombie.js`_ browser emulator. Zombie.js
5+
is a headless browser emulator, written in node.js. It supports all JS interactions
6+
that Sahi and Selenium do and works almost as fast as Goutte does.
7+
It's best of both worlds, actually, but still limited to only one browser
8+
type (Webkit). Also it's still slower than Goutte and requires node.js and
9+
npm to be installed on the system.
10+
11+
In order to talk with zombie.js server, you should install and configure
12+
zombie.js first:
13+
14+
1. Install node.js by following instructions from the official site:
15+
`<http://nodejs.org/>`_.
16+
17+
2. Install npm (node package manager) by following instructions from `<http://npmjs.org/>`_.
18+
19+
3. Install zombie.js with npm:
20+
21+
.. code-block:: bash
22+
23+
$ npm install -g zombie
24+
25+
After installing npm and zombie.js, you'll need to add npm libs to your ``NODE_PATH``.
26+
The easiest way to do this is to add:
27+
28+
.. code-block:: bash
29+
30+
export NODE_PATH="/PATH/TO/NPM/node_modules"
31+
32+
into your ``.bashrc``.
33+
34+
After that, you'll be able to just use ZombieDriver without manual server
35+
setup. The driver will do all that for you automatically:
36+
37+
.. code-block:: php
38+
39+
$driver = new \Behat\Mink\Driver\ZombieDriver(
40+
new \Behat\Mink\Driver\NodeJS\Server\ZombieServer()
41+
);
42+
43+
If you want more control during driver initialization, like for example if
44+
you want to configure the driver to init the server on a specific port, use
45+
the more verbose version:
46+
47+
.. code-block:: php
48+
49+
$driver = new \Behat\Mink\Driver\ZombieDriver(
50+
new \Behat\Mink\Driver\Zombie\Server($host, $port, $nodeBin, $script)
51+
);
52+
53+
.. note::
54+
55+
``$host`` simply defines the host on which zombie.js will be started. It's
56+
``127.0.0.1`` by default.
57+
58+
``$port`` defines a zombie.js port. Default one is ``8124``.
59+
60+
``$nodeBin`` defines full path to node.js binary. Default one is just ``node``.
61+
62+
``$script`` defines a node.js script to start zombie.js server. If you pass
63+
a ``null`` the default script will be used. Use this option carefully!
64+
65+
.. _Zombie.js: http://zombie.labnotes.org/

‎guides/drivers.rst‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Drivers
2+
=======
3+
4+
How does Mink provide a consistent API for very different browser library
5+
types, often written in different languages? Through drivers! A Mink driver
6+
is a simple class, that implements ``Behat\Mink\Driver\DriverInterface``.
7+
This interface describes bridge methods between Mink and real browser emulators.
8+
Mink always talks with browser emulators through its driver. It doesn't know
9+
anything about how to start/stop or traverse page in that particular browser
10+
emulator. It only knows what driver method it should call in order to do this.
11+
12+
Mink comes with five drivers out of the box:
13+
14+
.. toctree::
15+
:maxdepth: 1
16+
17+
/drivers/goutte
18+
/drivers/selenium2
19+
/drivers/zombie
20+
/drivers/sahi
21+
/drivers/selenium
22+
23+
.. todo:: Build a table of the features supported by each driver

‎guides/managing-sessions.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
Managing Sessions
2+
=================
3+
4+
Although the :doc:`session object </guides/session>` is already usable enough,
5+
it's not as easy to write multisession (multidriver/multibrowser) code. Yep,
6+
you've heard right, with Mink you can manipulate multiple browser emulators
7+
simultaneously with a single consistent API:
8+
9+
.. code-block:: php
10+
11+
// init sessions
12+
$session1 = new \Behat\Mink\Session($driver1);
13+
$session2 = new \Behat\Mink\Session($driver2);
14+
15+
// start sessions
16+
$session1->start();
17+
$session2->start();
18+
19+
$session1->visit('http://my_project.dev/chat.php');
20+
$session2->visit('http://my_project.dev/chat.php');
21+
22+
.. caution::
23+
24+
The state of a session is actually managed by the driver. This means
25+
that each session must use a different driver instance.
26+
27+
Isn't it cool? But Mink makes it even cooler:
28+
29+
.. code-block:: php
30+
31+
$mink = new \Behat\Mink\Mink();
32+
$mink->registerSession('goutte', $goutteSession);
33+
$mink->registerSession('sahi', $sahiSession);
34+
$mink->setDefaultSessionName('goutte');
35+
36+
With such configuration, you can talk with your sessions by name through
37+
one single container object:
38+
39+
.. code-block:: php
40+
41+
$mink->getSession('goutte')->visit('http://my_project.dev/chat.php');
42+
$mink->getSession('sahi')->visit('http://my_project.dev/chat.php');
43+
44+
.. note::
45+
46+
Mink will even lazy-start your sessions when needed (on first ``getSession()``
47+
call). So, the browser will not be started until you really need it!
48+
49+
Or you could even omit the session name in default cases:
50+
51+
.. code-block:: php
52+
53+
$mink->getSession()->visit('http://my_project.dev/chat.php');
54+
55+
This call is possible thanks to ``$mink->setDefaultSessionName('goutte')``
56+
setting previously. We've set the default session, that would be returned
57+
on ``getSession()`` call without arguments.
58+
59+
.. tip::
60+
61+
The ``Behat\Mink\Mink`` class also provides an easy way to reset or restart
62+
your started sessions (and only started ones):
63+
64+
.. code-block:: php
65+
66+
// reset started sessions
67+
$mink->resetSessions();
68+
69+
// restart started sessions
70+
$mink->restartSessions();

0 commit comments

Comments
 (0)