Mardown documentation for the tester

README.md

@@ -114,6 +114,16 @@ $ ./bin/mojitos -t 5 -f 1 -p cpu_cycles -r -s
 1036992.000165117 397678789 2770561 444030 1375729 510379
 ```
 
+## Testing
+MojitO/S provides a utility for correctness testing. It is located in the ext_tester directory and can be expanded easily with new tests.  
+This utility requires `mojitos` to be built first, and can then be ran by running `make run` in the ext_tester directory.  
+
+It works by running `mojitos` multiple times with different parameters, and running its output through different verification functions each time. 
+
+### Adding tests  
+A complete explanation on how to use the testing API can be found [here](./ext_tester/readme.md)
+
+
 ## License
 
 MojitO/S is published under the GPL3 license and is part of the [Energumen Project](https://www.irit.fr/energumen/)

ext_tester/readme.md

+## Adding tests
+*(all paths and filenames mentioned in this section are relative to the `ext_tester` directory)*
+Tests are by expanding the code of the utility directly, using a provded API. The recommended way to do that is to declare and define a test-running function (i.e. a function that uses the API to run specific tests) in a my_test.h/c pair of files in the `executions` subdirectory, and then add a call to your function in the main function, located in `main.c`.   
+Don't heasitate to refer to the existing tests provided for a good example.  
+
+Before you go anywhere, your test file should include `../execution.h`  
+The core function of the test-running API is the `execute_test()` function. This function runs `mojitos` in parallel and takes a pointer to an `Execution` object that will define what is done with this run.  
+```C
+typedef struct {
+    char *const *args; 
+    Tester *testers;
+    int nb_testers; 
+    void *context;  
+} Execution;
+```
+- *args* points to a string array, which is the arguments that will be passed to `mojitos`.  
+- *testers* is an array of *nb_testers* `Tester` objects. Each of these objects defines a test performed during the run.  
+- *context* is an arbitrary pointer that will be passed to the testing functions.  
+
+The Tester object is defined as follows : 
+
+```C
+typedef struct {
+    TesterInit init;
+    TesterReader read;
+    TesterFinalizer finalize;
+    void *state;
+    const char *name;
+} Tester;
+```
+- *init*, *read* and *finalize* are pointers to function that will be called at various stages of the run. See below. 
+- *state* is an arbitrary pointer that may be initialized (to possibly allocated memory) by the *init* function.
+- *name* is a string that will be used in the output of the program.  
+
+The function pointers are defined as follow : 
+
+```C
+typedef void(*TesterInit)(void **state, void *context);
+typedef void(*TesterReader)(void *state, void *context, const char *buffer, int read_size);
+typedef int(*TesterFinalizer)(void *state, void *context);
+```
+- The *TesterInit* function of a Tester is called once before `mojitos` is ran. It is given a pointer pointer to the state pointer, that will then be passed directly to the two other functions. Use this to allocate memory for a state-sotring structure. 
+- The *TesterReader* function of a Tester is called everytime `mojitos` outputs something. It is given a pointer to the null-terminated string that was read on mojitos output.  
+- The *TesterFinalizer* function of a Tester is called once `mojitos` exits, and should return a non-zero value if the test failed (incorrect mojitos output), or 0 otherwise. /!\ If this test uses a state object, it must be freed here !
+
+Notice how every function is also give a \**context* pointer. This pointer is the context property of the current Execution.
\ No newline at end of file