Guide de tests

English version: ../../en/guides/testing.md

Ce guide montre comment tester un agent, une skill, un plugin ou un pack avant son déploiement, et comment la plateforme vérifie sa propre API, ses contrats et sa documentation. Qui : développeurs et responsables de version. Chaque test ci-dessous échoue quand un outil nécessaire manque : rien n'est ignoré en silence.

Fonctionnels

Chaque modèle de projet contient ses tests pytest ; les suites d'évaluation se lancent par POST /v1/evaluations/runs et la porte qualité par POST /v1/evaluations/gates/check.

enterprise-ai test --suite regression --target agent/agt_ap@1.4.0

Écrans : Qualité > Suites d'évaluation définit les suites et leurs métriques, Qualité > Exécutions d'évaluation montre chaque exécution et ses scores, Qualité > Portes qualité montre le verdict qui autorise ou bloque un déploiement.

Sécurité

enterprise-ai test security lance une campagne red team et sort en code 1 au-dessus du seuil ; enterprise-ai test authz exécute les tests OPA et OpenFGA.

enterprise-ai test security --threshold 0
enterprise-ai test authz

Le moteur red team est builtin par défaut ; --engine garak et --probe <nom> choisissent un autre moteur et une autre sonde. Écran : Qualité > Red team.

Conformité et performance

enterprise-ai test sdk-conformance vérifie les contrats contracts/v1 du SDK face au point d'accès. La surface d'API est vérifiée par services/control-plane/tests/test_api_surface.py ; la documentation développeur par services/control-plane/tests/test_developer_guides.py, qui compile aussi les extraits TypeScript, Go et Java des guides SDK. La performance est mesurée par les SLO de télémétrie (GET /v1/telemetry/slo).

enterprise-ai test sdk-conformance

Procédures

Lancer les tests unitaires du projet. Ils prouvent la logique de l'agent ou de la skill sans appeler la plateforme : ils passent en premier et vite.
```
python -m pytest -q tests
```
Résultat attendu : chaque test passe ; les tests du modèle couvrent le manifeste et les politiques fournies.

En cas d'échec : lisez le message d'assertion, corrigez le code, relancez le test en échec seul.
Lancer les tests d'autorisation. Ils prouvent que les politiques OPA et le modèle OpenFGA du projet autorisent ce qu'ils doivent et refusent le reste.
```
enterprise-ai test authz
```
Résultat attendu : code de sortie 0, chaque cas opa test et fga model test passe.

En cas d'échec : le code de sortie 1 nomme le cas en échec, ou signale un binaire opa ou fga manquant ; installez le binaire et relancez la commande.
Lancer la red team. Elle envoie les sondes d'attaque du moteur red team à l'agent et mesure le taux d'attaques réussies.
```
enterprise-ai test security --agent ticket-helper --threshold 0
```
Résultat attendu : code de sortie 0, le taux d'attaques réussies est inférieur ou égal à --threshold.

En cas d'échec : code de sortie 1 ; ouvrez la campagne dans Qualité > Red team, corrigez le prompt, la politique ou le périmètre d'outil qui a laissé passer la sonde, puis relancez.
Lancer une suite d'évaluation. Elle note les réponses de l'agent selon les métriques et les cibles de la suite.
```
enterprise-ai test --suite regression --target agent/agt_ap@1.4.0
```
regression : nom de la suite ; agent/agt_ap@1.4.0 : l'agent et la version testés.

Résultat attendu : code de sortie 0, chaque métrique atteint sa cible.

En cas d'échec : code de sortie 1 avec la métrique sous sa cible ; 404 not_found signale une suite inconnue.
Vérifier la porte qualité. La porte est ce que lisent un déploiement et une promotion : les derniers résultats d'évaluation et de red team de la cible.

Écran : Qualité > Portes qualité. API : POST /v1/evaluations/gates/check.

Résultat attendu : le verdict autorise la cible.

