From a9260297ef2b92f67aea4c79613b64b34561853d Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Thu, 19 Jul 2018 15:59:47 +0200
Subject: [PATCH] Documented PHPUnit data providers

---
 best_practices/tests.rst |  3 ++-
 form/unit_testing.rst    | 58 ++++------------------------------------
 testing.rst              | 36 +++++++++++++++++++++++++
 3 files changed, 43 insertions(+), 54 deletions(-)

diff --git a/best_practices/tests.rst b/best_practices/tests.rst
index 65e8f539590..42a40b1a7c9 100644
--- a/best_practices/tests.rst
+++ b/best_practices/tests.rst
@@ -26,7 +26,8 @@ functional tests, you can quickly spot any big errors before you deploy them:
     Define a functional test that at least checks if your application pages
     are successfully loading.
 
-A functional test can be as easy as this::
+A functional test like this is simple to implement thanks to
+:ref:`PHPUnit data providers <testing-data-providers>`::
 
     // src/AppBundle/Tests/ApplicationAvailabilityFunctionalTest.php
     namespace AppBundle\Tests;
diff --git a/form/unit_testing.rst b/form/unit_testing.rst
index 5499331b358..3b3572cfc56 100644
--- a/form/unit_testing.rst
+++ b/form/unit_testing.rst
@@ -112,6 +112,11 @@ widgets you want to display are available in the children property::
         $this->assertArrayHasKey($key, $children);
     }
 
+.. tip::
+
+    Use :ref:`PHPUnit data providers <testing-data-providers>` to test multiple
+    form conditions using the same test code.
+
 Testings Types from the Service Container
 -----------------------------------------
 
@@ -212,56 +217,3 @@ allows you to return a list of extensions to register::
 
         // ... your tests
     }
-
-Testing against Different Sets of Data
---------------------------------------
-
-If you are not familiar yet with PHPUnit's `data providers`_, this might be
-a good opportunity to use them::
-
-    // src/AppBundle/Tests/Form/Type/TestedTypeTest.php
-    namespace AppBundle\Tests\Form\Type;
-
-    use AppBundle\Form\Type\TestedType;
-    use Symfony\Component\Form\Test\TypeTestCase;
-
-    class TestedTypeTest extends TypeTestCase
-    {
-        /**
-         * @dataProvider getValidTestData
-         */
-        public function testForm($data)
-        {
-            // ... your test
-        }
-
-        public function getValidTestData()
-        {
-            return array(
-                array(
-                    'data' => array(
-                        'test' => 'test',
-                        'test2' => 'test2',
-                    ),
-                ),
-                array(
-                    'data' => array(),
-                ),
-                array(
-                    'data' => array(
-                        'test' => null,
-                        'test2' => null,
-                    ),
-                ),
-            );
-        }
-    }
-
-The code above will run your test three times with 3 different sets of
-data. This allows for decoupling the test fixtures from the tests and
-easily testing against multiple sets of data.
-
-You can also pass another argument, such as a boolean if the form has to
-be synchronized with the given set of data or not etc.
-
-.. _`data providers`: https://phpunit.de/manual/current/en/writing-tests-for-phpunit.html#writing-tests-for-phpunit.data-providers
diff --git a/testing.rst b/testing.rst
index 868d9f862ea..f47268a647a 100644
--- a/testing.rst
+++ b/testing.rst
@@ -294,6 +294,41 @@ document::
         // ...or simply check that the response is a redirect to any URL
         $this->assertTrue($client->getResponse()->isRedirect());
 
+.. _testing-data-providers:
+
+Testing against Different Sets of Data
+--------------------------------------
+
+It's common to have to execute the same test against different sets of data to
+check the multiple conditions code must handle. This is solved with PHPUnit's
+`data providers`_, which work both for unit and functional tests.
+
+First, add one or more arguments to your test method and use them inside the
+test code. Then, define another method which returns a nested array with the
+arguments to use on each test run. Lastly, add the ``@dataProvider`` annotation
+to associate both methods::
+
+    /**
+     * @dataProvider provideUrls
+     */
+    public function testPageIsSuccessful($url)
+    {
+        $client = self::createClient();
+        $client->request('GET', $url);
+
+        $this->assertTrue($client->getResponse()->isSuccessful());
+    }
+
+    public function provideUrls()
+    {
+        return array(
+            array('/'),
+            array('/blog'),
+            array('/contact'),
+            // ...
+        );
+    }
+
 .. index::
    single: Tests; Client
 
@@ -927,3 +962,4 @@ Learn more
 .. _`documentation`: https://phpunit.de/manual/current/en/
 .. _`PHPUnit Bridge component`: https://symfony.com/components/PHPUnit%20Bridge
 .. _`$_SERVER`: https://php.net/manual/en/reserved.variables.server.php
+.. _`data providers`: https://phpunit.de/manual/current/en/writing-tests-for-phpunit.html#writing-tests-for-phpunit.data-providers