<!--
  Manuel de tests par défaut
  Chemin : doc/tests/default.md
-->
# Manuel de tests

Ce document décrit les procédures de test des principales fonctionnalités du CLI `codex-env-tools`.

## Pré-requis
- Node.js >= 14
- pnpm installé
- utilitaires système : `curl`, `jq`

## Variables d’environnement
- `GITLAB_TOKEN` (requis) : jeton GitLab avec droits d’écriture sur le projet
- `TELEPORT_TOKEN` (optionnel) : join token pour TeleportBot (génération de certificats TLS)

## Variables de test E2E
- `PROJECT_PATH` (requis pour le test E2E) : chemin du projet GitLab, ex. `groupe/mon-projet` (doit correspondre à l’origin du dépôt local)

## Préparation de l’environnement

Avant de lancer les procédures de test, exportez les variables :
```bash
export GITLAB_TOKEN="<votre_token_gitlab>"
export TELEPORT_TOKEN="<votre_token_teleport>"   # optionnel, requis pour TLS
export PROJECT_PATH="<groupe/mon-projet>"       # pour le scénario E2E
```

## 1. Création d’une tâche (start-task)
1. Installer les dépendances :
   ```bash
   pnpm install
   ```
2. Construire l’application :
   ```bash
   pnpm run build
   ```
3. (Optionnel) Générer les certificats TLS via Teleport Bot :
   ```bash
   node dist/cli/index.js start-app \
     --app gitlab \
     --token $TELEPORT_TOKEN \
     --workDir ~/.ftprod-ai/tbot
   ```
   **Attendu** : affichage de `Bot lancé: { ... }` et création des fichiers `tls.crt` et `tls.key` dans `~/.ftprod-ai/tbot/dest/`.
