[symfony#4243] Tweaks to the new var-dumper component

Author: weaverryan

components/var_dumper/advanced.rst

@@ -50,28 +50,33 @@ corresponding Data object could represent only a subset of the cloned variable.
 Before calling :method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::cloneVar`,
 you can configure these limits:
 
-* :method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::setMaxItems`
-  configures the maximum number of items that will be cloned
-  *past the first nesting level*. Items are counted using a breadth-first
-  algorithm so that lower level items have higher priority than deeply nested
-  items;
-* :method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::setMaxString`
-  configures the maximum number of characters that will be cloned before
-  cutting overlong strings;
-* in both cases, specifying `-1` removes any limit.
+:method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::setMaxItems`
+    configures the maximum number of items that will be cloned
+    *past the first nesting level*. Items are counted using a breadth-first
+    algorithm so that lower level items have higher priority than deeply nested
+    items;
+
+:method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::setMaxString`
+    configures the maximum number of characters that will be cloned before
+    cutting overlong strings;
+
+In both cases, specifying ``-1`` removes any limit.
 
 Before dumping it, you can further limit the resulting
-:class:`Symfony\\Component\\VarDumper\\Cloner\\Data` object by calling its
-:method:`Symfony\\Component\\VarDumper\\Cloner\\Data::getLimitedClone`
-method:
-
-* the first ``$maxDepth`` argument allows limiting dumps in the depth dimension,
-* the second ``$maxItemsPerDepth`` limits the number of items per depth level,
-* and the last ``$useRefHandles`` defaults to ``true``, but allows removing
-  internal objects' handles for sparser output,
-* but unlike the previous limits on cloners that remove data on purpose,
-  these can be changed back and forth before dumping since they do not affect
-  the intermediate representation internally.
+:class:`Symfony\\Component\\VarDumper\\Cloner\\Data` object using the following methods:
+
+:method:`Symfony\\Component\\VarDumper\\Cloner\\Data::withMaxDepth`
+    Allows limiting dumps in the depth dimension.
+
+:method:`Symfony\\Component\\VarDumper\\Cloner\\Data::withMaxItemsPerDepth`
+    Limits the number of items per depth level.
+
+:method:`Symfony\\Component\\VarDumper\\Cloner\\Data::withRefHandles`
+    Allows removing internal objects' handles for sparser output (useful for tests).
+
+Unlike the previous limits on cloners that remove data on purpose, these can
+be changed back and forth before dumping since they do not affect the
+intermediate representation internally.
 
 .. note::
 

components/var_dumper/introduction.rst

@@ -122,6 +122,53 @@ original value. You can configure the limits in terms of:
             <config max-items="250" max-string-length="-1" />
         </container>
 
+Using the VarDumper Component in your PHPUnit Test Suite
+--------------------------------------------------------
+
+.. versionadded:: 2.7
+    The :class:`Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait` was
+    introduced in Symfony 2.7.
+
+The VarDumper component provides
+:class:`a trait <Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait>`
+that can help writing some of your tests for PHPUnit.
+
+This will provide you with two new assertions:
+
+:method:`Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait::assertDumpEquals`
+    verifies that the dump of the variable given as the second argument matches
+    the expected dump provided as a string in the first argument.
+
+:method:`Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait::assertDumpMatchesFormat`
+    is like the previous method but accepts placeholders in the expected dump,
+    based on the ``assertStringMatchesFormat`` method provided by PHPUnit.
+
+Example::
+
+    class ExampleTest extends \PHPUnit_Framework_TestCase
+    {
+        use \Symfony\Component\VarDumper\Test\VarDumperTestTrait;
+
+        public function testWithDumpEquals()
+        {
+            $testedVar = array(123, 'foo');
+
+            $expectedDump = <<<EOTXT
+    array:2 [
+      0 => 123
+      1 => "foo"
+    ]
+    EOTXT;
+
+            $this->assertDumpEquals($expectedDump, $testedVar);
+        }
+    }
+
+.. tip::
+
+    If you still use PHP 5.3, you can extend the
+    :class:`Symfony\\Component\\VarDumper\\Test\\VarDumperTestClass` instead.
+
 Dump Examples and Output
 ------------------------