Apparence
A7 — Imports / Exports Excel
🆕 Évolution proposée — étend §17 et F11
Statut : 🟢 prêt à spécifier. Le périmètre et les règles de collision sont tranchés (décisions du 20/07/2026, voir ci-dessous). Clôt Q4 (format d'import CRIM). À séquencer après A9 : les étapes partagées et les jeux de données changent les colonnes du gabarit.
En une phrase
L'outil sait produire un classeur Excel, mais quasiment pas en avaler un. Reprendre un plan de test existant se fait donc écran par écran — c'est le premier obstacle au démarrage sur un nouveau projet.
Constat
- Export : un seul livrable, le classeur à 7 feuilles de F11 (Page de garde · Synthèse · Tests-Flux · Étapes · Anomalies · Journal · CRIMs), généré côté client avec ExcelJS.
- Import : les CRIMs uniquement, et le format est marqué ❓ non déterminé dans §17.
- Conséquence pratique : la reprise initiale d'un référentiel de 400 flux se fait à la main, écran par écran. C'est le premier obstacle à l'adoption sur un nouveau projet.
A7.1 Ce que le marché fait — le format n'est pas à inventer
TestRail — import CSV / Excel
- Deux dispositions : une ligne = un cas (cas simples), ou multi-lignes — la première ligne porte les champs du cas et la première étape, chaque étape suivante occupe une ligne supplémentaire dans les mêmes colonnes (modèle Test Case (Steps)).
- La 1ʳᵉ ligne porte les en-têtes, mappés ensuite aux champs.
- Mapping en deux temps : colonne → champ, puis valeur → option de liste déroulante / case à cocher / multi-sélection. Configurable pour les champs natifs comme personnalisés.
- La configuration de mapping est enregistrable dans un fichier réutilisable — importer dix fichiers avec la même config sans re-mapper.
- Pièges documentés : encodage (Excel/Windows écrit du windows-1252, les autres outils de l'UTF-8) et délimiteur (
,,;ou tabulation).
Xray — Test Case Importer
- Une colonne
TCID(Test Case Identifier) identifie à quel cas appartient chaque ligne : c'est elle qui regroupe les étapes. Même logique multi-lignes. Summaryobligatoire.- Les étapes se mappent sur trois colonnes : Step / Data / Expected Result.
- Encodage ISO-8859-1 recommandé pour les caractères accentués — point d'attention réel en contexte francophone.
➡️ Transposition directe à notre modèle : Step / Data / Expected Result correspond exactement à nos description / jeu / attendu, et le TCID à notre testCode.
A7.2 Périmètre d'import retenu
✅ Décision du 20/07/2026
Les quatre périmètres suivants entrent au périmètre. Ils se livrent dans cet ordre.
| # | Objet importable | Pourquoi |
|---|---|---|
| I1 | CRIMs en masse | Existant v1 dont le format n'était pas défini — clôt Q4 |
| I2 | Référentiel complet (modules → fonctionnalités → scénarios → flux → étapes) | Reprise initiale : charger 400 flux depuis l'Excel du client au lieu de les saisir |
| I3 | Résultats d'exécution | Testeur sans accès à l'outil, ou tests joués sur site client |
| I4 | Retours développeurs sur anomalies (round-trip) | Voir §A7.5 |
A7.3 Gabarit d'import du référentiel (I2)
Classeur template-import-referentiel.xlsx, généré par l'application (jamais rédigé à la main par le client) :
| Feuille | Rôle |
|---|---|
Flux | La donnée à saisir. Disposition multi-lignes : une ligne par étape, regroupées par testCode. |
Référentiels | Listes de valeurs (modules, fonctionnalités, scénarios, codes CRIM, statuts) — alimente les listes déroulantes de la feuille Flux. |
Notice | Règles de remplissage, colonnes obligatoires, exemple rempli. |
Colonnes de la feuille Flux
| Colonne | Obligatoire | Portée | Équivalent marché | Remarque |
|---|---|---|---|---|
testCode | ✅ | flux | TCID (Xray) | clé de regroupement des étapes |
module | ✅ | flux | — | liste déroulante |
fonctionnalite | ✅ | flux | — | liste déroulante |
scenario | ✅ | flux | — | liste déroulante |
nomFlux | ✅ | flux | Summary (Xray) | |
statut | — | flux | — | Draft / À rédiger / Validé — défaut Draft |
regressionCore | — | flux | — | booléen (A6) |
position | ✅ | étape | — | ordre de l'étape (1, 2, 3…) |
etapeNom | ✅ | étape | — | |
etapeDescription | — | étape | Step | |
jeu | — | étape | Data | |
attendu | ✅ | étape | Expected Result | |
crimCode | — | étape | — | liste déroulante alimentée par Référentiels |
⚠️ A9 ajoutera des colonnes (référence d'étape partagée, jeu de données paramétré). C'est pourquoi A9 doit être tranché avant de publier le gabarit : un client ne re-remplit pas 400 flux parce que le format a changé.
A7.4 Règles de traitement
✅ Décision du 20/07/2026 — collisions
Mise à jour + création automatique de la hiérarchie.
| Situation | Comportement retenu |
|---|---|
testCode déjà présent | Mise à jour du flux et de ses étapes (upsert) — jamais de doublon |
module / fonctionnalite / scenario absent du référentiel | Créé automatiquement |
| Ligne invalide (colonne obligatoire vide, valeur hors liste) | Rejetée, avec numéro de ligne et colonne |
Ce choix privilégie la fluidité de la reprise initiale. Sa contrepartie est non négociable :
- Import à blanc obligatoire (dry-run) — rapport d'erreurs ligne à ligne et aperçu d'impact (X flux créés, Y mis à jour, Z modules créés) avant toute écriture. Sans lui, un fichier mal préparé pollue silencieusement le référentiel.
- Jamais d'import partiel silencieux — soit le lot passe, soit il est rejeté avec un rapport.
- Erreurs exportables — un import de 400 flux ne se corrige pas avec un message générique.
- Import journalisé : qui, quand, quel fichier, combien de lignes créées / mises à jour / rejetées. Cohérent avec l'exigence de traçabilité posée en A3.
- Encodage et délimiteur : le gabarit étant produit par l'application en
.xlsx, le problème d'encodage disparaît pour I2. Il reste pour un import CSV libre (I1) → imposer l'UTF-8 et le documenter dans laNotice.
A7.5 Export « pour développeurs » et round-trip (I4)
Le classeur F11 est un livrable de recette pour le client, pas un support de travail pour l'équipe de développement ou la TMA. Deux besoins, deux formats :
| Export F11 (existant) | Export « dev » (nouveau) | |
|---|---|---|
| Destinataire | client, chef de projet | développeur, éditeur ERP, TMA |
| Contenu | 7 feuilles, mise en forme riche, page de garde | anomalies ouvertes uniquement : étape, jeu de données, attendu vs obtenu, gravité, CRIM, lien preuve, environnement, version ERP |
| Tri | par module | par gravité puis module |
| Forme | présentation | exploitable : une ligne = un défaut, colonnes fixes |
| Round-trip | ❌ | ✅ le développeur renseigne statutRetour et commentaireDev, le fichier est réimporté |
💡 Ce round-trip est une alternative légère à l'intégration Jira (Q10). Si le client n'a pas de Jira accessible depuis l'outil, il couvre l'essentiel du besoin pour une fraction du coût. Les deux ne sont pas exclusifs : le round-trip peut rester le mode dégradé même si l'intégration Jira est ensuite construite.
A7.6 Contraintes techniques
Deux points à connaître sans entrer dans le détail :
- Le gabarit est fabriqué par l'application, avec ses listes déroulantes déjà en place. On ne demande jamais au client de construire lui-même un fichier au bon format — c'est la première cause d'échec d'un import.
- Les gros fichiers sont traités sur le serveur, par lots, pas dans le navigateur. Un import de 400 flux n'est donc pas instantané : l'écran affiche une progression, puis le rapport.
Bibliothèque
ExcelJS est déjà en place et reste le bon choix :
- il produit des classeurs mis en forme (besoin de F11 et du gabarit) ;
- il expose
createReadStream(), qui lit ligne à ligne à mémoire constante — un fichier de 200 Mo passe avec 40 à 60 Mo de tas.
⚠️ Bug connu à contourner — à la lecture d'une plage de validation de données (C2:C1013), ExcelJS l'éclate en adresses individuelles puis les retrie alphabétiquement à l'écriture, créant des plages qui se chevauchent et des règles dupliquées.
➡️ Règle de conception : jamais d'aller-retour lecture → écriture sur le gabarit. Le gabarit est généré (avec ses listes déroulantes) et lu — jamais réécrit à partir d'une lecture.
(SheetJS a été écarté : son édition Community supprime silencieusement les validations de données à l'écriture et charge tout le classeur en mémoire.)
Où le traitement s'exécute — contraintes Convex
| Limite | Valeur | Conséquence |
|---|---|---|
| Temps de code utilisateur en query / mutation | 1 s | Le parsing Excel ne peut pas vivre dans une mutation → action |
| Durée d'une action | 30 min (runtime Convex) / 10 min (Node) | Confortable |
| Argument d'une action Node | 5 Mio | ⚠️ Un classeur volumineux ne passe pas en argument → upload dans Convex File Storage, l'action lit le stockage |
| Documents écrits par transaction | 16 000 | 400 flux × 8 étapes = 3 200 écritures : passe, mais batcher par lots (~500 lignes) reste la règle |
| Documents lus par transaction | 32 000 | Le contrôle d'existence (upsert) doit s'appuyer sur un index by_testCode, jamais sur un balayage |
| Taille d'un document | 1 Mio | non contraignant |
Chaîne retenue : upload navigateur → File Storage → action Node (parse ExcelJS en streaming + validation Zod) → dry-run renvoyé au client → confirmation → mutations par lots.
Export : point d'extension
L'export F11 est aujourd'hui généré côté client, ce qui impose de charger l'intégralité des données de la campagne dans le navigateur. Tenable aujourd'hui, fragile à l'échelle.
➡️ Point d'extension à documenter dans F11 : si le volume croît, basculer la génération dans une action Node qui écrit le classeur dans File Storage et renvoie une URL de téléchargement. Le code ExcelJS est identique — seul l'endroit d'exécution change.
A7.7 Droits
| Action | Rôles |
|---|---|
| Télécharger un gabarit | tous les rôles authentifiés |
| Importer le référentiel (I2) / les CRIMs (I1) | admin + consultant |
| Importer des résultats (I3) | admin + consultant + testeur |
| Importer des retours développeurs (I4) | admin + consultant |
| Exporter (F11 et export dev) | tous les rôles authentifiés |
A7.8 À trancher
| Question | État |
|---|---|
| Périmètre d'import (I1–I4) | ✅ tranché — les quatre |
| Collisions et création de hiérarchie | ✅ tranché — upsert + création auto, avec dry-run obligatoire |
| Colonnes du gabarit | 🟠 dépend d'A9 — à figer après |
| Round-trip Excel vs intégration Jira | 🟠 les deux sont retenus comme non exclusifs — reste à confirmer avec Q10 |
| Import de résultats (I3) : que faire si le flux n'est pas au périmètre de la campagne ? | 🟠 recommandation : rejet, l'ajout au périmètre reste un geste explicite (A3) |