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

vinceAmstoutz · vinceAmstoutz · commit b1c234092516 · 2025-06-17T10:51:06.000+02:00
Updates the documentation to document `JsonPathAssertionsTrait` and related constraints (closes #20977). Complete the previous work done in #21078.
diff --git a/components/json_path.rst b/components/json_path.rst
@@ -213,6 +213,78 @@ filters, please refer to the `Querying with Expressions`_ section above. All the
 features are supported and can be combined with the programmatic builder where
 appropriate (e.g., inside a ``filter()`` expression).
 
+Testing with JSON Assertions
+----------------------------
+
+The component provides a set of PHPUnit assertions to make testing JSON data more convenient. To use them, include the
+:class:`Symfony\\Component\\JsonPath\\Test\\JsonPathAssertionsTrait` in your test class::
+
+    use PHPUnit\Framework\TestCase;
+    use Symfony\Component\JsonPath\Test\JsonPathAssertionsTrait;
+
+    class MyTest extends TestCase
+    {
+        use JsonPathAssertionsTrait;
+
+        public function testSomething(): void
+        {
+            $json = '{"books": [{"title": "A"}, {"title": "B"}]}';
+
+            self::assertJsonPathCount(2, '$.books[*]', $json);
+        }
+    }
+
+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::
+
+        $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::
+
+        $json = '{"a": [1, 2, 3]}';
+
+        // 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::
+
+        $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::
+
+        $json = '{"a": [1, 2, 3]}';
+
+        // fails because "1" !== 1
+        // 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::
+
+        $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::
+
+        $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::
+
+        $json = '{"tags": ["php", "symfony", "json"]}';
+        self::assertJsonPathNotContains('java', '$.tags[*]', $json);
+
+
 Error Handling
 --------------
 