4. Créer une nouvelle branche à partir d’une issue GitLab :
   ```bash
   node dist/cli/index.js start-task <ISSUE_IID> \
     --gitlabToken $GITLAB_TOKEN \
     --teleportToken $TELEPORT_TOKEN
   ```
   **Attendu** :
   - Affichage : `Branche créée: <branch>, commit SHA: <sha>`
   - La branche `<branch>` est pushée sur le dépôt distant (`origin`)
     - Vérifier : `git ls-remote --heads origin <branch>` doit renvoyer un hash
   - L’issue GitLab (#<ISSUE_IID>) est liée à la branche (via l’API ou interface web)

## 2. Modification d’un bout de code
1. Se positionner sur la branche créée :
   ```bash
   git checkout <branch>
   ```
2. Modifier un fichier (ex. `src/services/gitlabClient.ts`), par exemple ajouter une ligne de log.
3. Valider les modifications :
   ```bash
   git add src/services/gitlabClient.ts
   git commit -m "Test: modification d'un bout de code"
   ```
   **Attendu** :
   - `git log -1 --pretty=%B` affiche `Test: modification d'un bout de code`
   - Le diff (`git show --name-only HEAD`) inclut `src/services/gitlabClient.ts`

## 3. Vérification de la qualité d’un build
1. (Re)construire l’application :
   ```bash
   pnpm run build
   ```
2. Générer un rapport de qualimétrie complet :
   ```bash
   node dist/cli/index.js qualimetrie:full \
     --out markdown \
     --output report.md
   ```
   **Attendu** :
   - Le fichier `report.md` est créé
   - Le contenu contient les sections suivantes :
     - `## 1. Tests unitaires` avec métriques de couverture (lignes, fonctions, branches, statements)
     - `## 2. Qualité de code (ESLint)` avec décompte des erreurs et warnings
     - `## 3. Sécurité (Vulnérabilités)` listant les vulnérabilités détectées
     - `## 4. Bill Of Materials (Licences)` listant chaque dépendance et sa licence
   - Exemple de vérification rapide :
     ```bash
     head -n 5 report.md | grep "## 1. Tests unitaires"
     ```

## 4. Envoi d’une tâche (send-task)
1. Pousser la branche et créer une Merge Request :
   ```bash
   node dist/cli/index.js send-task <ISSUE_IID> \
     --gitlabToken $GITLAB_TOKEN \
     --teleportToken $TELEPORT_TOKEN
   ```
   **Attendu** :
   - Affichage : `MR créée: !<mrIid> (<webUrl>), branche <branch> à <commitSha>`
   - La Merge Request !<mrIid> existe et est `opened` sur GitLab (vérifier via `<webUrl>`)
   - La description de la MR contient `Closes #<ISSUE_IID>`
   - L’issue #<ISSUE_IID> apparaît liée à la MR (onglet Liens ou API)

## 5. Test d’intégration bout-à-bout
> Ce scénario E2E utilise `curl` pour l'API GitLab et `jq` pour parser la réponse JSON. Installez `jq` si nécessaire.

Pour valider chaque étape en conditions réelles, on peut créer automatiquement une issue GitLab, lancer la tâche, modifier le code en ajoutant un fichier horodaté et valider la MR.

1. Définir le chemin du projet GitLab et créer une issue de test :
   ```bash
   # Remplacer par 'groupe/nom-du-projet' (identique à celui de l'origine git)
   PROJECT_PATH="<votre-groupe>/<votre-projet>"
   # Création d'une issue via l'API GitLab
   ISSUE_RESPONSE=$(curl -s --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
     -X POST "https://gitlab.teleport.ftprod.fr/api/v4/projects/${PROJECT_PATH//\//%2F}/issues" \
     --form "title=Test intégration codex-env-tools" \
     --form "description=Création d'un fichier horodaté pour test E2E")
   ISSUE_IID=$(echo "$ISSUE_RESPONSE" | jq -r '.iid')
   echo "Issue créée: IID=$ISSUE_IID"
   ```
   **Attendu** :
   - `ISSUE_IID` est un entier positif (`echo "$ISSUE_IID" | grep -E '^[0-9]+$'`)
   - L’issue #${ISSUE_IID} apparaît dans l’interface GitLab

2. Lancer la création de branche (start-task) :
   ```bash
   node dist/cli/index.js start-task $ISSUE_IID \
     --gitlabToken $GITLAB_TOKEN \
     --teleportToken $TELEPORT_TOKEN
   ```
   **Attendu** :
   - Affichage : `Branche créée: <branch>, commit SHA: <sha>`
   - La branche `<branch>` est pushée sur `origin` (`git ls-remote --heads origin <branch>`)

3. Se positionner sur la branche et ajouter un fichier horodaté :
   ```bash
   BRANCH=$(git rev-parse --abbrev-ref HEAD)
   git checkout "$BRANCH"
   TIMESTAMP=$(date +%Y%m%d%H%M%S)
   FILE="doc/tests/data/touch-${TIMESTAMP}.md"
   mkdir -p $(dirname "$FILE")
   echo "Test E2E – $TIMESTAMP" > "$FILE"
   git add "$FILE"
   git commit -m "Test E2E: ajout $FILE"
   git push origin "$BRANCH"
   ```
   **Attendu** :
   - Localement : `ls "$FILE"` renvoie le fichier créé et `cat "$FILE"` affiche `Test E2E – $TIMESTAMP`
   - Distant : `git ls-remote --heads origin "$BRANCH"` inclut la branche, et `git ls-tree origin/$BRANCH doc/tests/data/` liste le fichier

4. Envoyer la tâche (send-task) et créer la MR :
   ```bash
   node dist/cli/index.js send-task $ISSUE_IID \
     --gitlabToken $GITLAB_TOKEN \
     --teleportToken $TELEPORT_TOKEN
   ```
   **Attendu** :
   - Affichage : `MR créée: !<mrIid> (<webUrl>), branche <branch> à <commitSha>`
   - La Merge Request !<mrIid> est `opened` sur GitLab (vérifier via `<webUrl>`)

5. Vérifier sur GitLab :
   - Dans l’interface GitLab (ou via l’API `GET /projects/:id/merge_requests/:mr_iid/changes`), le fichier `doc/tests/data/touch-<timestamp>.md` figure parmi les changements
   - La description de la MR contient `Closes #<ISSUE_IID>` et l’issue #<ISSUE_IID> apparaît liée/fermée

6. Nettoyage (optionnel) :
   ```bash
   # revenir sur la branche principale (main ou master)
   git checkout main
   # supprimer localement et à distance la branche de test
   git branch -D "$BRANCH"
   git push origin --delete "$BRANCH"
   ```

---
*Fin du manuel de tests.*