docs(json-path): add testing part doc for the component

vinceAmstoutz · vinceAmstoutz · commit 85bc74a9a2f9 · 2025-06-19T10:52:56.000+02:00
Updates the documentation to document `JsonPathAssertionsTrait` and related constraints (closes #20977). Complete the previous work done in #21078. # Conflicts: # components/json_path.rst
diff --git a/components/json_path.rst b/components/json_path.rst
@@ -81,14 +81,12 @@ the data. This method always returns an array of matching values.
 Querying with Expressions
 -------------------------
 
-The primary way to query the JSON is by passing a JSONPath expression string
-to the :method:`Symfony\\Component\\JsonPath\\JsonCrawler::find` method.
+The primary way to query the JSON is by passing a JSONPath expression string to the :method:`Symfony\\Component\\JsonPath\\JsonCrawler::find` method.
 
 Accessing a Specific Property
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use dot-notation for object keys and square brackets for array indices. The root
-of the document is represented by ``$``::
+Use dot-notation for object keys and square brackets for array indices. The root of the document is represented by ``$``::
 
     // Get the title of the first book in the store
     $titles = $crawler->find('$.store.book[0].title');
@@ -157,53 +155,51 @@ the correct escaping of keys and values, preventing syntax errors::
 The :class:`Symfony\\Component\\JsonPath\\JsonPath` class provides several methods to build your query:
 
 * :method:`Symfony\\Component\\JsonPath\\JsonPath::key`
-    Adds a key selector. The key name will be properly escaped::
+  Adds a key selector. The key name will be properly escaped::
 
-        // Creates the path '$["key\"with\"quotes"]'
-        $path = (new JsonPath())->key('key"with"quotes');
+      // Creates the path '$["key\"with\"quotes"]'
+      $path = (new JsonPath())->key('key"with"quotes');
 
 * :method:`Symfony\\Component\\JsonPath\\JsonPath::deepScan`
-    Adds the descendant operator ``..`` to perform a recursive search from the
-    current point in the path::
+  Adds the descendant operator ``..`` to perform a recursive search from the current point in the path::
 
-        // Get all prices in the store: '$["store"]..["price"]'
-        $path = (new JsonPath())->key('store')->deepScan()->key('price');
+      // Get all prices in the store: '$["store"]..["price"]'
+      $path = (new JsonPath())->key('store')->deepScan()->key('price');
 
 * :method:`Symfony\\Component\\JsonPath\\JsonPath::all`
-    Adds the wildcard operator ``[*]`` to select all items in an array or object::
+  Adds the wildcard operator ``[*]`` to select all items in an array or object::
 
-        // Creates the path '$["store"]["book"][*]'
-        $path = (new JsonPath())->key('store')->key('book')->all();
+      // Creates the path '$["store"]["book"][*]'
+      $path = (new JsonPath())->key('store')->key('book')->all();
 
 * :method:`Symfony\\Component\\JsonPath\\JsonPath::index`
-    Adds an array index selector.
+  Adds an array index selector.
 
 * :method:`Symfony\\Component\\JsonPath\\JsonPath::first` / :method:`Symfony\\Component\\JsonPath\\JsonPath::last`
-    Shortcuts for ``index(0)`` and ``index(-1)`` respectively::
+  Shortcuts for ``index(0)`` and ``index(-1)`` respectively::
 
-        // Get the last book: '$["store"]["book"][-1]'
-        $path = (new JsonPath())->key('store')->key('book')->last();
+     // Get the last book: '$["store"]["book"][-1]'
+     $path = (new JsonPath())->key('store')->key('book')->last();
 
 * :method:`Symfony\\Component\\JsonPath\\JsonPath::slice`
-    Adds an array slice selector ``[start:end:step]``::
+  Adds an array slice selector ``[start:end:step]``::
 
-        // Get books from index 1 up to (but not including) index 3
-        // Creates the path '$["store"]["book"][1:3]'
-        $path = (new JsonPath())->key('store')->key('book')->slice(1, 3);
+      // Get books from index 1 up to (but not including) index 3
+      // Creates the path '$["store"]["book"][1:3]'
+      $path = (new JsonPath())->key('store')->key('book')->slice(1, 3);
 
-        // Get every second book from the first four books
-        // Creates the path '$["store"]["book"][0:4:2]'
-        $path = (new JsonPath())->key('store')->key('book')->slice(0, 4, 2);
+      // Get every second book from the first four books
+      // Creates the path '$["store"]["book"][0:4:2]'
+      $path = (new JsonPath())->key('store')->key('book')->slice(0, 4, 2);
 
 * :method:`Symfony\\Component\\JsonPath\\JsonPath::filter`
-    Adds a filter expression. The expression string is the part that goes inside
-    the ``?()`` syntax::
+  Adds a filter expression. The expression string is the part that goes inside the ``?()`` syntax::
 
-        // Get expensive books: '$["store"]["book"][?(@.price > 20)]'
-        $path = (new JsonPath())
-            ->key('store')
-            ->key('book')
-            ->filter('@.price > 20');
+      // Get expensive books: '$["store"]["book"][?(@.price > 20)]'
+      $path = (new JsonPath())
+          ->key('store')
+          ->key('book')
+          ->filter('@.price > 20');
 
 Advanced Querying
 -----------------
@@ -237,52 +233,52 @@ The component provides a set of PHPUnit assertions to make testing JSON data mor
 The trait provides the following assertion methods:
 
 * :method:`Symfony\\Component\\JsonPath\\Test\\JsonPathAssertionsTrait::assertJsonPathCount`
-    Asserts that the number of elements found by the JSONPath expression matches an expected count::
+  Asserts that the number of elements found by the JSONPath expression matches an expected count::
 
-        $json = '{"a": [1, 2, 3]}';
-        self::assertJsonPathCount(3, '$.a[*]', $json);
+      $json = '{"a": [1, 2, 3]}';
+      self::assertJsonPathCount(3, '$.a[*]', $json);
 
 * :method:`Symfony\\Component\\JsonPath\\Test\\JsonPathAssertionsTrait::assertJsonPathEquals`
-    Asserts that the result of a JSONPath expression is equal (``==``) to an expected value. This assertion uses type coercion::
+  Asserts that the result of a JSONPath expression is equal to an expected value.The comparison uses ``==`` (type coercion) instead of ``===``::
 
-        $json = '{"a": [1, 2, 3]}';
+      $json = '{"a": [1, 2, 3]}';
 
-        // passes because "1" == 1
-        self::assertJsonPathEquals(['1'], '$.a[0]', $json);
+      // passes because "1" == 1
+      self::assertJsonPathEquals(['1'], '$.a[0]', $json);
 
 * :method:`Symfony\\Component\\JsonPath\\Test\\JsonPathAssertionsTrait::assertJsonPathNotEquals`
-    Asserts that the result of a JSONPath expression is not equal (``!=``) to an expected value::
+  Asserts that the result of a JSONPath expression is not equal to an expected value.The comparison uses ``!=`` (type coercion) instead of ``!==``::
 
-        $json = '{"a": [1, 2, 3]}';
-        self::assertJsonPathNotEquals([42], '$.a[0]', $json);
+      $json = '{"a": [1, 2, 3]}';
+      self::assertJsonPathNotEquals([42], '$.a[0]', $json);
 
 * :method:`Symfony\\Component\\JsonPath\\Test\\JsonPathAssertionsTrait::assertJsonPathSame`
-    Asserts that the result of a JSONPath expression is identical (``===``) to an expected value. This is a strict comparison and does not perform type coercion::
+  Asserts that the result of a JSONPath expression is identical (``===``) to an expected value. This is a strict comparison and does not perform type coercion::
 
-        $json = '{"a": [1, 2, 3]}';
+      $json = '{"a": [1, 2, 3]}';
 
-        // fails because "1" !== 1
-        // self::assertJsonPathSame(['1'], '$.a[0]', $json);
+      // fails because "1" !== 1
+      // self::assertJsonPathSame(['1'], '$.a[0]', $json);
 
-        self::assertJsonPathSame([1], '$.a[0]', $json);
+      self::assertJsonPathSame([1], '$.a[0]', $json);
 
 * :method:`Symfony\\Component\\JsonPath\\Test\\JsonPathAssertionsTrait::assertJsonPathNotSame`
-    Asserts that the result of a JSONPath expression is not identical (``!==``) to an expected value::
+  Asserts that the result of a JSONPath expression is not identical (``!==``) to an expected value::
 
-        $json = '{"a": [1, 2, 3]}';
-        self::assertJsonPathNotSame(['1'], '$.a[0]', $json);
+      $json = '{"a": [1, 2, 3]}';
+      self::assertJsonPathNotSame(['1'], '$.a[0]', $json);
 
 * :method:`Symfony\\Component\\JsonPath\\Test\\JsonPathAssertionsTrait::assertJsonPathContains`
-    Asserts that a given value is found within the array of results from the JSONPath expression::
+  Asserts that a given value is found within the array of results from the JSONPath expression::
 
-        $json = '{"tags": ["php", "symfony", "json"]}';
-        self::assertJsonPathContains('symfony', '$.tags[*]', $json);
+      $json = '{"tags": ["php", "symfony", "json"]}';
+      self::assertJsonPathContains('symfony', '$.tags[*]', $json);
 
 * :method:`Symfony\\Component\\JsonPath\\Test\\JsonPathAssertionsTrait::assertJsonPathNotContains`
-    Asserts that a given value is NOT found within the array of results from the JSONPath expression::
+  Asserts that a given value is NOT found within the array of results from the JSONPath expression::
 
-        $json = '{"tags": ["php", "symfony", "json"]}';
-        self::assertJsonPathNotContains('java', '$.tags[*]', $json);
+      $json = '{"tags": ["php", "symfony", "json"]}';
+      self::assertJsonPathNotContains('java', '$.tags[*]', $json);
 
 Error Handling
 --------------