En cas d'échec : 409 gate_failed liste chaque contrôle en échec dans details.failures.
Vérifier la conformité du SDK. Elle prouve que le SDK utilisé et le Control Plane s'accordent sur les contrats.
```
enterprise-ai test sdk-conformance
```
Résultat attendu : code de sortie 0.

En cas d'échec : le code de sortie 1 signale un écart de contrat ; mettez à jour le SDK (voir le Guide de migration).
Lancer les contrôles de la plateforme (contributeurs). Ils prouvent que l'API publiée, la surface des requêtes et ces guides correspondent au code.
```
cd services/control-plane
.venv/bin/python -m pytest -q tests/test_api_surface.py tests/test_developer_guides.py tests/test_docs_kit.py
```
Résultat attendu : chaque test passe.

En cas d'échec : l'assertion nomme la page et la route, la commande, le réglage ou le chemin qui n'existe pas.
Mesurer la performance (exploitants). Le générateur de charge démarre un PostgreSQL jetable, un faux fournisseur de modèles et le Control Plane sur des ports libres de cet hôte, puis lance les scénarios et les contrôles de quotas ; rien n'est envoyé vers un cluster ou un compte cloud.
```
bash tools/perf/run.sh /tmp/eai-perf
```
Résultat attendu : le dossier de sortie contient les mesures ; comparez-les aux SLO de Observabilité > SLO et budgets d'erreur (GET /v1/telemetry/slo).

En cas d'échec : le code de sortie 3 signale l'absence du virtualenv du Control Plane ou de redis-server.

Lancer les tests d'une unité du dépôt (contributeurs)

Le dépôt est un monorepo : chaque unité (Control Plane, Manager, agents sectoriels) a son propre pyproject.toml et son propre virtualenv .venv. Le python du système n'a aucun paquet du projet : python -m pytest depuis la racine échoue à la collecte avec ModuleNotFoundError: No module named 'navin_courtier' (ou navin_rag, navin_compliance, eai). Deux règles suffisent.

Un fichier de tests se lance avec le virtualenv de son unité, depuis le dossier de l'unité. Ne mélangez jamais deux unités dans une même commande : pytest prendrait le pyproject.toml de la première comme racine.
```
cd navin-enterprise-assurance-courtier-distribution/backend
.venv/bin/python -m pytest -q tests/test_kpis_hardening.py
```
Résultat attendu : 2 passed.
Les tests du pipeline du Hub tournent avec le python3 du système et trois outils externes. opa est cherché sur le PATH puis dans OPA_BIN ; yara_x et shellcheck sont des paquets Python épinglés par la CI du Hub (shellcheck-py==0.11.0.1, yara-x==1.22.1). Sur un poste où ces outils vivent dans /tmp/toolchains :
```
env OPA_BIN=/tmp/toolchains/opa \
    PYTHONPATH=/tmp/toolchains/yarax-1.22.1-venv/lib/python3.12/site-packages \
    python3 -m pytest -q hub/pipeline/tests/test_pipeline_files.py -k "not shellcheck"
```
Résultat attendu : 57 passed, 1 deselected. Sans -k, test_shellcheck_clean exige shellcheck installé ; il passe alors aussi (58 au total). Les binaires de /tmp/toolchains disparaissent au redémarrage : un échec opa is required ou No module named 'yara_x' après un reboot vient de là, pas du code.

