8000 Added docs for clickLink() and submitForm() · symfony/symfony-docs@0668ccc · GitHub
[go: up one dir, main page]
Skip to content

Commit 0668ccc

Browse files
javiereguiluzjaviereguiluz
committed
Added docs for clickLink() and submitForm()
1 parent 25075f7 commit 0668ccc

File tree

2 files changed

+89
-54
lines changed

2 files changed

+89
-54
lines changed

‎components/browser_kit.rst

Lines changed: 49 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -97,42 +97,77 @@ make AJAX requests::
9797
Clicking Links
9898
~~~~~~~~~~~~~~
9999

100-
The ``Crawler`` object is capable of simulating link clicks. First, pass the
101-
text content of the link to the ``selectLink()`` method, which returns a
102-
``Link`` object. Then, pass this object to the ``click()`` method, which
103-
performs the needed HTTP GET request to simulate the link click::
100+
The ``Client`` object is capable of simulating link clicks. Pass the text
101+
content of the link and the client will perform the needed HTTP GET request to
102+
simulate the link click::
104103

105104
use Acme\Client;
106105

107106
$client = new Client();
107+
$client->request('GET', '/product/123');
108+
109+
$crawler = $client->clickLink('Go elsewhere...');
110+
111+
.. versionadded:: 4.2
112+
The ``clickLink()`` method was introduced in Symfony 4.2.
113+
114+
If you need the :class:`Symfony\\Component\\DomCrawler\\Link` object that
115+
provides access to the link properties (e.g. ``$link->getMethod()``,
116+
``$link->getUri()``), use this other method:
117+
118+
// ...
108119
$crawler = $client->request('GET', '/product/123');
109120
$link = $crawler->selectLink('Go elsewhere...')->link();
110121
$client->click($link);
111122

112123
Submitting Forms
113124
~~~~~~~~~~~~~~~~
114125

115-
The ``Crawler`` object is also capable of selecting forms. First, select any of
116-
the form's buttons with the ``selectButton()`` method. Then, use the ``form()``
117-
method to select the form which the button belongs to.
118-
119-
After selecting the form, fill in its data and send it using the ``submit()``
120-
method (which makes the needed HTTP POST request to submit the form contents)::
126+
The ``Client`` object is also capable of submitting forms. First, select the
127+
form using any of its buttons and then override any of its properties (method,
128+
field values, etc.) before submitting it::
121129

122130
use Acme\Client;
123131

124-
// make a real request to an external site
125132
$client = new Client();
126133
$crawler = $client->request('GET', 'https://github.com/login');
127134

135+
// find the form with the 'Log in' button and submit it
136+
// 'Log in' can be the text content, id, value or name of a <button> or <input type="submit">
137+
$client->submitForm('Log in');
138+
139+
// the second optional argument lets you override the default form field values
140+
$client->submitForm('Log in', array(
141+
'login' => 'my_user',
142+
'password' => 'my_pass',
143+
// to upload a file, the value must be the absolute file path
144+
'file' => __FILE__,
145+
));
146+
147+
// you can override other form options too
148+
$client->submitForm(
149+
'Log in',
150+
array('login' => 'my_user', 'password' => 'my_pass'),
151+
// override the default form HTTP method
152+
'PUT',
153+
// override some $_SERVER parameters (e.g. HTTP headers)
154+
array('HTTP_ACCEPT_LANGUAGE' => 'es')
155+
);
156+
157+
.. versionadded:: 4.2
158+
The ``submitForm()`` method was introduced in Symfony 4.2.
159+
160+
If you need the :class:`Symfony\\Component\\DomCrawler\\Form` object that
161+
provides access to the form properties (e.g. ``$form->getUri()``,
162+
``$form->getValues()``, ``$form->getFields()``), use this other method::
163+
164+
// ...
165+
128166
// select the form and fill in some values
129167
$form = $crawler->selectButton('Log in')->form();
130168
$form['login'] = 'symfonyfan';
131169
$form['password'] = 'anypass';
132170

133-
// To upload a file, the value should be the absolute file path
134-
$form['file'] = __FILE__;
135-
136171
// submit that form
137172
$crawler = $client->submit($form);
138173

‎testing.rst

Lines changed: 40 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -387,21 +387,17 @@ returns a ``Crawler`` instance.
387387
Use the crawler to find DOM elements in the response. These elements can then
388388
be used to click on links and submit forms::
389389

390-
$link = $crawler->selectLink('Go elsewhere...')->link();
391-
$crawler = $client->click($link);
390+
$crawler = $client->clickLink('Go elsewhere...');
392391

393-
$form = $crawler->selectButton('validate')->form();
394-
$crawler = $client->submit($form, array('name' => 'Fabien'));
392+
$crawler = $client->submitForm('validate', array('name' => 'Fabien'));
395393

396-
The ``click()`` and ``submit()`` methods both return a ``Crawler`` object.
394+
The ``clickLink()`` and ``submitForm()`` methods both return a ``Crawler`` object.
397395
These methods are the best way to browse your application as it takes care
398396
of a lot of things for you, like detecting the HTTP method from a form and
399397
giving you a nice API for uploading files.
400398

