From abbb9ef39edd89e7f50810d197a3015fde532833 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 15 Jul 2018 10:50:21 +0200 Subject: [PATCH 1/6] Added docs for clickLink() and submitForm() --- testing.rst | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/testing.rst b/testing.rst index cea8746c9d7..20a3dbca62b 100644 --- a/testing.rst +++ b/testing.rst @@ -387,21 +387,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 ` 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:: @@ -676,15 +672,17 @@ 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. -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:: +Once you've selected a link, you have access to a special +:class:`Symfony\\Component\\DomCrawler\\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:: $link = $crawler->selectLink('Click here')->link(); - $client->click($link); + // equivalent code when you don't need access to the Link object: + // $client->clickLink('Click here'); + Forms ~~~~~ @@ -707,7 +705,8 @@ tags. It uses several parts of the buttons to find them: * The ``id`` or ``name`` attribute value for ``button`` tags. Once you have a Crawler representing a button, call the ``form()`` method -to get a ``Form`` instance for the form wrapping the button node:: +to get a :class:`Symfony\\Component\\DomCrawler\\Form` instance for the form +wrapping the button node:: $form = $buttonCrawlerNode->form(); @@ -736,6 +735,12 @@ method:: 'my_form[subject]' => 'Symfony rocks!', )); + // equivalent code when you don't need access to the Form object: + // $client->submitForm('submit', array( + // 'my_form[name]' => 'Fabien', + // 'my_form[subject]' => 'Symfony rocks!', + // )); + For more complex situations, use the ``Form`` instance as an array to set the value of each field individually:: From 962f310c5eb030f643b038c3285d499ca6046a04 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 18 Jul 2018 09:43:10 +0200 Subject: [PATCH 2/6] Finished the docs --- components/browser_kit.rst | 22 ++++++++++++++++++++++ testing.rst | 5 +++-- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/components/browser_kit.rst b/components/browser_kit.rst index f36b566c2cf..4589386b125 100644 --- a/components/browser_kit.rst +++ b/components/browser_kit.rst @@ -109,6 +109,15 @@ performs the needed HTTP GET request to simulate the link click:: $link = $crawler->selectLink('Go elsewhere...')->link(); $client->click($link); +If you don't need the low level ``Link`` object, you can use the ``clickLink()`` +shortcut to click links more easily:: + + // ... + $client->clickLink('Go elsewhere...'); + +.. versionadded:: 4.2 + The ``clickLink()`` method was introduced in Symfony 4.2. + Submitting Forms ~~~~~~~~~~~~~~~~ @@ -136,6 +145,19 @@ method (which makes the needed HTTP POST request to submit the form contents):: // submit that form $crawler = $client->submit($form); +If you don't need the low level ``Form`` object, you can use the +``submitForm()`` shortcut to submit the form more easily:: + + // ... + $client->submitForm('Log in', [ + 'login' => 'symfonyfan', + 'password' => 'anypass', + 'file' => __FILE__, + ]); + +.. versionadded:: 4.2 + The ``submitForm()`` method was introduced in Symfony 4.2. + Cookies ------- diff --git a/testing.rst b/testing.rst index 20a3dbca62b..747f4ff6897 100644 --- a/testing.rst +++ b/testing.rst @@ -776,10 +776,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. From 59abd1574036c0ac8f3bf59d8d1ba7d18eb0b50d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 18 Jul 2018 10:10:09 +0200 Subject: [PATCH 3/6] Explain the shortcuts first --- components/browser_kit.rst | 89 +++++++++++++++++++++++--------------- 1 file changed, 53 insertions(+), 36 deletions(-) diff --git a/components/browser_kit.rst b/components/browser_kit.rst index 4589386b125..1c6a0568f46 100644 --- a/components/browser_kit.rst +++ b/components/browser_kit.rst @@ -97,67 +97,84 @@ 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; + use Acme\Client; $client = new Client(); - $crawler = $client->request('GET', '/product/123'); - $link = $crawler->selectLink('Go elsewhere...')->link(); - $client->click($link); + $client->request('GET', '/product/123'); -If you don't need the low level ``Link`` object, you can use the ``clickLink()`` -shortcut to click links more easily:: - - // ... - $client->clickLink('Go elsewhere...'); + $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