[#2012] Proofreading the new unit testing form types chapter

Author: weaverryan

cookbook/form/index.rst

@@ -11,3 +11,4 @@ Form
     create_custom_field_type
     create_form_type_extension
     use_virtuals_forms
+    unit_testing

cookbook/form/unit_testing.rst

@@ -1,36 +1,35 @@
 .. index::
    single: Form; Form testing
 
-Testing forms
-=============
+How to Unit Test your Forms
+===========================
 
-The Form Component consists of 3 core objects: a FormType (implementing
+The Form Component consists of 3 core objects: a form type (implementing
 :class:`Symfony\\Component\\Form\\FormTypeInterface`), the
 :class:`Symfony\\Component\\Form\\Form` and the
 :class:`Symfony\\Component\\Form\\FormView`.
 
-The only class that is usually manipulated by programmers is the FormType class
-which serves as a form blueprint. It is used to generate the Form and the
-FormView. You could test it directly by mocking its interactions with the
+The only class that is usually manipulated by programmers is the form type class
+which serves as a form blueprint. It is used to generate the ``Form`` and the
+``FormView``. You could test it directly by mocking its interactions with the
 factory but it would be complex. It is better to pass it to FormFactory like it
-is done in a real application. It is simple to bootstrap and we trust Symfony
-components enough to use them as a testing base.
+is done in a real application. It is simple to bootstrap and you can trust
+the Symfony components enough to use them as a testing base.
 
 There is already a class that you can benefit from for simple FormTypes
-testing, the
-:class:`Symfony\\Component\\Form\\Tests\\Extension\\Core\\Type\\TypeTestCase`.
-It is used to test the core types and you can use it to test yours too.
+testing: :class:`Symfony\\Component\\Form\\Tests\\Extension\\Core\\Type\\TypeTestCase`.
+It is used to test the core types and you can use it to test your types too.
 
 .. note::
-    
+
     Depending on the way you installed your Symfony or Symfony Form Component
     the tests may not be downloaded. Use the --prefer-source option with
     composer if this is the case.
 
 The Basics
 ----------
 
-The simplest TypeTestCase implementation looks like the following::
+The simplest ``TypeTestCase`` implementation looks like the following::
 
     // src/Acme/TestBundle/Tests/Form/Type/TestedTypeTests.php
     namespace Acme\TestBundle\Tests\Form\Type;
@@ -70,34 +69,32 @@ The simplest TypeTestCase implementation looks like the following::
 
 So, what does it test? Let's explain it line by line.
 
-First we verify if the FormType compiles. This includes basic class
-inheritance, the buildForm function and options resolution. This should
+First you verify if the ``FormType`` compiles. This includes basic class
+inheritance, the ``buildForm`` function and options resolution. This should
 be the first test you write::
 
     $type = new TestedType();
     $form = $this->factory->create($type);
 
-
-This test checks if none of your DataTransformers used by the form
-failed. The isSynchronized is only set to false if a DataTransformer
-throws an exception::
+This test checks that none of your data transformers used by the form
+failed. The :method:`Symfony\\Component\\Form\\FormInterface::isSynchronized``
+method is only set to ``false`` if a data transformer throws an exception::
 
     $form->bind($formData);
     $this->assertTrue($form->isSynchronized());
 
 .. note::
 
-    We don't check the validation – it is done by a listener that is not
+    Don't test the validation: it is applied by a listener that is not
     active in the test case and it relies on validation configuration.
-    You would need to bootstrap the whole kernel to do it. Write
-    separate tests to check your validators.
+    Instead, unit test your custom constraints directly.
 
-Next we verify the binding and mapping of the form. The test below
+Next, verify the binding and mapping of the form. The test below
 checks if all the fields are correctly specified::
 
     $this->assertEquals($object, $form->getData());
 
-At last we check the creation of the FormView. You should check if all
+Finally, check the creation of the ``FormView``. You should check if all
 widgets you want to display are available in the children property::
 
     $view = $form->createView();
@@ -107,18 +104,18 @@ widgets you want to display are available in the children property::
         $this->assertArrayHasKey($key, $children);
     }
 
-Adding a Type your form depends on
+Adding a Type your Form depends on
 ----------------------------------
 
 Your form may depend on other types that are defined as services. It
-would be defined like this::
+might look like this::
 
     // src/Acme/TestBundle/Form/Type/TestedType.php
 
     // ... the buildForm method
     $builder->add('acme_test_child_type');
 
-To create your form correctly you need to make the type available to the
+To create your form correctly, you need to make the type available to the
 form factory in your test. The easiest way is to register it manually
 before creating the parent form::
 
@@ -137,7 +134,7 @@ before creating the parent form::
 
             $type = new TestedType();
             $form = $this->factory->create($type);
-            
+
             // ... your test
         }
     }
@@ -148,15 +145,15 @@ before creating the parent form::
     be getting errors that are not related to the form you are currently
     testing but to its children.
 
-Adding custom extensions
+Adding custom Extensions
 ------------------------
 
-It often happens that you use some options that are added by form
-extensions.  One of the cases may be the ValidatorExtension with its
-invalid_message option.  The TypeTestCase loads only the core Form
-Extension so an “Invalid option” exception will be raised if you try to
-use it for testing a class that depends on other extensions. You need
-add the dependencies to the Factory object::
+It often happens that you use some options that are added by
+:doc:`form extensions<cookbook/form/create_form_type_extension>`. One of the
+cases may be the ``ValidatorExtension`` with its ``invalid_message`` option.
+The ``TypeTestCase`` loads only the core form extension so an "Invalid option"
+exception will be raised if you try to use it for testing a class that depends
+on other extensions. You need add those extensions to the factory object::
 
     // src/Acme/TestBundle/Tests/Form/Type/TestedTypeTests.php
     namespace Acme\TestBundle\Tests\Form\Type;
@@ -193,11 +190,11 @@ add the dependencies to the Factory object::
         // ... your tests
     } 
 
-Testing against different sets of data
+Testing against different Sets of Data
 --------------------------------------
 
-If you are not familiar yet with PHPUnit's `data providers`_ it would be
-a good opportunity to use them:: 
+If you are not familiar yet with PHPUnit's `data providers`_, this might be
+a good opportunity to use them::
 
     // src/Acme/TestBundle/Tests/Form/Type/TestedTypeTests.php
     namespace Acme\TestBundle\Tests\Form\Type;
@@ -244,6 +241,6 @@ 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.  
+be synchronized with the given set of data or not etc.
 
-.. _`data providers`: http://www.phpunit.de/manual/3.7/en/writing-tests-for-phpunit.html#writing-tests-for-phpunit.data-providers
+.. _`data providers`: http://www.phpunit.de/manual/current/en/writing-tests-for-phpunit.html#writing-tests-for-phpunit.data-providers

cookbook/map.rst.inc

@@ -81,6 +81,7 @@
   * :doc:`/cookbook/form/create_custom_field_type`
   * :doc:`/cookbook/form/create_form_type_extension`
   * :doc:`/cookbook/form/use_virtuals_forms`
+  * :doc:`/cookbook/form/unit_testing`
   * (validation) :doc:`/cookbook/validation/custom_constraint`
   * (doctrine) :doc:`/cookbook/doctrine/file_uploads`