From 48d792afeb41be2d16255b28b5cb3ae92caca613 Mon Sep 17 00:00:00 2001 From: Phil Davis Date: Mon, 21 Aug 2017 20:19:08 +0545 Subject: [PATCH] Minor doc review --- at-a-glance.rst | 40 +++++++++++++++---------------- drivers/browserkit.rst | 2 +- drivers/sahi.rst | 4 ++-- guides/drivers.rst | 4 ++-- guides/interacting-with-pages.rst | 16 ++++++------- guides/managing-sessions.rst | 2 +- guides/manipulating-pages.rst | 11 ++++----- guides/session.rst | 2 +- guides/traversing-pages.rst | 8 +++---- index.rst | 12 +++++----- 10 files changed, 50 insertions(+), 51 deletions(-) diff --git a/at-a-glance.rst b/at-a-glance.rst index 11c7f9b..51cfec3 100644 --- a/at-a-glance.rst +++ b/at-a-glance.rst @@ -1,43 +1,43 @@ Mink at a Glance ================ -There's huge number of browser emulators out there, like `Goutte`_, `Selenium`_, +There's a huge number of browser emulators out there, like `Goutte`_, `Selenium`_, `Sahi`_ and others. They all do the same job, but do it very differently. They behave differently and have very different API's. But, what's more important, -there is actually 2 completely different types of browser emulators out there: +there are actually 2 completely different types of browser emulators out there: * Headless browser emulators * Browser controllers -First type browser emulators are simple pure HTTP specification implementations, like -`Goutte`_. Those browser emulators send a real HTTP requests against an application +The first type of browser emulators are simple pure HTTP specification implementations, like +`Goutte`_. Those browser emulators send real HTTP requests against an application and parse the response content. They are very simple to run and configure, -because this type of emulators can be written in any available programming -language and can be run through console on servers without GUI. Headless +because this type of emulator can be written in any available programming +language and can be run through the console on servers without a GUI. Headless emulators have both advantages and disadvantages. Advantages are simplicity, -speed and ability to run it without the need of a real browser. But this -type of browsers has one big disadvantage, they have no JS/AJAX support. +speed and ability to run without the need of a real browser. But this +type of browser emulator has one big disadvantage, it has no JS/AJAX support. So, you can't test your rich GUI web applications with headless browsers. -Second browser emulators type are browser controllers. Those emulators aim +The second type of browser emulators are browser controllers. Those emulators aim to control the real browser. That's right, a program to control another program. -Browser controllers simulate user interactions on browser and are able to -retrieve actual information from current browser page. `Selenium`_ and `Sahi`_ -are the two most famous browser controllers. The main advantage of browser -controllers usage is the support for JS/AJAX interactions on page. The disadvantage -is that such browser emulators require the installed browser, extra configuration +Browser controllers simulate user interactions on the browser and are able to +retrieve actual information from the current browser page. `Selenium`_ and `Sahi`_ +are the two most famous browser controllers. The main advantage of using browser +controllers is the support for JS/AJAX interactions on the page. The disadvantage +is that such browser emulators require an installed browser, extra configuration and are usually much slower than headless counterparts. So, the easy answer is to choose the best emulator for your project and use -its API for testing. But as we've already seen, both browser emulator types have both -advantages and disadvantages. If you choose headless browser emulator, you -will not be able to test your JS/AJAX pages. And if you choose browser controller, -your overall test suite will become very slow at some point. So, in real -world we should use both! And that's why you need a **Mink**. +its API for testing. But as we've already seen, both browser emulator types have +advantages and disadvantages. If you choose a headless browser emulator, you +will not be able to test your JS/AJAX pages. And if you choose a browser controller, +your overall test suite will become very slow at some point. So, in the real +world we should use both! And that's why you need **Mink**. **Mink** removes API differences between different browser emulators providing different drivers (read in :doc:`/guides/drivers` chapter) for every browser -emulator and providing you with the easy way to control the browser (:doc:`/guides/session`), +emulator and providing you with an easy way to control the browser (:doc:`/guides/session`), traverse pages (:doc:`/guides/traversing-pages`), manipulate page elements (:doc:`/guides/manipulating-pages`) or interact with them (:doc:`/guides/interacting-with-pages`). diff --git a/drivers/browserkit.rst b/drivers/browserkit.rst index 4634cd6..2789f01 100644 --- a/drivers/browserkit.rst +++ b/drivers/browserkit.rst @@ -16,7 +16,7 @@ BrowserKitDriver is a pure PHP library available through Composer: .. note:: The BrowserKit component only provides an abstract implementation. The - actual implementation are provided by other projects, like `Goutte`_ + actual implementation is provided by other projects, like `Goutte`_ or the `Symfony HttpKernel`_ component. If you are using Goutte, you should use the special :doc:`/drivers/goutte` diff --git a/drivers/sahi.rst b/drivers/sahi.rst index 116ffc1..314ea21 100644 --- a/drivers/sahi.rst +++ b/drivers/sahi.rst @@ -2,7 +2,7 @@ SahiDriver ========== SahiDriver provides a bridge for the `Sahi`_ browser controller. Sahi is -a new JS browser controller, that fast replaced old Selenium testing suite. +a new JS browser controller, that fast replaced the old Selenium testing suite. It's both easier to setup and to use than classical Selenium. It has a GUI installer for each popular operating system out there and is able to control every systems browser through a special bundled proxy server. @@ -43,7 +43,7 @@ to control it with ``Behat\Mink\Driver\SahiDriver``: .. note:: - Notice, that first argument of ``SahiDriver`` is always a browser name, + Notice, that the first argument of ``SahiDriver`` is always a browser name, `supported by Sahi`_. If you want more control during the driver initialization, like for example diff --git a/guides/drivers.rst b/guides/drivers.rst index 40452c6..c619b6a 100644 --- a/guides/drivers.rst +++ b/guides/drivers.rst @@ -6,7 +6,7 @@ types, often written in different languages? Through drivers! A Mink driver is a simple class, that implements ``Behat\Mink\Driver\DriverInterface``. This interface describes bridge methods between Mink and real browser emulators. Mink always talks with browser emulators through its driver. It doesn't know -anything about how to start/stop or traverse page in that particular browser +anything about how to start/stop or traverse pages in that particular browser emulator. It only knows what driver method it should call in order to do this. Mink comes with six drivers out of the box: @@ -26,7 +26,7 @@ Mink comes with six drivers out of the box: Driver Feature Support ---------------------- -Although Mink does its best on removing browser differences between different +Although Mink does its best to remove browser differences between different browser emulators, it can't do much in some cases. For example, BrowserKitDriver cannot evaluate JavaScript and Selenium2Driver cannot get the response status code. In such cases, the driver will always throw a meaningful diff --git a/guides/interacting-with-pages.rst b/guides/interacting-with-pages.rst index af3b7f8..95b3535 100644 --- a/guides/interacting-with-pages.rst +++ b/guides/interacting-with-pages.rst @@ -13,14 +13,14 @@ the links and press the buttons on the page. .. note:: These methods are actually equivalent internally (pressing a button involves - clicking on it). Having both methods allows to keep the code more readable. + clicking on it). Having both methods allows the code to be more readable. .. _interacting-with-forms: Interacting with Forms ---------------------- -The ``NodeElement`` class has a set of methods allowing to interact with +The ``NodeElement`` class has a set of methods allowing interaction with forms: ``NodeElement::getValue`` @@ -67,7 +67,7 @@ forms: Interacting with the Mouse -------------------------- -The ``NodeElement`` class offers a set of methods allowing to interact with +The ``NodeElement`` class offers a set of methods allowing interaction with the mouse: ``NodeElement::click`` @@ -109,8 +109,8 @@ Mink supports drag'n'drop of one element onto another: Shortcut Methods ---------------- -The ``TraversableElement`` class provides a few shortcut methods allowing -to find a child element on the page and perform an action on it immediately: +The ``TraversableElement`` class provides a few shortcut methods that allow +finding a child element on the page and performing an action on it immediately: ``TraversableElement::clickLink`` Looks for a link (see findLink) and clicks on it. @@ -131,9 +131,9 @@ to find a child element on the page and perform an action on it immediately: Looks for a select or radio group (see findField) and selects a choice in it. ``TraversableElement::attachFileToField`` - Looks for a file field (see findField) and attach a file to it. + Looks for a file field (see findField) and attaches a file to it. .. note:: - All these shortcut methods are throwing an ``ElementNotFoundException`` - in case the child element cannot be found. + All these shortcut methods throw an ``ElementNotFoundException`` + if the child element cannot be found. diff --git a/guides/managing-sessions.rst b/guides/managing-sessions.rst index 3fed60d..a27b988 100644 --- a/guides/managing-sessions.rst +++ b/guides/managing-sessions.rst @@ -43,7 +43,7 @@ one single container object: .. note:: - Mink will even lazy-start your sessions when needed (on first ``getSession()`` + Mink will even lazy-start your sessions when needed (on the first ``getSession()`` call). So, the browser will not be started until you really need it! Or you could even omit the session name in default cases: diff --git a/guides/manipulating-pages.rst b/guides/manipulating-pages.rst index 5b870d7..09e3222 100644 --- a/guides/manipulating-pages.rst +++ b/guides/manipulating-pages.rst @@ -60,19 +60,18 @@ The ``Element`` class provides access to the content of elements. .. note:: ``getText()`` will strip tags and unprinted characters out of the response, - including newlines. So it'll basically return the text, that user sees + including newlines. So it'll basically return the text that the user sees on the page. Checking Element Visibility --------------------------- -The ``NodeElement::isVisible`` methods allows to checks whether the element -is visible. +The ``NodeElement::isVisible`` method checks whether the element is visible. Accessing Form State -------------------- -The ``NodeElement`` class allows to access the state of form elements: +The ``NodeElement`` class allows access to the state of form elements: ``NodeElement::getValue`` Gets the value of the element. See :ref:`interacting-with-forms`. @@ -86,8 +85,8 @@ The ``NodeElement`` class allows to access the state of form elements: Shortcut methods ~~~~~~~~~~~~~~~~ -The ``TraversableElement`` class provides a few shortcut methods allowing -to find a child element in the page and checks the state of it immediately: +The ``TraversableElement`` class provides a few shortcut methods that allow +finding a child element in the page and checking the state of it immediately: ``TraversableElement::hasCheckedField`` Looks for a checkbox (see findField) and checks whether it is checked. diff --git a/guides/session.rst b/guides/session.rst index 81d5ad3..7fcacef 100644 --- a/guides/session.rst +++ b/guides/session.rst @@ -139,7 +139,7 @@ The method can also be used to reset a previous authentication: .. note:: Automatic HTTP authentication is only supported in headless drivers. - Because HTTP authentication in browser requires manual user action, that + Because HTTP authentication in the browser requires manual user action, that can't be done remotely for browser controllers. Javascript Evaluation diff --git a/guides/traversing-pages.rst b/guides/traversing-pages.rst index 923df0c..9f144b0 100644 --- a/guides/traversing-pages.rst +++ b/guides/traversing-pages.rst @@ -61,7 +61,7 @@ on top of ``find()`` to make it easier to achieve many common use cases: .. note:: - These shortcuts are returning a single element. If you need to find all + These shortcuts return a single element. If you need to find all matches, you will need to use ``findAll`` with the :ref:`named selector `. Nested Traversing @@ -69,7 +69,7 @@ Nested Traversing Every ``find*()`` method will return a ``Behat\Mink\Element\NodeElement`` instance and ``findAll()`` will return an array of such instances. The fun part is -that you can make same old traversing on such elements as well: +that you can use the same methods of traversing on such elements as well: .. code-block:: php @@ -116,7 +116,7 @@ on the page: This selector searches for an element inside the current node (which is ```` for the page object). This means that trying to pass it - the XPath of and element retrieved with ``ElementInterface::getXpath`` + the XPath of an element retrieved with ``ElementInterface::getXpath`` will not work (this query includes the query for the root node). To check whether an element object still exists on the browser page, use ``ElementInterface::isValid`` instead. @@ -128,7 +128,7 @@ Named Selectors Named selectors provide a set of reusable queries for common needs. For conditions based on the content of elements, the named selector will try to find an -exact match first. It will then fallback to partial matching in case there +exact match first. It will then fallback to partial matching if there is no result for the exact match. The ``named_exact`` selector type can be used to force using only exact matching. The ``named_partial`` selector type can be used to apply partial matching without preferring exact matches. diff --git a/index.rst b/index.rst index 57b6351..26dee5a 100644 --- a/index.rst +++ b/index.rst @@ -1,13 +1,13 @@ Welcome to the Mink documentation! ================================== -One of the most important parts in the web is a browser. Browser is the window +One of the most important parts in the web is a browser. A browser is the window through which web users interact with web applications and other users. Users are always talking with web applications through browsers. So, in order to test that our web application behaves correctly, we need a way to simulate this interaction between the browser and the web application -in our tests. We need a **Mink**. +in our tests. We need **Mink**. Mink is an open source browser controller/emulator for web applications, written in PHP 5.3. @@ -34,8 +34,8 @@ The recommended way to install Mink with all its dependencies is through In this case you must use the different call ``php composer.phar`` everywhere instead of the simple command ``composer``. -Everything will be installed inside ``vendor`` folder. -Finally, include Composer autoloading script to your project: +Everything will be installed inside the ``vendor`` folder. +Finally, include the Composer autoloading script to your project: .. code-block:: php @@ -55,9 +55,9 @@ Finally, include Composer autoloading script to your project: - SahiDriver - ``behat/mink-sahi-driver`` - WUnitDriver - ``behat/mink-wunit-driver`` - If you're newcomer or just don't know what to choose, you should probably + If you're a newcomer or just don't know what to choose, you should probably start with the GoutteDriver and the Selenium2Driver (you will be able - to tuneup it later): + to tune it up later): Guides ------