Skip to content

Commit 69a7e45

Browse files
stofstof
committed
Merge pull request #27 from stof/reorganize_docs
Reorganize the documentation into multiple chapters
2 parents 9df7a56 + fcd64e7 commit 69a7e45

13 files changed

Lines changed: 799 additions & 753 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/

‎conf.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,9 @@
3939

4040
# Add any Sphinx extension module names here, as strings. They can be extensions
4141
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
42-
#extensions = []
42+
extensions = [
43+
'sphinx.ext.todo',
44+
]
4345

4446
# Add any paths that contain templates here, relative to this directory.
4547
templates_path = ['theme/_templates']

‎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)