Skip to content

Commit bdc5d6f

Browse files
stofstof
committed
Rewrite the page manipulation chapter
1 parent 7c5d80d commit bdc5d6f

6 files changed

Lines changed: 212 additions & 77 deletions

File tree

‎at-a-glance.rst‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,10 @@ your overall test suite will become very slow at some point. So, in real
3636
world we should use both! And that's why you need a **Mink**.
3737

3838
**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`).
39+
different drivers (read in :doc:`/guides/drivers` chapter) for every browser
40+
emulator and providing you with the easy way to control the browser (:doc:`/guides/session`),
41+
traverse pages (:doc:`/guides/traversing-pages`), manipulate page elements
42+
(:doc:`/guides/manipulating-pages`) or interact with them (:doc:`/guides/interacting-with-pages`).
4443

4544
.. _Goutte: https://github.com/FriendsOfPHP/Goutte
4645
.. _Sahi: http://sahi.co.in/w/

‎guides/interacting-with-pages.rst‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
Interacting with Pages
2+
======================
3+
4+
Most usages of Mink will involve working with the page opened in your browser.
5+
The Mink Element API lets you interact with elements of the page.
6+
7+
Interacting with Links and Buttons
8+
----------------------------------
9+
10+
The ``NodeElement::click`` and ``NodeElement::press`` methods let you click
11+
the links and press the buttons on the page.
12+
13+
.. note::
14+
15+
These methods are actually equivalent internally (pressing a button involves
16+
clicking on it). Having both methods allows to keep the code more readable.
17+
18+
.. _interacting-with-forms:
19+
20+
Interacting with Forms
21+
----------------------
22+
23+
The ``NodeElement`` class has a set of methods allowing to interact with
24+
forms:
25+
26+
``NodeElement::getValue``
27+
gets the value of a form field. The value depends on the type of field:
28+
29+
- the value of the selected option for single select boxes (or ``null``
30+
when none are selected);
31+
- an array of selected option values for multiple select boxes;
32+
- the value of the checkbox field when checked, or ``null`` when not
33+
checked;
34+
- the value of the selected radio button in the radio group for radio
35+
buttons;
36+
- the value of the field for textual fields and textareas;
37+
- an undefined value for file fields (because of browser limitations).
38+
39+
``NodeElement::setValue``
40+
sets the value of a form field
41+
42+
- for a file field, it should be the absolute path to the file;
43+
- for a checkbox, it should be a boolean indicating whether it is checked;
44+
- for other fields, it should match the behavior of ``getValue``.
45+
46+
``NodeElement::isChecked``
47+
reports whether a radio button or a checkbox is checked.
48+
49+
``NodeElement::isSelected``
50+
reports whether an ``<option>`` element is selected.
51+
52+
``NodeElement::check``
53+
checks a checkbox field.
54+
55+
``NodeElement::uncheck``
56+
unchecks a checkbox field.
57+
58+
``NodeElement::selectOption``
59+
select an option in a select box or in a radio group.
60+
61+
``NodeElement::attachFile``
62+
attaches a file in a file input.
63+
64+
``NodeElement::submit``
65+
submits the form.
66+
67+
Interacting with the Mouse
68+
--------------------------
69+
70+
The ``NodeElement`` class offers a set of methods allowing to interact with
71+
the mouse:
72+
73+
``NodeElement::click``
74+
performs a click on the element.
75+
76+
``NodeElement::doubleClick``
77+
performs a double click on the element.
78+
79+
``NodeElement::rightClick``
80+
performs a right click on the element.
81+
82+
``NodeElement::mouseOver``
83+
moves the mouse over the element.
84+
85+
Interacting with the Keyboard
86+
-----------------------------
87+
88+
Mink lets you interact with the keyboard thanks to the ``NodeElement::keyDown``,
89+
``NodeElement::keyPress`` and ``NodeElement::keyUp`` methods.
90+
91+
Manipulating the Focus
92+
----------------------
93+
94+
The ``NodeElement`` class lets you give and remove focus on the element thanks
95+
to the ``NodeElement::focus`` and ``NodeElement::blur`` methods.
96+
97+
Drag'n'Drop
98+
-----------
99+
100+
Mink supports drag'n'drop of one element onto another:
101+
102+
.. code-block:: php
103+
104+
$dragged = $page->find(...);
105+
$target = $page->find(...);
106+
107+
$dragged->dragTo($target);
108+
109+
Shortcut Methods
110+
----------------
111+
112+
The ``TraversableElement`` class provides a few shortcut methods allowing
113+
to find a child element on the page and perform an action on it immediately:
114+
115+
``TraversableElement::clickLink``
116+
Looks for a link (see findLink) and clicks on it.
117+
118+
``TraversableElement::pressButton``
119+
Looks for a button (see findButton) and presses on it.
120+
121+
``TraversableElement::fillField``
122+
Looks for a field (see findField) and sets a value in it.
123+
124+
``TraversableElement::checkField``
125+
Looks for a checkbox (see findField) and checks it.
126+
127+
``TraversableElement::uncheckField``
128+
Looks for a checkbox (see findField) and unchecks it.
129+
130+
``TraversableElement::selectFieldOption``
131+
Looks for a select or radio group (see findField) and selects a choice in it.
132+
133+
``TraversableElement::attachFileToField``
134+
Looks for a file field (see findField) and attach a file to it.
135+
136+
.. note::
137+
138+
All these shortcut methods are throwing an ``ElementNotFoundException``
139+
in case the child element cannot be found.

‎guides/manipulating-pages.rst‎

Lines changed: 60 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,96 @@
11
Manipulating Pages
22
==================
33

4-
Ok, you've got an interesting page element. Now you'll want to do something
5-
with it. ``Behat\Mink\Element\NodeElement`` provides bunch a of useful methods
6-
for you:
4+
Once you :doc:`get a page element </guides/traversing-pages>`, you will want
5+
to manipulate it. You can also interact with the page, which is covered in
6+
the :doc:`next chapter </guides/interacting-with-pages>`.
7+
8+
Getting the tag name
9+
--------------------
10+
11+
The ``NodeElement::getTagName`` method allows you to get the tag name of
12+
the element. This tag name is always returned lowercased.
713

814
.. code-block:: php
915
1016
$el = $page->find('css', '.something');
1117
1218
// get tag name:
13-
echo $el->getTagName();
19+
echo $el->getTagName(); // displays 'a'
1420
15-
// check that element has href attribute:
16-
$el->hasAttribute('href');
21+
Accessing HTML attributes
22+
-------------------------
1723

18-
// get element's href attribute:
19-
echo $el->getAttribute('href');
20-
21-
Element Content and Text
22-
~~~~~~~~~~~~~~~~~~~~~~~~
23-
24-
To retrieve HTML content or plain text from out of the element, you can use:
25-
26-
.. code-block:: php
24+
The ``NodeElement`` class gives you access to HTML attributes of the element.
2725

28-
$plainText = $el->getText();
29-
$html = $el->getHtml();
30-
31-
.. note::
32-
33-
``getText()`` will strip tags and unprinted characters out of the response,
34-
including newlines. So it'll basically return the text, that user sees
35-
on the page.
26+
``NodeElement::hasAttribute``
27+
Checks whether the element has a given attribute.
3628

37-
Form Field Manipulations
38-
~~~~~~~~~~~~~~~~~~~~~~~~
29+
``NodeElement::getAttribute``
30+
Gets the value of an attribute.
3931

40-
You can fill form fields/retrieve its values with form manipulation actions:
32+
``NodeElement::hasClass``
33+
Checks whether the element has the given class (convenience wrapper around
34+
``getAttribute('class')``).
4135

4236
.. code-block:: php
4337
44-
// check/uncheck checkbox:
45-
if ($el->isChecked()) {
46-
$el->uncheck();
47-
}
48-
$el->check();
49-
50-
// select option in select:
51-
$el->selectOption('option value');
38+
$el = $page->find('css', '.something');
5239
53-
// attach file to file input:
54-
$el->attachFile('/path/to/file');
40+
if ($el->hasAttribute('href') {
41+
echo $el->getAttribute('href');
42+
} else {
43+
echo 'This anchor is not a link. It does not have an href.';
44+
}
5545
56-
// get input value:
57-
echo $el->getValue();
46+
Element Content and Text
47+
------------------------
5848

59-
// set intput value:
60-
$el->setValue('some val');
49+
The ``Element`` class provides access to the content of elements.
6150

62-
// press the button:
63-
$el->press();
51+
``Element::getHtml``
52+
Gets the inner HTML of the element, i.e. all children of the element.
6453

54+
``Element::getOuterHtml``
55+
Gets the outer HTML of the element, i.e. including the element itself.
6556

66-
Mouse Manipulations
67-
~~~~~~~~~~~~~~~~~~~
57+
``Element::getText``
58+
Gets the text of the element.
6859

69-
You can perform mouse manipulations on an element:
60+
.. note::
7061

71-
.. code-block:: php
62+
``getText()`` will strip tags and unprinted characters out of the response,
63+
including newlines. So it'll basically return the text, that user sees
64+
on the page.
7265

73-
$el->click();
74-
$el->doubleClick();
75-
$el->rightClick();
76-
$el->mouseOver();
77-
$el->focus();
78-
$el->blur();
66+
Checking Element Visibility
67+
---------------------------
7968

80-
.. note::
69+
The ``NodeElement::isVisible`` methods allows to checks whether the element
70+
is visible.
8171

82-
All methods except ``click()`` are not supported by ``Driver\GoutteDriver``,
83-
because there is no way how it can perform them without actual browser
84-
window.
72+
Accessing Form State
73+
--------------------
8574

86-
Drag'n'Drop
87-
~~~~~~~~~~~
75+
The ``NodeElement`` class allows to access the state of form elements:
8876

89-
Mink even supports drag'n'drop of one field onto another:
77+
``NodeElement::getValue``
78+
Gets the value of the element. See :ref:`interacting-with-forms`.
9079

91-
.. code-block:: php
80+
``NodeElement::isChecked``
81+
Checks whether the checkbox or radio button is checked.
9282

93-
$el1 = $page->find(...);
94-
$el2 = $page->find(...);
83+
``NodeElement::isSelected``
84+
Checks whether the ``<option>`` element is selected.
9585

96-
$el1->dragTo($el2);
86+
Shortcut methods
87+
~~~~~~~~~~~~~~~~
9788

98-
.. note::
89+
The ``TraversableElement`` class provides a few shortcut methods allowing
90+
to find a child element in the page and checks the state of it immediately:
9991

100-
Drag'n'drop is not supported by ``Driver\GoutteDriver``, because there
101-
is no way how it can perform this action without actual browser window.
92+
``TraversableElement::hasCheckedField``
93+
Looks for a checkbox (see findField) and checks whether it is checked.
10294

95+
``TraversableElement::hasUncheckedField``
96+
Looks for a checkbox (see findField) and checks whether it is not checked.

‎guides/session.rst‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,10 +52,11 @@ Interacting with the Page
5252
-------------------------
5353

5454
The session gives you access to the page through the ``Session::getPage``
55-
method. This allows you to :doc:`traverse </guides/traversing-pages>` and
56-
:doc:`manipulate </guides/manipulating-pages>` it. The next chapters cover
57-
the page API in depth. Most of what you'll do with Mink will use this object,
58-
but you can continue reading to learn more about the Session.
55+
method. This allows you to :doc:`traverse the page </guides/traversing-pages>`,
56+
:doc:`manipulate page elements </guides/traversing-pages>` and
57+
:doc:`interact </guides/interacting-with-pages>` with them. The next chapters
58+
cover the page API in depth. Most of what you'll do with Mink will use this
59+
object, but you can continue reading to learn more about the Session.
5960

6061
Using the Browser History
6162
-------------------------

‎guides/traversing-pages.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,9 @@ Traversing Pages
33

44
Most usages of Mink will involve working with the page opened in your browser.
55
This is done thanks to the powerful Element API. This API allows to traverse
6-
the page (similar to the DOM in Javascript) and to interact with it, which
7-
will be covered in the :doc:`next chapter </guides/manipulating-pages>`.
6+
the page (similar to the DOM in Javascript), :doc:`manipulate page elements </guides/traversing-pages>`
7+
and to :doc:`interact with them </guides/interacting-with-pages>`, which
8+
will be covered in the next chapters.
89

910
DocumentElement and NodeElement
1011
-------------------------------

‎index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ Learn Mink with the topical guides:
6464
guides/session
6565
guides/traversing-pages
6666
guides/manipulating-pages
67+
guides/interacting-with-pages
6768
guides/drivers
6869
guides/managing-sessions
6970
contributing

0 commit comments

Comments
 (0)