Controlling the Browser¶
In Mink, the entry point to the browser is called the session. Think about it as being your browser window (some drivers even let you switch tabs!).
First, start your session (it’s like opening your browser tab). Nothing can be done with it before starting it.
// Choose a Mink driver. More about it in later chapters. $driver = new \Behat\Mink\Driver\GoutteDriver(); $session = new \Behat\Mink\Session($driver); // start the session $session->start();
The first argument to the session constructor is a driver object. Drivers are the way the Mink abstraction layer works. You will discover more about the available drivers in a later chapter.
Although Mink does its best to remove differences between the different drivers, each driver has unique features and shortcomings. See the Driver Feature Support to see which features are supported by each driver.
Basic Browser Interaction¶
Now that your session is started, you’ll want to open a page with it. Just
after starting, the session is not on any page (in a real browser, you would
be on the
about:blank page), and calling any other action is likely to fail.
Mink is primarily designed to be used for testing websites. To allow
you to browse and test error pages, the
Session::visit method does
not consider error status codes as invalid. It will not throw an exception
in this case. You will need to check the status code (or certain text
on the page) to know if the response was successful or not.
Interacting with the Page¶
The session gives you access to the page through the
method. This allows you to traverse the page,
manipulate page elements and
interact with them. The next chapters
cover the page API in depth. Most of what you’ll do with Mink will use this
object, but you can continue reading to learn more about the Session.
Using the Browser History¶
The session gives you access to the browser history:
// get the current page URL: echo $session->getCurrentUrl(); // use history controls: $session->reload(); $session->back(); $session->forward();
Status Code Retrieval¶
The session lets you retrieve the HTTP status code of the response:
The session lets you manipulate request headers and access response headers:
// setting browser language: $session->setRequestHeader('Accept-Language', 'fr'); // retrieving response headers: print_r($session->getResponseHeaders());
Headers handling is only supported in headless drivers (e.g. Goutte). Browser controllers (e.g. Selenium2) cannot access that information.
The session has a special method to perform HTTP Basic authentication:
The method can also be used to reset a previous authentication:
Automatic HTTP authentication is only supported in headless drivers. Because HTTP authentication in the browser requires manual user action, that can’t be done remotely for browser controllers.
// Execute JS $session->executeScript('document.body.firstChild.innerHTML = "";'); // evaluate JS expression: echo $session->evaluateScript( "return 'something from browser';" );
The difference between these methods is that
returns the result of the expression. When you don’t need to get a return
Session::executeScript is better.
You can also wait until a given JS expression returns a truthy value or the timeout is reached:
// wait for n milliseconds or // till JS expression becomes truthy: $session->wait( 5000, "$('.suggestions-results').children().length" );
Session::wait method returns
true when the evaluation becomes
truthy. It will return
false when the timeout is reached.
Resetting the Session¶
The primary aim for Mink is to provide a single consistent web browsing API for acceptance tests. But a very important part in testing is isolation.
Mink provides two very useful methods to isolate tests, which can be used
in your test’s
// soft-reset: $session->reset(); // hard-reset: $session->stop(); // or if you want to start again at the same time $session->restart();
Stopping the session is the best way to reset the session to its initial
state. It will close the browser entirely. To use the session again, you
need to start the session before any other action. The
shortcut allows you to do these 2 steps in a single call.
The drawback of closing the browser and starting it again is that it takes
time. In many cases, a lower level of isolation is enough in favor of a faster
Session::reset method covers this use case. It will try
to clear the cookies and reset the request headers and the browser history
to the limit of the driver possibilities.
Taking all this into account, it is recommended to use
by default and to call
Session::stop() when you need really full isolation.