How to add a JSON assertion in JMeter

JSON APIs can return HTTP 200 while still sending the wrong field, an empty branch, or a value from the wrong order state. A JMeter JSON Assertion checks the sampler response as JSON so the sample fails when the selected path or value does not match the API contract being tested.

The assertion parses the response first, then evaluates a JSON Path expression such as $.order.status. A missing path fails the sample, and selecting Additionally assert value requires the matched value to equal the expected value or match the selected regular expression mode.

A validation copy with one matching response and one mismatching response keeps the failure boundary visible before the assertion moves into a larger load plan. The matching row should stay success=true, while the controlled mismatch should show success=false with the JSON Path assertion message.

1. Open a validation copy of the .jmx test plan in the JMeter GUI.
2. Select the sampler that returns the JSON response.
3. Add JSON Assertion from Add → Assertions → JSON Assertion.
4. Name the assertion for the response field it checks.

   Name: JSON Assertion - order status is ready

5. Enter the JSON path that should exist in the response.

   Assert JSON Path exists: $.order.status

   Use a path that points to the value being asserted, not only to the parent object. For arrays or broad selectors that can return multiple values, set an expected value so JMeter checks the returned content instead of only the selector result.
   Tool: JSONPath Tester

6. Select Additionally assert value and enter the expected value.

   Additionally assert value: selected
   Expected Value: ready
   Match as regular expression: cleared
   Expect null: cleared
   Invert assertion: cleared

   Select Expect null only when the expected JSON value is literally null. Use Invert assertion when the sampler should fail if the path and value match.

7. Apply the same assertion to a controlled mismatch in the validation copy.

   Matching response: {"order":{"id":"A100","status":"ready"}}
   Mismatching response: {"order":{"id":"A101","status":"queued"}}

   A mock endpoint, disposable fixture, or JSR223 sampler can supply the mismatch. Remove the artificial failure branch before the plan becomes a normal load run.

8. Save the validation copy.

   json-assertion-add.jmx

9. Run a one-user non-GUI validation pass.

   $ jmeter -n -t json-assertion-add.jmx -l json-assertion-results.jtl
   Creating summariser <summary>
   Created the tree successfully using json-assertion-add.jmx
   Starting standalone test @ 2026 Jun 30 01:29:15 GMT
   Waiting for possible Shutdown/StopTestNow/HeapDump/ThreadDump message on port 4445
   summary =      2 in 00:00:00 =    5.6/s Avg:   157 Min:     9 Max:   306 Err:     1 (50.00%)
   Tidying up ...
   ... end of run

   The one error is expected for this validation copy because the mismatch sampler proves that the assertion can fail a bad JSON value.
   Related: How to run a JMeter test from the command line

10. Check the result file for the passing row and assertion message.

    $ cat json-assertion-results.jtl
    timeStamp,elapsed,label,responseCode,responseMessage,threadName,dataType,success,failureMessage,bytes,sentBytes,grpThreads,allThreads,URL,Latency,IdleTime,Connect
    1782782955401,306,GET order status matching response,200,OK,JSON assertion users 1-1,text,true,,40,0,1,1,null,0,0,0
    1782782955727,9,GET order status mismatching response,200,OK,JSON assertion users 1-1,text,false,"Value in json path '$.order.status' expected to be 'ready', but found 'queued'",41,0,1,1,null,0,0,0

11. Keep the assertion under the real API sampler and remove the controlled mismatch.

    After the mismatch branch is removed, a smoke run against the accepted response should show success=true for the asserted sampler. A false row with a JSON Path message means the API response, selector, or expected value no longer matches.