From 451594132e09f5fc2f2f2f46232a43007edd7a38 Mon Sep 17 00:00:00 2001
From: viennet <emmanuel.viennet@gmail.com>
Date: Fri, 6 May 2022 17:36:19 +0200
Subject: [PATCH] Doc tests API

---
 docs/ModelisationParcoursBUT.md |  1 +
 docs/ScoDoc9API.md              |  6 ++-
 docs/TestsScoDoc.md             | 65 ++++++++++++++++++++++++++++++++-
 3 files changed, 70 insertions(+), 2 deletions(-)

diff --git a/docs/ModelisationParcoursBUT.md b/docs/ModelisationParcoursBUT.md
index b9dfbaea..e221ea6e 100644
--- a/docs/ModelisationParcoursBUT.md
+++ b/docs/ModelisationParcoursBUT.md
@@ -173,6 +173,7 @@ particuliers (décision de jury manuelle).
  - [x] pour le passage en S5, avoir validé toutes les UE du BUT 1 (S1 et S2).
 
 Il faut donc:
+
  1. Construire les regroupements d'UE et calculer la moyenne des moyennes d'UE
     (a priori de même poids, cela n'est pas spécifié dans les textes).
 
diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md
index 42b80cdc..d34d3002 100644
--- a/docs/ScoDoc9API.md
+++ b/docs/ScoDoc9API.md
@@ -80,7 +80,11 @@ Les autorisations et rôles sont gérés exactement comme pour l'application.
 Exemple avec `curl` (un outil en ligne de commande présent sur la plupart des
 systèmes):
   
-    curl -u user_name:password --request POST  https://SERVEUR/ScoDoc/api/tokens 
+  curl -u user_name:password --request POST  https://SERVEUR/ScoDoc/api/tokens 
+
+ou la même chose avec `http`:
+
+  http --auth user_name:password POST https://SERVER/ScoDoc/api/tokens
 
 où `SERVEUR` est l'adresse (IP ou nom) de votre serveur.
 La réponse doit ressembler à ceci:
diff --git a/docs/TestsScoDoc.md b/docs/TestsScoDoc.md
index b256762f..9a051df9 100644
--- a/docs/TestsScoDoc.md
+++ b/docs/TestsScoDoc.md
@@ -28,7 +28,7 @@ lance l'ensemble des tests unitaires.
 
 ## Tests Selenium (web)
 
-TODO (Aurélien, JMP)
+TODO (Aurélien, JMP) *ce projet est abandonné pour l'instant*.
 
 ## Portail pour tests
 
@@ -42,6 +42,69 @@ Lancement:
 
     /opt/scodoc/tools/fakeportal/fakeportal.py 
 
+## Tests de l'API ScoDoc9
+
+L'API est [documentée ici](ScoDoc9API.md).
+Des tests sont disponibles sous `scodoc/tests/api`. Le mécanisme de test est un
+peu différent de celui des tests unitaire: on test un *client* de l'API. Il faut
+donc un serveur, tournant sur la même machine ou sur une machine distante. Ce
+serveur doit avoir été configuré avec des données de test.
+
+### Configuration du serveur pour tester l'API
+
+ 1. modifier /opt/scodoc/.env pour indiquer 
+
+    FLASK_ENV=test_api
+    FLASK_DEBUG=1 
+ 
+ 2. En tant qu'utilisateur scodoc, lancer:
+
+    tools/create_database.sh --drop SCODOC_TEST_API
+    flask db upgrade
+    flask sco-db-init --erase
+    flask init-test-database
+ 
+Ces commandes vont effacer la base `SCODOC_TEST_API` si elle existe, la
+recréer, mettre à jour le schéma pour la dernière version de ScoDoc installée,
+l'initialiser et la peupler de données fictives pour les tests.
+
+ 3. Relancer ScoDoc:
+
+    flask run --host 0.0.0.0
+
+
+### Configuration du client de test API
+ 1. Copier le fichier `scodoc/tests/api/dotenv_exemple` dans
+    `scodoc/tests/api/.env`, et éditer ce fichier `.env`pour y configurer votre
+    *client* de test (ne pas confondre avec `scodoc/.env` qui est la config de
+    votre serveur). 
+    Normalement, il est suffisant d'indiquer l'URL de votre serveur. Si le
+    client de test est sur la même machine que le serveur ScoDoc, c'est simplement:
+    ```
+    SCODOC_URL = "http://localhost:5000/"
+    ```
+
+### Lancement des tests de l'API
+
+Le serveur scodoc étant lancé comme expliqué ci-dessus, on utilise `pytest`sur
+le client (qui peut être un autre shell de la même machine, bien sûr).
+
+```
+cd /opt/scodoc/
+pytest tests/api/test_api_xxx.py # remplacer xxx par votre test
+```
+
+Rappelons quelques options utiles de `pytest`: `-x` permet de s'arrêter sur la
+première erreur, et `--pdb` lance directement le débuggueur sur l'erreur.
+Ainsi, 
+```
+pytest --pdb -x tests/api/test_api_departements.py 
+```
+lancera un test en mode "interactif", utile pour les mises au point.
+
+
+
+