Environnement de développement local reproductible avec données d'amorçage et fixtures

Pourquoi les bases locales deviennent imprévisibles

Une base locale est propre le premier jour. Puis tout le monde la touche. Un collègue lance une migration, vous importez un CSV, quelqu'un teste une fonctionnalité qui crée 2 000 lignes, et soudain l'app se comporte différemment sur chaque portable.

C'est comme ça qu'un environnement de développement local reproductible se casse en silence. Le code peut être identique, mais pas les données.

Quand chaque développeur a des données locales différentes, les petites choses deviennent vite déroutantes. Un écran qui semble correct pour une personne affiche des erreurs pour une autre. La recherche paraît « lente » uniquement sur une machine. Un flux d'inscription « fonctionne » seulement parce qu'une base a déjà les bons rôles, flags ou comptes de démonstration.

Beaucoup de « ça marche sur ma machine » commencent avec la base de données parce qu'elle porte un état caché : migrations appliquées dans un ordre différent, lignes créées par d'anciennes expérimentations, enregistrements manquants que l'app suppose présents (comme un utilisateur admin ou des paramètres par défaut), voire des secrets ou clés API placés au mauvais endroit.

La configuration manuelle devient un goulot dès que vous intégrez quelqu'un de nouveau ou que vous avez besoin d'un reset propre pour chasser un bug. Si votre doc de setup inclut des étapes comme « créez ces 12 enregistrements à la main » ou « demandez à quelqu'un un dump de la base », ça finira par échouer.

Les données d'amorçage (seed data) sont les données de base dont votre appli a besoin pour fonctionner en local (quelques utilisateurs, plans et flags). Les fixtures sont des jeux de données petits et spécifiques destinés à couvrir un scénario (comme « utilisateur avec abonnement expiré » ou « commande avec remboursement ») pour tester de façon fiable un écran ou une API.

Si vous avez hérité d'un prototype généré par l'IA qui « fonctionne à peu près », c'est souvent là que ça casse. Vous verrez une app qui ne tourne que sur la machine du créateur parce que la base n'a jamais été rendue reconstruisible. La solution commence par rendre les données prévisibles, pas par deviner ce qui manque.

Seeds et fixtures : quand et quoi utiliser

Un environnement local reproductible commence par une décision : aidez-vous les gens à utiliser l'app manuellement ou à vérifier le comportement automatiquement ? Ce choix vous indiquera si vous avez besoin de seeds, de fixtures, ou des deux.

Considérez-le ainsi :

• Les migrations changent la forme de la base (tables, colonnes, index). Elles ne devraient pas dépendre d'utilisateurs d'exemple ou de commandes factices.
• Les données d'amorçage donnent aux développeurs une base prévisible pour que l'interface ne soit pas vide et que les flux courants soient faciles à tester manuellement.
• Les fixtures donnent aux tests des entrées connues pour que les vérifications automatisées s'exécutent de la même manière à chaque fois.
• Les factories (optionnelles) créent des enregistrements à la demande, souvent comme alternative plus souple aux fixtures statiques.

Séparez votre base dev et votre base de tests. Les données dev sont pour les humains qui explorent les fonctionnalités. Les données de test sont pour l'automatisation : elles doivent être isolées, réinitialisées souvent et sûres à exécuter en parallèle. Les mélanger conduit à des tests qui passent sur une machine et échouent ailleurs.

Quand vous choisissez ce qui doit paraître « réel », visez le réalisme là où il affecte la logique, pas là où il ajoute du bruit. Conservez des rôles, permissions et statuts d'edge-case réalistes, mais utilisez des noms factices, des emails bidons et des détails de paiement fictifs.

