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
Session::getPage 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
Session::evaluateScript returns the result of the expression. When you don’t need to get a return value, using
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
Session::restart 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 resetting. The
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
Session::reset() by default and to call
Session::stop() when you need really full isolation.