# TESTS (Raphaël Thomann)

## Tests du debugger
[Tests du debugger du 20/07/2021](https://hackmd.io/4WG0SX0GTa-DQjfkECK2VA)

## 4 août
- [x] develop/backend/cmds
- [x] OurExceptions.py à commenter
- [x] "if any changes are made in the format of these json files, you need to apply those changes in the jsonFormat.py file, and also in the README.md file at the root of the backend since that is where their format is described here." -> ultra dangereux. Mettre une section dédiée là où les formats sont définis (avant leur définition).
- [name=raphaël]
- [ ] ces fichier ne sont pas utilisé dans le processus de vérification des formats, une section a été ajouté a la doc doxygen dans la sous-page project configuration : [ici]()
- [x] develop/backend/cmds/cmds_tests
- [x] corriger anglais (les pluriels) et autres choses (faire la traduction en français pour voir les erreurs, les corriger et retraduire en anglais)
- [x] diagram_backend_project_launhcer (anglais)
- [x] manque de la ponctuation et faire phrase plus courtes.
- [x] develop/backend/README.md
- [x] What is it?
- [x] est-ce à jour?
- [x] How it works : parsing and executing .proof files
- [x] cette partie n'a pas été relue/corrigée?
- [x] Added feature concerning execute.py
- [x] je n'ai pas compris cette section.
- [x] corriger l'anglais
- [x] coloration syntaxique des fichiers json
- [ ] Modifications done for development purposes
- [ ] pas compris cette section
- [ ] [name=raphaël] cette section (Modifications done for development purposes) ce n'est pas moi qui l'a rajouter
- [x] develop/backend/requirements.txt
- [x] big problem: ceci n'est pas à jour les versions sont à 3 chiffres (ce qui devait être banni)
## Relecture du 14/07/2021

> [name=Michel Lenczner]
> Dans tous les fichiers mettre le nom des contributeurs et la date de production.
>
> **répertoire citadle/backend/cmds/
> - [x] décrire la fonction `OurException.py` dans le readme
>
> *fichier citadle/backend/cmds/OurExceptions.py*
> - [x] Pourquoi les formats de fichiers de configuration sont là? Ce n'est pas l'endroit.
> - [x] A quoi sert ce fichier? est-il généré automatiquement? Sinon, il faut le décrire dans le readme.
>
> **répertoire citadle/backend/cmds/cmds_tests**
> - [x] Faire un readme synthétique :
> - description des fichiers et répertoire
> - autre informations importantes:
> principes des tests s'il y en a un?
> lien vers les formats de fichiers de configuration et liste de projets.
> comment lancer les tests si nécessaire (lien avec le répertoire de tests?)
> lien avec d'autres répertoires...
> éventuellement contenu des sous-répertoires ou bien le mettre dans le sous-répertoire `test_data`
> - description de chaque test (une phrase par test) du fichier `test_commands.py` plus éventuellement l'explication du principe des tests (si nécessaire).
> - expliquer ce qui est couvert et ce qui ne l'est pas.
> - les tests manquants.
>

> *fichier citadle/backend/cmds/cmds_tests/test_commands.py*
> - [x] Si nécessaire, commenter les "import" de début.
> - [x] Je ne sais pas à quoi correspondent les commentaires lignes 14-76.
> - [ ] Ici comme dans tous les fichiers, mettre le nom de l'auteur et date de modification.
> - [x] Ne pas répéter ce qui est fait dans la description des tests du readme, mais ajouter des explications de détail.
>
> *fichier citadle/backend/cmds/commands.py*
> - [ ] Si possible mettre nom d'auteur/date dans les fonctions modifiées.
> - [ ]
> **répertoire citadle/backend/core/core_tests**

> *fichier citadle/backend/execute.py*
> - [x] corriger les quelques coquilles restantes dans les commentaires (penser à utiliser le neutre plutôt que le masculin pour les objets). Utiliser un correcteur d'orthographe pourrait être utile ou bien comme je l'ai indiqué DeepL pour traduire anglais->français->anglais (avec relecture du français pour vous assurer que ce qui est dit est bien ce que vous voulez dire.)
> - [x] vérifier que sa description dans le readme du backend est correcte.
>
> *fichier citadle/backend/requirements.txt*
> - [x] mettre ce fichier à jour à condition qu'il soit toujours utilisé. Sinon, me dire pourquoi il ne l'est plus et prendre une décision. Si suppression mettre à jour le readme du backend.
>
> *fichier citadle/backend/test_suites_tools.py*
> - [x] à déclarer dans le readme du backend
> - [x] faire une explication du principe de ce fichier dans le readme à la suite de ce qui est dit sur les tests
> - [x] faire un point sur le readme du backend concernant les tests et le lancement des programmes. Voir ce qui est toujours valable (modifier si nécessaire) et proposer la suppression de ce qui ne l'est plus.

> *fichier citadle/backend/README.md*
> - [x] Dans [List of projects](https://gitlab.com/michelLenczner/citadle/-/tree/develop/backend#list-of-projects) mettre un exemple plus général (incluant des projets ignorés)
> - [x] Dans [Configuration files](https://gitlab.com/michelLenczner/citadle/-/tree/develop/backend#configuration-files) mettre à jour l'exemple de fichier de configuration et compléter/ les explications (je crois que c'est fait), et corriger les fautes d'anglais introduites (ça n'est pas fait)
> - [x] pour les options de ocaml, il expliciter celles que nous utilisons avec leur explication.
> - [x] vérifier que la section [How it works : parsing and executing .proof files](https://gitlab.com/michelLenczner/citadle/-/blob/develop/backend/README.md#how-it-works-parsing-and-executing-proof-files) est à jour. La mettre à jour sinon.
> - [x] vérifier que la section [Running tests](https://gitlab.com/michelLenczner/citadle/-/blob/develop/backend/README.md#running-tests) est à jour. La mettre à jour sinon. Si elle est utile, cette section devrait être dans le readme de `citadle/tests` ou dans le readme d'un sous-répertoire.
> - [x] vérifier que la section `Launching projects without running the server` est à jour. La mettre à jour sinon.
> - [x] vérifier que la section `Added feature concerning execute.py` est à jour. La mettre à jour sinon. Corriger l'orthographe. Sauter des lignes avant et après les figures/vidéos. Expliquer ce que font les vidéos.

> **répertoire libCitadle**
> - [x] Faire un readme qui explique l'utilité du répertoire et le contenu des fichiers. Si vous ne savez pas, vous laissez des ???.
> **répertoire citadle/tests**
> - [x] Compléter le readme
> - [x] Faire le readme du répertoire `tests/backend-debug`. C'est probablement là que l'on devrait mettre toutes les explications ce qui concerne les tests du back-end. Donc faire des renvois des readme du back-end vers ce readme.
> [name=Raphaël] le répertoir tests/backend-debug a été suprimé puique ce dernier n'entre pas de le processus des tests du backend

> **répertoire citadle**
>
> *fichier citadle/readme*
> - [x] Vérifier/compléter/modifier [la description des fichiers/répertoires de citadle](https://gitlab.com/michelLenczner/citadle/-/blob/develop/README.md#description-of-the-directories)
>
> **Tests du noyau**
> - [ ] prise en charge des tests du noyau dans l'intégration continue

----

> [name=Michel Lenczner]
> - [x] Trouver une solution pour que les figures et diagrammes soient pérénisées (suivant les outils utilisés). Définir une stratégie collective. Il s'agit que lorsque l'on prend la suite de quelqu'un, on n'ait pas à refaire une figure si on doit la modifier.
> - [x] Faire des figures qui soient plus "intégrées". Elles sont trop grandes et pas séparées les unes des autres.
> - [x] faire une table des priorités comme les autres en fin de document. Prenez exemple sur Lilyan.

> [name=Raphaël Thomann]
> - [ ] concernant la pérénité des diagrammes j'ai une solution qui permet de [générer les diagramme UML a partir de code](https://plantuml.com/fr/), pour ce qui est des autres diagrame (non normalisé la seul solution qui semble adapté est de laisser une trace de la source est de les éditer avec leur logiciel d'édition)

## normalization of uml diagram format:
[diagramme UML via plantUML](https://plantuml.com/fr/)

## this specication are based on these document:
- [here](https://michellenczner.gitlab.io/citadle/_backend_project_configuration.html) for back-end
- [here](https://michellenczner.gitlab.io/citadle/_ebop_version1_0_student_interface.html) for studentInterface
- [here](https://michellenczner.gitlab.io/citadle/_ebop_version1_0_user_interfaces.html) for userInterface

note_to_self add a link to debuggerInterface when it will be done in documentation
### more details:
#### Methodology:
- list functionalities for one of the project's part
- for each of the functionalities establish an activity diagram (even a non exhaustive one for unit testing , those are more useful for functional testing)
- cover every path of the created graph
- use coverage to establish consistency of test
#### details on code coverage:
- for both frontend and backend coverage is already set-up
- natively in angular
- natively in django
- both command to create code coverage report are documented:
- for front-end:
if prompted with error:No binary for Chrome browser on your platform. then you must first export CHROME_BIN variable in your environement.
Please, set "CHROME_BIN" env variable. then you must first :

    # note this the default path to chromium binary on my system
    export CHROME_BIN='/usr/bin/chromium-browser'

    #enter these comand in a terminal in root of the project
    cd userInterfaces
    ng test --no-watch --code-coverage

    #enter these comand in a terminal in root of the project
    cd ebopStudentInterfaces
    ng test --no-watch --code-coverage

- for back-end:

    #enter these comand in a terminal in root of the project
    cd backend
    coverage run --source='.' manage.py test
    coverage html

#### Details on unit test adding
- for back-end:
- the django project (aka the backend/ folder ate the root of project citadle) is structured in multiple subfolder, each containing each module. Every subfolder has a moduleName_tests/ folder in them wich contain new test files e.g.:

        backend/ 
        ├──core/
        │  ├──core_tests/
        │     ├──test_dbinterface.py
        │     ├──test_ocamlinterface.py
        │     ├──...
        ├──cmds/
        │  ├──...

for each module we can put test in their already existing tests files, or simply create new one
### what has already been done:
- normalization of error naming on citadle project :

|  |
| -------- |
| diagram explaining the adding of error category / error adding|

every processus runing on citadle server has to take care of their errors individualy, the only standards they have to respect is this one when they adress error messages to the user,every errors belong to a category, in this category 99 error can be created (normaly it's enough to be exhaustive), errors and error categories would be stored in a json following this format bellow:

{
    "error":{
        "error_category_1":{
            "error_type_1":    "101"
            .
            .
            .
            "error_type_99":    "199"
        }
        .
        .
        .
        "error_category_n":{
            "error_type_1":    "n*100+1"
            .
            .
            .
            "error_type_99":    "n*100+99"
        }
    }
}

- diagram explaining the debuggerInterface part of backend :

|  |
| ------------------------------------ |
| handling of the functioning of the debuggerInterface part of backend in general |


### new diagram

@startuml global
title global view of proof builder
skinparam defaultTextAlignment center
start
    #palegreen:check for project_list presence and comformity;
    if (projectList check faillure?) then (no)
    else (yes)
        repeat
            #Cyan:build/ and ml_files/ directories creation;
            if (directories creation faillure?) then (no)
                #Gold:check presence and format of config file;
                if (config file check faillure?) then (no)
                    #Pink:parser compilation;
                    if (parser makefile faillure?) then (no)
                        #Orange:all .proof file parsing;
                        if (parsing error?) then (no)
                            #LightSkyBlue:concatenation of all file;
                            if (concatenation failure?) then (no)
                                #Pink:libCitadle compilation;
                                if (libCitadle makefile faillure?) then (no)
                                    #Plum:interpretation of the concatenated files;
                                else (yes)
                                endif
                            else(yes)
                            endif
                        else(yes)
                        endif
                    else(yes)
                    endif
                else(yes)
                endif
            else (yes)
            endif
        repeat while (project remaining?) is (yes) not (no)
    endif
    
    #WhiteSmoke:display all message on standard output 
    and return logger object containing errors only;
stop
@enduml

---

@startuml handle project_list
title Handling of presence \nand format of project_list file
skinparam defaultTextAlignment center
skinparam Activity{
    ArrowColor Green
    BackgroundColor PaleGreen
}
start
:read the path to project_file.json;
if (Path to project_list.json exist?) then (yes)
else (no)
    :error_display: path not found;
endif
if (project format is correct?) then (yes)
else (no)
    :error_display: bad format;
endif
:create a Project Object that\nwill be used for the rest of the handling;
stop
@enduml

---

@startuml handle config file
title Handling of presence\nand format of config_*.json file
skinparam defaultTextAlignment center
skinparam activity{
    ArrowColor Gold
    BackgroundColor Yellow
}
start
:read conf_* file;
if (file exist?) then (yes)
else (no)
    :error_display: file not found;
endif
if (file is good format?) then (yes)
else (no)
    :error_display: bad format\nfor config file;
endif
stop
@enduml

---

@startuml lib parse compile
title Handle of the compilation of parser and lib files
skinparam defaultTextAlignment center
skinparam activity{
    ArrowColor Crimson
    BackgroundColor Pink
}
start
:cd parser directory;
if (parser path exist?) then (yes)
    if (has makefile \nallready been\nexecuted once?) then (yes)
    elseif (has makefile \nbeen modified?) then (no)
    elseif (has the \nparser's files\nbeen modified?) then (no)
    else (yes)
        :execute makefile;
        if (has makefile \nexecution failled?) then (yes)
            :error_display: makefile execution \nfor parser has failled;
        else (no)
        endif
    endif
else (no)
    :error_display file not found;
endif
:cd libcitadle directory;
if (libcitadle path exist?) then (yes)
    
    if (has makefile \nallready been\nexecuted once?) then (yes)
    elseif (has makefile \nbeen modified?) then (no)
    elseif (has the \nlibcitadle's files\nbeen modified?) then (no)
    else (yes)
        :execute makefile;
        if (has makefile \nexecution failled?) then (yes)
            :error_display: makefile execution \nfor libcitadle has failled;
        else (no)
        endif
    endif
else (no)
    :error_display file not found;
endif
stop
@enduml

### Task priority:
High: signify that the task need to be trated in the nearest future
medium: means that the processing of this task can be delayed but it must be completed
low: implies that the task may not be done durring my stage

- for backend/cmds/ part (concering debuggerInterface):

|Task:|Priority:|
|-|-|
|create functional test for execute.py command|High|
|realise unit test fuction called by excute.py|High|
|document this part in the back end|High|
|redo the activity diagram with a more separated way|Medium|

- for studentInterface:

|Task:|Priority:|
|-|-|
|list every function used in this part|Medium|
|realise unit test on diferent module of this interface|Medium|
|document test on this part|Medium|

- for userInterface:

|Task:|Priority:|
|-|-|
|list every function used in this part|Medium|
|realise unit test on diferent module of this interface|Medium|
|document test on this part|Medium|

- for back-end part in general

|Task:|Priority:|
|-|-|
|evaluate consistency of back-end's test|High|
|add more precise test for dbinterface module|High|
|move test section of the doc to non regretion test part of the doc|Medium|

- for the parser:

|Task:|Priority:|
|-|-|
|evaluate consistency of parser's tests|low|
|deploy more precise test for the parser|low|
|create documentation for the test suites|low|

- for the core:

|Task:|Priority:|
|-|-|
|evaluate consistency of core's tests|low|
|deploy more precise tests for the core|low|
|create documentation for the test suites|low|

- for the project globally:

|Task:|Priority:|
|-|-|
|change the naming convention so it fits better our programming habits (we already concerted with Kilian and everyone agrees on using camelCase practice)|Done|
|complete missing information in documentation concerning ebopClient|Medium|
|restructurate documentation|Medium or Low|
|establish a way to handle error|Low|
|create a methodology to automate test suite creation|High|
|maintain and create new test on gitlab integration|Medium|
|test data flow management between front end and back end|Medium or Low|
|esatblish functional test suite with protractor|Low|

[carnet de bord temporaire](https://hackmd.io/ODZQ8MgBR2GquMSPCpvBnw)

angular part of test:

every module has a moduleName_specs.ts with a synthax based off [jasmine framework](https://jasmine.github.io/)
([more info o the said synthaxe : here](https://jasmine.github.io/tutorials/your_first_suite)).
the protractor tool will use these specs.ts file in order to run test suite on the application:

// spec.ts : an exemple of test suite -> describe('Protractor Demo App',...)
// containing one test -> it('should add one and two')

describe('Protractor Demo App', function() { // this is the test suite
  it('should add one and two', function() { //this is the test
    browser.get('http://juliemr.github.io/protractor-demo/');
    element(by.model('first')).sendKeys(1);
    element(by.model('second')).sendKeys(2);

    element(by.id('gobutton')).click();

    expect(element(by.binding('latest')).getText()).
        toEqual('5'); // This is wrong!
  });
});

each time there is element you must first [select it](https://www.protractortest.org/#/locators)
exemple of use:
{%youtube WROmnhRbH6k %}
[Angular: End to End Testing With Protractor](https://medium.com/swlh/angular-end-to-end-testing-with-protractor-55897de591be)

troubleshooting:
localisation of problem in backend/cmds/commands.py
when interpretation is succesful but there's no output , the command doesn't generate print strategy

toux doux list current:
- [ ] speak to Lylian to clarify the use of protractor suite test
- [ ] speak to Vincent about test methodology
- [x] clarify bug concerning print_of_strategy_out.txt removal
- [ ] moving doumentation of doc generation outside nonregression test (maybe talk to Killian and Florian for documentation manipulation)
- [x] change debugger interface readme.md to explain how exectue.py work

[comportement patologique du pseudo_makefile](https://hackmd.io/7J2rUpa7R1yOm-gYkuSjaA)

> [name=Michel Lenczner]Je me suis amusé à traduire en français puis de nouveau en anglais pour filtrer les fautes d'anglais. Ca marche bien. Voici le résultat:
> [name=Raphaël Thomann] c'était une bonne idée merci. Dans le doute je vais déplacer l'ancienne version dans old , hésité pas a me dire si on doit la suprimer
### Documentation :

### standardization of test suites:
each test will follow the same template based on the ToolsForTestSuites class of the test_suites_tools module.
the tests are divided into four steps:
- the initialization
- the command to execute
- the test to execute on the result of the previous step
- the cleanup (return to the initialization)

all these steps are functions that are passed to the factorTest function which will simply execute each of these steps if they are defined, it is also important to note that any of these steps can be omitted (any of them can be omitted if so the function will return a successful test). This was done so that if we don't need to set things up, it can be skipped, but if we need to create some file with things written in it, then you can set it up.

Here is an example

def precondition_function(value:int)->None :

    """
    do the thing you need to do before this specific test
    """
    a=value
    print('a treatment')
    ...
    
argument_for_initialization_function=\
{
    "value":56
}

It is important to note that the field in the dictionary must have the same name as the function argument, in this case value=value, and that dictionaries can contain multiple fields, each of which can be of any type:

def precond(varObject:Object,res:'list[int]'=[1,2,3])->None :
    an_object=varObject
    inner_res=res
    ...
    
argPrecond=\
{
    "varObject":Object(), # calls the constructor of the object
    "res" :[]
}

It is important to note that if a function parameter has a default value as in our example:

res:'list[int]'=[1,2,3]

if it is present in the dictionary :

argPrecond=\
{
    "varObject":Object(), # calls the constructor of the Object
    "res":[]
}

the value of res in this case is overloaded

## Old:

## Documentation:

### standardization of test suites:
each tests will follow the same patern based on ToolsForTestSuites class from test_suites_tools module
the test are splited in four step:
- initialzation
- the command to run
- the test to run on the result of previous previous step
- the cleaning (revert initialization)

all these step are functions that are passed to the factorTest function wich will simply run each of these step if they're defined, it's also important to note that any of these steps can be omitted (every of them can be omitted if so the function will return a succesful test). It's been done in a way that if we don't need to establish things it can be skiped, but if we need to create a certain file with things written in it then you can define it.

here is an example

def precondition_function(value:int)->None:
"""
do the thing you have to do before this specific test
"""
    a=value
    print('some treatment')
    ...
    
argument_for_initialization_function=\
{
    "value":56
}

It's important to note that the field in the dictionary must have the same name as the argument of the functon here value=value, also the dictionaries can hold multiples field, eahch of them can be of any type:

def precond(varObject:Object,res:'list[int]'=[1,2,3])->None:
    an_object=varObject
    inner_res=res
    ...
    
argPrecond=\
{
    "varObject":Object(), # call the construtor of Object
    "res":[]
}

important to note is that if there's a parameter in the function that has a default value like in our example :

res:'list[int]'=[1,2,3]

if it's present in the dictionary:

argPrecond=\
{
    "varObject":Object(), # call the construtor of Object
    "res":[]
}

the value of res in this case is overridden