Une règle pratique est simple : seedez un petit nombre de flux complets (2–3 utilisateurs, 1 org, une poignée d'enregistrements par écran). Ajoutez un ou deux cas volontairement bizarres (jeton expiré, compte désactivé, état vide) pour couvrir les branches UI. Évitez les blobs énormes comme des images ou de gros logs ; utilisez des stubs qui déclenchent toutefois les mêmes chemins de code. Ne seedz jamais de secrets. Et quand cela aide, rendez les IDs et timestamps déterministes pour que les captures d'écran et le debug correspondent entre machines.

Concevoir un setup local que l'on peut reconstruire à tout moment

Un setup n'est « simple » que si vous pouvez tout supprimer et revenir à une appli fonctionnelle sans vous souvenir d'étapes secrètes. C'est le cœur d'un environnement de dev local reproductible : une machine fraîche doit se comporter comme la vôtre.

Choisissez une commande unique qui crée la base depuis zéro, et faites-la sûre à exécuter plusieurs fois, même si la base existe déjà. Les nouveaux contributeurs ne devraient pas deviner quels scripts lancer et dans quel ordre.

Les commandes de reset les plus fiables font toujours la même chose : effacer ou recréer la base locale, appliquer les migrations, charger les données de seed pour le développement quotidien, démarrer les services requis, et afficher l'étape suivante (y compris comment se connecter).

Conservez la source de vérité du schéma dans les migrations, pas dans du SQL édité à la main dans un wiki ou des commandes « fix » ponctuelles que les gens exécutent une fois. Si quelqu'un modifie une table localement et oublie de capturer le changement dans une migration, vous aurez des bugs mystérieux où « ça marche sur ma machine » devient normal.

Créez un utilisateur de base local dédié avec des permissions limitées. Ça semble du travail en plus, mais ça attrape des erreurs réelles tôt. Par exemple, si l'app tente accidentellement de créer des tables à l'exécution, un utilisateur verrouillé échouera rapidement au lieu de masquer le problème jusqu'en production.

Les services optionnels sont souvent la zone où les setups deviennent désordonnés. Décidez de ce qui est requis et de ce qui est optionnel. Si Redis, S3 ou l'email sont optionnels, faites en sorte que l'app démarre sans eux et affiche un message clair quand une fonctionnalité est indisponible. Une approche commune est de supporter des versions locales « factices » (stockage fichier au lieu de S3, boîte locale au lieu d'un vrai envoi) et d'activer les intégrations réelles seulement lorsqu'un développeur choisit de le faire.

Écrire des scripts de seed qui produisent toujours les mêmes données

Un script de seed n'est utile que s'il est ennuyeux. Lancez-le aujourd'hui, la semaine prochaine ou sur un portable neuf, et vous devriez obtenir les mêmes enregistrements, les mêmes identifiants de connexion et les mêmes écrans de démonstration.

Choisissez un ordre de seed fixe basé sur les dépendances. Si des projets appartiennent à des orgs, et des orgs à des utilisateurs, seedz les utilisateurs d'abord, puis les orgs, puis les projets, puis tout ce qui s'attache aux projets (tâches, factures, commentaires). Cela évite les erreurs de type « parent manquant » et garde les clés étrangères cohérentes.

Utilisez des identifiants stables ou des clés naturelles pour que les données ne dérivent pas. Tout ce à quoi vous référez plus tard devrait avoir un identifiant permanent (email utilisateur, slug d'org, ou un UUID fixe codé en dur dans le seed). Évitez les noms aléatoires, UUID aléatoires ou « insérer et espérer obtenir id 3 », car les relances et différents moteurs de BD changeront les résultats.

Rendez le script idempotent : on doit pouvoir le relancer sans créer de doublons. Au lieu d'insérer systématiquement, faites des upserts par la clé naturelle (email, slug, external_id). Si vous avez besoin d'un reset complet, faites-le volontairement (vider les tables d'abord, ou supporter un flag --reset), pas accidentellement.

Il aide aussi de garder les paramètres de seed en un seul endroit : nombres (combien d'orgs/projets/enregistrements), feature flags, identifiants demo fixes et bascules d'environnement (seed rapide vs seed complet). Quand ces valeurs sont dispersées, chaque machine finit « proche, mais différente ».

Construire des fixtures qui couvrent de vrais cas UI et API

Les fixtures sont des petits jeux de données connus que vous chargez pour que les écrans et endpoints se comportent de la même façon à chaque fois.

Commencez par quelques enregistrements réalistes liés à vos flux les plus utilisés. Pensez en clics : se connecter, arriver sur un tableau de bord, voir une liste, ouvrir une page de détail, enregistrer une modification. Si votre appli a des organisations et des projets, une org avec deux projets, quelques tâches et un élément d'activité récent suffit souvent pour activer la plupart des chemins UI et API sans créer un dataset gigantesque.

Ajoutez ensuite des edge cases volontairement. Il n'en faut pas beaucoup, mais il faut ceux qui cassent couramment :

• Un état vide (une nouvelle org sans projets)
• Un nom long (mise en page et troncature)
• Un utilisateur désactivé (accès et messages)
• Champs optionnels manquants (gestion des null)
• Une limite de permission (peut voir mais pas modifier)

Gardez les fixtures lisibles et faciles à comparer en revue de code. YAML, JSON ou un petit fichier TypeScript conviennent. Choisissez un style et tenez-vous-en. Utilisez des IDs et timestamps stables quand possible, afin que les snapshots, le tri et les widgets “activité récente” ne changent pas au hasard.

Documentez enfin l'intention là où les données vivent. Un court commentaire comme « Utilisé pour l'état vide de la page Paramètres » fait gagner du temps plus tard.

Étape par étape : une commande qui configure tout

Un environnement local reproductible paraît presque sans effort lors de l'onboarding : quelqu'un lance une commande et n'a pas besoin d'étapes spéciales depuis le chat.

Votre commande unique de setup doit effectuer la même séquence à chaque fois :

1. Réinitialiser la base locale en toute sécurité. Utilisez un nom de base dev dédié et une vérification de sécurité évidente (par exemple, refuser d'exécuter si NODE_ENV=production).
2. Appliquer les migrations depuis zéro. Le schéma ne doit être créé que via des migrations pour que la base corresponde à ce que CI et la production attendent.
3. Charger un petit jeu de données de base stable. Insérez uniquement ce dont l'app a besoin pour démarrer (rôles, feature flags, quelques produits, une org).
4. Créer des identifiants locaux utilisables. Seedz quelques logins connus (admin et utilisateur normal) et toutes les fausses clés API que l'app attend, uniquement pour l'usage local.
5. Lancer un quick smoke test. Taper un endpoint, rendre une page clé ou exécuter un petit fichier de test pour que les échecs apparaissent immédiatement.

Un pattern concret est d'envelopper cela dans un script que les devs lancent depuis la racine du repo :

./dev/setup

Ce script peut afficher ce qu'il a fait et quoi tester ensuite, par exemple : « Connexion admin : [email protected] / password123 » et « Executer : ./dev/smoke ». Gardez la sortie courte et pratique.

Rendre les scripts d'onboarding conviviaux pour les nouveaux contributeurs

Un bon script d'onboarding ressemble à un guide utile, pas à un puzzle. Les nouveaux contributeurs doivent pouvoir cloner le repo, lancer une commande et obtenir une appli fonctionnelle sans demander d'étapes secrètes.

Rendez la voie de reset sûre et évidente. Si quelqu'un exécute une commande de reset, elle doit cibler uniquement des ressources locales et dire ce qu'elle va supprimer avant de le faire. Une vérification simple (ou exiger un flag --yes) évite les accidents.

Supportez les variables d'environnement, mais ne faites pas chercher. Fournissez des valeurs par défaut sensées pour le nom de la base, le port et l'email admin. Si votre appli a vraiment besoin d'une valeur réelle (comme une clé API), échouez vite et dites exactement quoi faire.

Les petits détails comptent. Après un run réussi, affichez un court résumé : base créée, migrations appliquées, utilisateurs seedés, et les identifiants exacts de connexion (email, mot de passe, rôle). Si votre appli a plusieurs services, indiquez où chacun tourne et quoi vérifier si un port est occupé.

Erreurs courantes qui font perdre des heures

La plupart des douleurs de setup local viennent de petits raccourcis qui vont pour une personne puis s'effondrent quand un second contributeur arrive.

Évitez ces pièges courants :

• Bidouiller la base à la main. Une édition SQL rapide ou un dump partagé devient vite obsolète, et une installation propre ne correspondra pas à la machine « qui marche ».
• Données de seed aléatoires sans seed stable. Si IDs, noms d'utilisateur ou timestamps changent à chaque run, vous aurez des bugs instables et des tests flakys.
• Copier de vrais secrets ou des données de production. Partager des .env, committer des clés ou dumper des lignes de prod en local crée des problèmes de sécurité et de comportement.
• Fixtures qui dérivent du schéma. Le setup « réussit », mais les pages plantent ensuite parce que les champs des fixtures ne correspondent plus aux migrations en vigueur.
• Setup qui exige de cliquer dans l'UI. « Fais juste un signup et crée un projet » parait simple jusqu'à ce que ce soit 15 clics dans un ordre fragile.

Un scénario courant est la casse de la connexion parce que le seed a créé des mots de passe aléatoires tandis que les fixtures réfèrent encore à un ancien champ du schéma. Quelqu'un passe une heure à déboguer l'auth alors que le vrai problème est une configuration incohérente.

Vérifications rapides avant de déclarer le setup reproductible

Un setup n'est reproductible que lorsqu'une nouvelle personne peut obtenir le même résultat que vous, sans lire dans vos pensées.

Le test du clone en 5 minutes

Prenez une machine propre (ou un dossier neuf) et agissez comme si vous ne connaissiez rien du projet. L'objectif est d'obtenir une appli fonctionnelle à partir de zéro.

Vous devez pouvoir confirmer rapidement :

• Une nouvelle personne peut lancer le setup sans deviner des étapes manquantes.
• La base peut être effacée et reconstruite en moins de 5 minutes sur un laptop moyen.
• Les scripts de seed peuvent être relancés sans doublons, clés étrangères cassées ou échecs aléatoires.
• Vous avez toujours au moins une connexion fonctionnelle plus quelques scénarios réalistes (admin, utilisateur normal et un état « pas encore de données »).
• Les tests s'exécutent contre une base propre et séparée (pas la base dev).

Si un point échoue, notez précisément où la confusion intervient et corrigez cela en priorité.

Chercher l'état caché

La plupart des problèmes « ça marche sur ma machine » viennent d'état qui vit en dehors de vos scripts : un utilisateur créé manuellement, un fichier local avec des secrets, une migration appliquée une fois seulement, ou des données laissées la semaine dernière.

Un moyen rapide de le détecter est de reconstruire deux fois de suite : réinitialisez la base, lancez le setup, démarrez l'app, puis réinitialisez et faites-le à nouveau. Le second run devrait être identique au premier.

Exemple concret : si votre seed crée un utilisateur [email protected], le script doit upserter ou recréer proprement cet utilisateur à chaque fois, et le mot de passe doit être documenté en un seul endroit.

Exemple : intégrer un nouveau contributeur en 30 minutes

Un nouveau contractuel arrive lundi matin. Il a le repo, mais pas le contexte, pas de base existante et pas le temps de créer manuellement comptes et exemples. L'objectif : qu'il soit productif le jour même, avec les mêmes données de départ que tout le monde.

Il suit le README et lance une commande, par exemple make dev-reset ou npm run dev:reset. Cette commande supprime la base locale, la recrée, applique les migrations, charge les seeds et installe un petit ensemble de fixtures. À la fin, l'app démarre avec une connexion prévisible.

Le contractuel se connecte avec un compte seedé comme [email protected] et un mot de passe connu. Le compte est déjà lié à une organisation, un workspace et deux projets. Un projet inclut des relations « assez réelles » : quelques utilisateurs, quelques rôles, une facture payée, un paiement échoué et un élément avec des commentaires. Les écrans clés se chargent immédiatement sans configuration manuelle.

En moins de 30 minutes, il peut lancer le setup, se connecter, ouvrir le tableau de bord et les vues de détail du projet, déclencher un edge case connu (par exemple une bannière « paiement échoué ») et reproduire un bug signalé contre le même jeu de fixtures que tout le monde utilise.

Lorsque le schéma change, traitez les fixtures comme du code, pas comme des exemples jetables. Une habitude simple aide : mettez à jour les migrations d'abord, puis les scripts de seed (en conservant IDs et timestamps stables), puis rafraîchissez les fixtures et ajoutez un rapide smoke check (connexion, chargement des pages principales).

Prochaines étapes : maintenir la stabilité au fur et à mesure que l'app grandit

À mesure que les fonctionnalités s'accumulent, le setup local est souvent la première chose qui pourrit. La meilleure défense est de garder votre liste de « données minimales utilisables » courte et écrite. Pensez à l'ensemble minimal d'enregistrements nécessaires pour utiliser l'app de bout en bout : un utilisateur qui peut se connecter, un workspace ou projet, quelques éléments réalistes, et les rôles ou paramètres qui font fonctionner les écrans principaux.

Une fois ce minimum identifié, protégez-le avec deux habitudes : une commande de reset que les gens utilisent vraiment, et un petit jeu de fixtures de base qui ne change que lorsque le produit change réellement.

Une routine légère de maintenance aide aussi : une fois par mois, reconstruisez depuis zéro sur une machine propre (ou un conteneur/VM) et chronométrez. Si ça prend plus de 10–15 minutes ou nécessite des modifications manuelles, corrigez-le immédiatement. C'est aussi un bon moment pour rechercher des secrets dans les fichiers de seed et confirmer que l'auth fonctionne sur une base toute neuve.

Si vous traitez une codebase générée par l'IA qui ne fonctionne que sur un laptop, ce n'est généralement pas seulement des « données manquantes ». C'est des migrations incohérentes, des valeurs par défaut d'auth fragiles et des scripts qui ne réussissent qu'une fois. FixMyMess (fixmymess.ai) se concentre sur le diagnostic et la réparation de ces problèmes, particulièrement pour des prototypes créés avec des outils comme Lovable, Bolt, v0, Cursor et Replit, afin que les équipes puissent reconstruire leurs bases locales et de test de manière prévisible et avancer en confiance.