Unité	Interpréteur	Dossier de lancement	Exemple
Control Plane	`services/control-plane/.venv/bin/python`	`services/control-plane`	`.venv/bin/python -m pytest -q tests/test_api_surface.py`
Manager (serveur)	`navin-manager/server/.venv/bin/python`	`navin-manager/server`	`.venv/bin/python -m pytest -q tests`
RAG Agent	`navin-enterprise-rag/backend/.venv/bin/python`	`navin-enterprise-rag/backend`	`.venv/bin/python -m pytest -q -p no:cacheprovider tests/test_template_artifacts.py`
Compliance & Audit	`navin-enterprise-compliance/backend/.venv/bin/python`	`navin-enterprise-compliance/backend`	`.venv/bin/python -m pytest -q -p no:cacheprovider tests/test_migrations.py`
Back-office bancaire	`navin-enterprise-banking-backoffice/backend/.venv/bin/python`	`navin-enterprise-banking-backoffice/backend`	`.venv/bin/python -m pytest -q tests`
Agents assurance (5 dossiers `navin-enterprise-assurance-*`)	`<dossier>/backend/.venv/bin/python`	`<dossier>/backend`	`.venv/bin/python -m pytest -q tests`
Pipeline du Hub	`python3` du système + `OPA_BIN`, `yara_x`, `shellcheck`	racine du dépôt	voir ci-dessus
Contrats, packaging, outils (`contracts/tests`, `sdks/tests`, `os/tests`)	`services/control-plane/.venv/bin/python`	racine du dépôt	`services/control-plane/.venv/bin/python -m pytest -q contracts/tests`

Lancez les tests les plus proches de votre changement, une fois, après la dernière modification ; la suite complète d'une unité est le travail de la CI.

Outils de test

Besoin	Commande	Utilisé par
Outils OCI, de politique et d'observabilité	`bash tools/oci/fetch.sh`	tests des packs, `opa test`, `fga model test`, `trivy fs`
Émulateurs de stockage	`bash tools/emulators/fetch.sh`	`services/control-plane/tests/test_storage_s3_seaweedfs.py` et les autres tests de stockage
Interpréteur des packs	`bash packs/bootstrap.sh`	suites de tests des packs
Tests de charge	`bash tools/perf/run.sh`	mesures de performance et de quotas

Dépannage

Symptôme	Cause	Correction
`enterprise-ai test authz` sort en code 1, binaire introuvable	`opa` ou `fga` absent	installez-le (`bash tools/oci/fetch.sh` récupère des versions épinglées)
`enterprise-ai test security` sort en code 1	taux d'attaques réussies au-dessus de `--threshold`	corrigez la faiblesse, relancez ; ne relevez jamais le seuil pour passer
409 `gate_failed`	un résultat d'évaluation ou de red team sous la cible	lisez `details.failures`, corrigez, relancez la suite
403 `forbidden` sur une évaluation	rôle manquant (`details.required_roles`)	demandez un rôle qui peut écrire des évaluations
400 `invalid_request` avec `details.engine`	moteur red team inconnu	utilisez `builtin` ou `garak`
`tools/perf/run.sh` sort en code 3	virtualenv ou `redis-server` absent	créez `services/control-plane/.venv`, installez `redis-server`
`ModuleNotFoundError: No module named 'navin_...'` à la collecte pytest	`python` du système au lieu du virtualenv de l'unité	relancez avec `<unité>/.venv/bin/python -m pytest` depuis le dossier de l'unité
`rootdir` pytest pointe sur un autre backend que celui testé	deux unités dans une même commande pytest	une commande par unité
`opa is required`, `No module named 'yara_x'`, `shellcheck is required` dans `hub/pipeline/tests`	outils externes absents du `PATH` (ou `/tmp/toolchains` vidé par un redémarrage)	`OPA_BIN=<chemin opa>`, `PYTHONPATH` vers un venv contenant `yara-x==1.22.1`, `pip install shellcheck-py==0.11.0.1`

Étapes suivantes

Premiers pas : le premier agent, de bout en bout.
Guide de migration : mettre à jour le SDK et les contrats.
Guide de développement de politiques : écrire et tester les politiques.

Fonctionnels​

Sécurité​

Conformité et performance​

Procédures​

Lancer les tests d'une unité du dépôt (contributeurs)​

Outils de test​

Dépannage​

Étapes suivantes​