Added docs for clickLink() and submitForm()

Author: javiereguiluz

components/browser_kit.rst

@@ -97,42 +97,77 @@ make AJAX requests::
 Clicking Links
 ~~~~~~~~~~~~~~
 
-The ``Crawler`` object is capable of simulating link clicks. First, pass the
-text content of the link to the ``selectLink()`` method, which returns a
-``Link`` object. Then, pass this object to the ``click()`` method, which
-performs the needed HTTP GET request to simulate the link click::
+The ``Client`` object is capable of simulating link clicks. Pass the text
+content of the link and the client will perform the needed HTTP GET request to
+simulate the link click::
 
     use Acme\Client;
 
     $client = new Client();
+    $client->request('GET', '/product/123');
+
+    $crawler = $client->clickLink('Go elsewhere...');
+
+.. versionadded:: 4.2
+    The ``clickLink()`` method was introduced in Symfony 4.2.
+
+If you need the :class:`Symfony\\Component\\DomCrawler\\Link` object that
+provides access to the link properties (e.g. ``$link->getMethod()``,
+``$link->getUri()``), use this other method:
+
+    // ...
     $crawler = $client->request('GET', '/product/123');
     $link = $crawler->selectLink('Go elsewhere...')->link();
     $client->click($link);
 
 Submitting Forms
 ~~~~~~~~~~~~~~~~
 
-The ``Crawler`` object is also capable of selecting forms. First, select any of
-the form's buttons with the ``selectButton()`` method. Then, use the ``form()``
-method to select the form which the button belongs to.
-
-After selecting the form, fill in its data and send it using the ``submit()``
-method (which makes the needed HTTP POST request to submit the form contents)::
+The ``Client`` object is also capable of submitting forms. First, select the
+form using any of its buttons and then override any of its properties (method,
+field values, etc.) before submitting it::
 
     use Acme\Client;
 
-    // make a real request to an external site
     $client = new Client();
     $crawler = $client->request('GET', 'https://github.com/login');
 
+    // find the form with the 'Log in' button and submit it
+    // 'Log in' can be the text content, id, value or name of a <button> or <input type="submit">
+    $client->submitForm('Log in');
+
+    // the second optional argument lets you override the default form field values
+    $client->submitForm('Log in', array(
+        'login' => 'my_user',
+        'password' => 'my_pass',
+        // to upload a file, the value must be the absolute file path
+        'file' => __FILE__,
+    ));
+
+    // you can override other form options too
+    $client->submitForm(
+        'Log in',
+        array('login' => 'my_user', 'password' => 'my_pass'),
+        // override the default form HTTP method
+        'PUT',
+        // override some $_SERVER parameters (e.g. HTTP headers)
+        array('HTTP_ACCEPT_LANGUAGE' => 'es')
+    );
+
+.. versionadded:: 4.2
+    The ``submitForm()`` method was introduced in Symfony 4.2.
+
+If you need the :class:`Symfony\\Component\\DomCrawler\\Form` object that
+provides access to the form properties (e.g. ``$form->getUri()``,
+``$form->getValues()``, ``$form->getFields()``), use this other method::
+
+    // ...
+
     // select the form and fill in some values
     $form = $crawler->selectButton('Log in')->form();
     $form['login'] = 'symfonyfan';
     $form['password'] = 'anypass';
 
-    // To upload a file, the value should be the absolute file path
-    $form['file'] = __FILE__;
-
     // submit that form
     $crawler = $client->submit($form);
 

testing.rst

@@ -422,21 +422,17 @@ returns a ``Crawler`` instance.
 Use the crawler to find DOM elements in the response. These elements can then
 be used to click on links and submit forms::
 
-    $link = $crawler->selectLink('Go elsewhere...')->link();
-    $crawler = $client->click($link);
+    $crawler = $client->clickLink('Go elsewhere...');
 
-    $form = $crawler->selectButton('validate')->form();
-    $crawler = $client->submit($form, array('name' => 'Fabien'));
+    $crawler = $client->submitForm('validate', array('name' => 'Fabien'));
 
-The ``click()`` and ``submit()`` methods both return a ``Crawler`` object.
+The ``clickLink()`` and ``submitForm()`` methods both return a ``Crawler`` object.
 These methods are the best way to browse your application as it takes care
 of a lot of things for you, like detecting the HTTP method from a form and
 giving you a nice API for uploading files.
 
-.. tip::
-
-    You will learn more about the ``Link`` and ``Form`` objects in the
-    :ref:`Crawler <testing-crawler>` section below.
+.. versionadded:: 4.2
+    The ``clickLink()`` and ``submitForm()`` methods were introduced in Symfony 4.2.
 
 The ``request()`` method can also be used to simulate form submissions directly
 or perform more complex requests. Some useful examples::
