From d130be4e37a85a6e9615471fbe31ae84e80a6cdf Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Thu, 18 Jul 2019 10:27:18 +0200
Subject: [PATCH] [VarDumper] Documented setUpVarDumper() and
 tearDownVarDumper()

---
 components/var_dumper.rst | 40 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 37 insertions(+), 3 deletions(-)

diff --git a/components/var_dumper.rst b/components/var_dumper.rst
index 533ae68d9c8..9d271e961f2 100644
--- a/components/var_dumper.rst
+++ b/components/var_dumper.rst
@@ -248,6 +248,21 @@ This will provide you with two new assertions:
     is like the previous method but accepts placeholders in the expected dump,
     based on the ``assertStringMatchesFormat()`` method provided by PHPUnit.
 
+The ``VarDumperTestTrait`` also includes these other methods:
+
+:method:`Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait::setUpVarDumper`
+    is used to configure the available casters and their options, which is a way
+    to only control the fields you're expecting and allows writing concise tests.
+
+:method:`Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait::tearDownVarDumper`
+    is called automatically after each case to reset the custom configuration
+    made in ``setUpVarDumper()``.
+
+.. versionadded:: 4.4
+
+    The ``setUpVarDumper()`` and ``tearDownVarDumper()`` methods were introduced
+    in Symfony 4.4.
+
 Example::
 
     use PHPUnit\Framework\TestCase;
@@ -257,14 +272,33 @@ Example::
     {
         use VarDumperTestTrait;
 
+        protected function setUp()
+        {
+            $casters = [
+                \DateTimeInterface::class => static function (\DateTimeInterface $date, array $a, Stub $stub): array {
+                    $stub->class = 'DateTime';
+                    return ['date' => $date->format('d/m/Y')];
+                },
+            ];
+
+            $flags = CliDumper::DUMP_LIGHT_ARRAY | CliDumper::DUMP_COMMA_SEPARATOR;
+
+            // this configures the casters & flags to use for all the tests in this class.
+            // If you need custom configurations per test rather than for the whole class,
+            // call this setUpVarDumper() method from those tests instead.
+            $this->setUpVarDumper($casters, $flags);
+        }
+
         public function testWithDumpEquals()
         {
             $testedVar = [123, 'foo'];
 
+            // the expected dump contents don't have the default VarDumper structure
+            // because of the custom casters and flags used in the test
             $expectedDump = <<<EOTXT
-    array:2 [
-      0 => 123
-      1 => "foo"
+    [
+      123,
+      "foo",
     ]
     EOTXT;