docs: storing expected results of tests as JSON

docs/dev/how-to-write-and-run-tests.md

@@ -18,7 +18,7 @@ We have some helpers for tests.
 
 See mainly:
 * [Test.pm](https://openfoodfacts.github.io/openfoodfacts-server/dev/ref-perl-pod/ProductOpener/Test.html) (notably `init_expected_results` and `compare_to_expected_results`)
-* [TestAPI.pm](https://openfoodfacts.github.io/openfoodfacts-server/dev/ref-perl-pod/ProductOpener/APITest.html)
+* [APITest.pm](https://openfoodfacts.github.io/openfoodfacts-server/dev/ref-perl-pod/ProductOpener/APITest.html)
 
 and other modules with Test in their name !
 
@@ -43,7 +43,21 @@ You can read other tests to understand how we write them (inspire yourself from
 
 One effective way is to create a list of tests each represented by a hashmap with inputs and expected outputs and run them in a loop. Add an `id` and/or a `desc` (description) and use it as last argument to check functions (like `ok`, `is`, …) to easily see tests running and identify failing tests.
 
-If your outputs are consequent, you might use json files (one per tests), stored on disk. See tests using `init_expected_results` (and see below to refresh those files).
+### Using JSON files to save expected results of tests
+
+If the output of the function you are testing is small (e.g. a function that returns one single value), the expected return value can be stored in the .t test file.
+
+If your outputs are complex and/or large (e.g. for unit tests of functions that return a complex structure, or for API integration tests that return a JSON response), you can use json files to save the expected result of each test, stored on disk. 
+
+[Test.pm](https://openfoodfacts.github.io/openfoodfacts-server/dev/ref-perl-pod/ProductOpener/Test.html) contains helper functions to compare results to expected results and to update the expected results. For instance if your function returns a reference $results_ref to a complex object (like a product):
+
+`compare_to_expected_results($results_ref, "$expected_result_dir/$testid.json", $update_expected_results);`
+
+After writing the test, you need to use once `init_expected_results` (see below) to create a JSON file that contains the resulting object.
+
+Then the next time you run the test, the results will be compared to the stored expected results.
+
+You can also use `init_expected_results` to generate new expected results file and easily what has changed using it `git diff`. If the changes are expected, you can commit the new expected results.
 
 
 ## Running tests