@@ -715,65 +711,68 @@ The Crawler can extract information from the nodes::
 Links
 ~~~~~
 
-To select links, you can use the traversing methods above or the convenient
-``selectLink()`` shortcut::
+Use the ``clickLink()`` method to click on the first link that contains the
+given text (or the first clickable image with that ``alt`` attribute)::
 
-    $crawler->selectLink('Click here');
+    $client = static::createClient();
+    $client->request('GET', '/post/hello-world');
 
-This selects all links that contain the given text, or clickable images for
-which the ``alt`` attribute contains the given text. Like the other filtering
-methods, this returns another ``Crawler`` object.
+    $client->clickLink('Click here');
 
-Once you've selected a link, you have access to a special ``Link`` object,
-which has helpful methods specific to links (such as ``getMethod()`` and
-``getUri()``). To click on the link, use the Client's ``click()`` method
-and pass it a ``Link`` object::
+If you need access to the :class:`Symfony\\Component\\DomCrawler\\Link` object
+that provides helpful methods specific to links (such as ``getMethod()`` and
+``getUri()``), use the ``selectLink()`` method instead:
 
-    $link = $crawler->selectLink('Click here')->link();
+    $client = static::createClient();
+    $crawler = $client->request('GET', '/post/hello-world');
 
+    $link = $crawler->selectLink('Click here')->link();
     $client->click($link);
 
 Forms
 ~~~~~
 
-Forms can be selected using their buttons, which can be selected with the
-``selectButton()`` method, just like links::
+Use the ``submitForm()`` method to submit the form that contains the given button::
 
-    $buttonCrawlerNode = $crawler->selectButton('submit');
+    $client = static::createClient();
+    $client->request('GET', '/post/hello-world');
+
+    $crawler = $client->submitForm('Add comment', array(
+       'comment_form[content]' => '...',
+    ));
+
+The first argument of ``submitForm()`` is the text content, ``id``, ``value`` or
+``name`` of any ``<button>`` or ``<input type="submit">`` included in the form.
+The second optional argument is used to override the default form field values.
 
 .. note::
 
     Notice that you select form buttons and not forms as a form can have several
     buttons; if you use the traversing API, keep in mind that you must look for a
     button.
 
-The ``selectButton()`` method can select ``button`` tags and submit ``input``
-tags. It uses several parts of the buttons to find them:
+If you need access to the :class:`Symfony\\Component\\DomCrawler\\Form` object
+that provides helpful methods specific to forms (such as ``getUri()``,
+``getValues()`` and ``getFields()``) use the ``selectButton()`` method instead::
 
-* The ``value`` attribute value;
-* The ``id`` or ``alt`` attribute value for images;
-* The ``id`` or ``name`` attribute value for ``button`` tags.
+    $client = static::createClient();
+    $crawler = $client->request('GET', '/post/hello-world');
 
-Once you have a Crawler representing a button, call the ``form()`` method
-to get a ``Form`` instance for the form wrapping the button node::
+    $buttonCrawlerNode = $crawler->selectButton('submit');
 
+    // select the form that contains this button
     $form = $buttonCrawlerNode->form();
 
-When calling the ``form()`` method, you can also pass an array of field values
-that overrides the default ones::
-
+    // you can also pass an array of field values that overrides the default ones
     $form = $buttonCrawlerNode->form(array(
         'my_form[name]'    => 'Fabien',
         'my_form[subject]' => 'Symfony rocks!',
     ));
 
-And if you want to simulate a specific HTTP method for the form, pass it as a
-second argument::
-
+    // you can pass a second argument to override the form HTTP method
     $form = $buttonCrawlerNode->form(array(), 'DELETE');
 
-The Client can submit ``Form`` instances::
-
+    // submit the Form object
     $client->submit($form);
 
 The field values can also be passed as a second argument of the ``submit()``
@@ -819,10 +818,11 @@ their type::
 
 .. tip::
 
-    The ``submit()`` method defines a third optional argument to add custom
-    HTTP headers when submitting the form::
+    The ``submit()`` and ``submitForm()`` methods define optional arguments to
+    add custom server parameters and HTTP headers when submitting the form::
 
         $client->submit($form, array(), array('HTTP_ACCEPT_LANGUAGE' => 'es'));
+        $client->submitForm($button, array(), 'POST', array('HTTP_ACCEPT_LANGUAGE' => 'es'));
 
     .. versionadded:: 4.1
         The feature to add custom HTTP headers was introduced in Symfony 4.1.