401-
.. tip::
402-
403-
You will learn more about the ``Link`` and ``Form`` objects in the
404-
:ref:`Crawler <testing-crawler>` section below.
399+
.. versionadded:: 4.2
400+
The ``clickLink()`` and ``submitForm()`` methods were introduced in Symfony 4.2.
405401

406402
The ``request()`` method can also be used to simulate form submissions directly
407403
or perform more complex requests. Some useful examples::
@@ -667,65 +663,68 @@ The Crawler can extract information from the nodes::
667663
Links
668664
~~~~~
669665

670-
To select links, you can use the traversing methods above or the convenient
671-
``selectLink()`` shortcut::
666+
Use the ``clickLink()`` method to click on the first link that contains the
667+
given text (or the first clickable image with that ``alt`` attribute)::
672668

673-
$crawler->selectLink('Click here');
669+
$client = static::createClient();
670+
$client->request('GET', '/post/hello-world');
674671

675-
This selects all links that contain the given text, or clickable images for
676-
which the ``alt`` attribute contains the given text. Like the other filtering
677-
methods, this returns another ``Crawler`` object.
672+
$client->clickLink('Click here');
678673

679-
Once you've selected a link, you have access to a special ``Link`` object,
680-
which has helpful methods specific to links (such as ``getMethod()`` and
681-
``getUri()``). To click on the link, use the Client's ``click()`` method
682-
and pass it a ``Link`` object::
674+
If you need access to the :class:`Symfony\\Component\\DomCrawler\\Link` object
675+
that provides helpful methods specific to links (such as ``getMethod()`` and
676+
``getUri()``), use the ``selectLink()`` method instead:
683677

684-
$link = $crawler->selectLink('Click here')->link();
678+
$client = static::createClient();
679+
$crawler = $client->request('GET', '/post/hello-world');
685680

681+
$link = $crawler->selectLink('Click here')->link();
686682
$client->click($link);
687683

688684
Forms
689685
~~~~~
690686

691-
Forms can be selected using their buttons, which can be selected with the
692-
``selectButton()`` method, just like links::
687+
Use the ``submitForm()`` method to submit the form that contains the given button::
693688

694-
$buttonCrawlerNode = $crawler->selectButton('submit');
689+
$client = static::createClient();
690+
$client->request('GET', '/post/hello-world');
691+
692+
$crawler = $client->submitForm('Add comment', array(
693+
'comment_form[content]' => '...',
694+
));
695+
696+
The first argument of ``submitForm()`` is the text content, ``id``, ``value`` or
697+
``name`` of any ``<button>`` or ``<input type="submit">`` included in the form.
698+
The second optional argument is used to override the default form field values.
695699

696700
.. note::
697701

698702
Notice that you select form buttons and not forms as a form can have several
699703
buttons; if you use the traversing API, keep in mind that you must look for a
700704
button.
701705

702-
The ``selectButton()`` method can select ``button`` tags and submit ``input``
703-
tags. It uses several parts of the buttons to find them:
706+
If you need access to the :class:`Symfony\\Component\\DomCrawler\\Form` object
707+
that provides helpful methods specific to forms (such as ``getUri()``,
708+
``getValues()`` and ``getFields()``) use the ``selectButton()`` method instead::
704709

705-
* The ``value`` attribute value;
706-
* The ``id`` or ``alt`` attribute value for images;
707-
* The ``id`` or ``name`` attribute value for ``button`` tags.
710+
$client = static::createClient();
711+
$crawler = $client->request('GET', '/post/hello-world');
708712

709-
Once you have a Crawler representing a button, call the ``form()`` method
710-
to get a ``Form`` instance for the form wrapping the button node::
713+
$buttonCrawlerNode = $crawler->selectButton('submit');
711714

715+
// select the form that contains this button
712716
$form = $buttonCrawlerNode->form();
713717

714-
When calling the ``form()`` method, you can also pass an array of field values
715-
that overrides the default ones::
716-
718+
// you can also pass an array of field values that overrides the default ones
717719
$form = $buttonCrawlerNode->form(array(
718720
'my_form[name]' => 'Fabien',
719721
'my_form[subject]' => 'Symfony rocks!',
720722
));
721723

722-
And if you want to simulate a specific HTTP method for the form, pass it as a
723-
second argument::
724-
724+
// you can pass a second argument to override the form HTTP method
725725
$form = $buttonCrawlerNode->form(array(), 'DELETE');
726726

727-
The Client can submit ``Form`` instances::
728-
727+
// submit the Form object
729728
$client->submit($form);
730729

731730
The field values can also be passed as a second argument of the ``submit()``
@@ -771,10 +770,11 @@ their type::
771770

772771
.. tip::
773772

774-
The ``submit()`` method defines a third optional argument to add custom
775-
HTTP headers when submitting the form::
773+
The ``submit()`` and ``submitForm()`` methods define optional arguments to
774+
add custom server parameters and HTTP headers when submitting the form::
776775

777776
$client->submit($form, array(), array('HTTP_ACCEPT_LANGUAGE' => 'es'));
777+
$client->submitForm($button, array(), 'POST', array('HTTP_ACCEPT_LANGUAGE' => 'es'));
778778

779779
.. versionadded:: 4.1
780780
The feature to add custom HTTP headers was introduced in Symfony 4.1.

0 commit comments

Comments
 (0)
0