Journal Documenter ou tester, il faut trancher (j'ai pas trouvé de rime avec choisir...)

Posté par  (site web personnel) . Licence CC By‑SA.
Étiquettes :
27
6
fév.
2025

Sommaire

La dernière fois que j'ai écris sur LinuxFR, j'ai eu une tonne de commentaires utiles, des idées, des critiques, pleins de références comparables à ce que je proposais. C'était exactement ce que je demandais.

Il se trouve que c'est aussi exactement ce dont j'ai besoin aujourd'hui, donc… ben je reviens!

J'ai créé un outil de test, qui me paraît présenter un rapport efficacité / courbe d'apprentissage / utilité très intéressant.
(Oui, je sais, quand on a plus d'un '/' dans la phrase, on ne sait plus bien de quel rapport on parle, mais tu vois l'idée!)
Cette fois-ci, j'ai bien cherché s'il avait de l'existant avant de me lancer, parce que le domaine du test est exploré depuis la nuit des temps informatiques, qu'il y a des dizaines d'outils existant, et donc j'étais sûr de trouver quelque chose.

Mais non. Et donc je pense que j'ai fait quelque chose de nouveau, n'ayons pas peur des mots.

Oui, mais tu cherchais quoi?

Mes deux derniers projets sont des applis en ligne de commande. Elles prennent des choses en entrée, et recrache des choses en sortie.
Les traitements étant rapide, je me suis retrouvé avec 95% de tests end-to-end, comme on dit dans la langue de Donald Molière, et malgré tout une suite de tests qui s'exécute en moins de deux minutes.

J'avais tout naturellement commencé par un petit Makefile, qui lançait l'appli avec les bonnes options, puis un diff de la sortie obtenue avec la sortie attendue.
La suite de tests prenant des stéroïdes, je me suis retrouvé avec une hiérarchie de répertoire de test et de Makefile.
En parallèle, comme je suis un bon gars à l'écoute des "bonnes pratiques", j'ai ajouté dans mes Makefile la génération de la description des tests, et des résultats, qui se retrouvaient à la fin du process dans des fichiers Markdown ou html.
Au début j'avais le sourire, c'était beau à voir tourner.
Puis, à force d'ajouter des tests, j'ai fini par avoir des Makefile d'une longueur énorme, avec une partie documentation pas facile à mettre à jour.

Et ça m'a gonflé.
En informatique, il y a beaucoup de bonnes idées qui ont commencées par un gros soupir de lassitude.

La lettre au père noël

Tant qu'à viser la lune, ça ne me fait pas peur d'en demander beaucoup.
(Oui, il y a de vrais références culturelles dans ce journal)

Première chose, générer la doc. Hashtag #docascode, tout ça.
OK, mais si on prenait la chose au premier degré, et qu'on générait les tests à partir de la doc, et pas le contraire?
Idée vieille comme le monde info… (ah non je l'ai déjà faite, celle là).
Pas question ici néanmoins de sortir les grands moyens, AGL, méthodes formelles, etc. : je développe sur mon temps libre des applis pour m'amuser, pas pour me faire certifier SIL 13 ou DO 178 Z. Il faut que ça reste simple, le but étant de gagner du temps pour un dev "classique".

Pour que ce soit vraiment cool, il faudrait que la doc utilisateur et le script de test ne fasse qu'un. Et que ce soit en anglais, pas dans un langage de programmation ou de script.
L'air de ne pas y toucher, avec cette dernière exigence, je viens de faire sauter 99% de l'offre disponible. En effet, à ma grande surprise, je n'ai pas trouvé d'outil simple qui permette une exécution directe de la doc décrivant le comportement souhaité de l'appli en anglais "normal".

L'utilisation du langage naturel est un vieux dada pour moi. Aussi me suis-je demandé dans quelles conditions, forcément restrictives, je pourrais l'utiliser.
Le premier tour de piste a montré que l'essentiel de mes tests :
1. créaient des fichiers de donnée
2. lancaient mon appli avec les bonnes options
3. vérifiaient les sorties

En utilisant un formalisme Gherkin, ca donne quelque chose comme :
Given the input file machin containing mes datas
When I run mon_app --input=machin
Then I get résultat_attendu

On a pas besoin d'une grammaire sophistiquée. En réalité, je n'ai même pas besoin d'une grammaire complète, au sens où nous l'entendons pour les langages de programmation. (Après avoir codé mon proto, j'ai trouvé des références (rares) sur le net qualifiant ce que j'avais fait de partial parsing, et ça existe depuis 60 ans)

Ca va être moche?

Pour rappel, le but c'est de faire uniquement une documentation "utilisateur".
Dans mes projets, j'utilise MarkDown. (Pour les exigeants, je précise que asciidoc ou autre sont dans la roadmap, en attente d'une demande sérieuse!)
Le principe général "ce dont tu as besoin existe déjà quelque part" n'a pas fonctionné avec l'outil, mais ça a fonctionné avec le format: les gens de Gherkin ont déjà défini une déclinaison Markdown du format Gherkin initial, MDG, que j'ai trouvé très bien, et immédiatement adopté.

Un scenario minimal, ce sera par exemple : 

# Scenario: gcc illegal option

(Je prends gcc comme exemple, tout le monde connaît)

- When I run `gcc -tr`
- Then I get an error
- And the output contains `error: unrecognized command-line option`

Et la beauté de la chose, c'est que grosso modo tout ce qui n'est pas dans une ligne Given / When / Then n'est pas interprété par l'outil. Donc on peut vraiment faire une doc à sa guise, avec le plan que l'on veut, en insérant des graphiques, des tableaux, etc.

Sur la forme, c'est du markdown, le rendu n'est pas moche, c'est même beau.

Sur le fond, quand on regarde les fichiers d'entrées qui sont acceptés par l'outils, il est difficile de distinguer la partie qui est du commentaire de la partie qui est exécutée, qui est également écrite dans un anglais presque fluide, non informatique en tout cas.
On peut dire que le but de lisibilité et ouverture à une population de non programmeur est atteint.

Silence, ça tourne

L'outil s'appelle bbt, ce qui veut simplement dire black box tester.
Le proto a rapidement produit un résultat correct, validant le concept.
Je peux même dire à ma grande surprise.

Mon test case est l'un de mes deux projets évoqués ci-dessus, et j'ai donc commencé à migrer mes gros Makefile vers la nouvelle solution. Puis j'ai fait une annonce limitée dans le monde Ada pour avoir les premiers retours utilisateurs.
L'outil est écrit en Ada, c'est mon choix. (j'ai prévenu, gros contenu culturel dans ce texte)
Mais en fait ça n'a aucune importance pour l'utilisateur, on utilise un exe, il n'y a par principe rien à coder ni rien a stubber ou linker avec l'appli.

Pas de chance, mon premier utilisateur enthousiaste était sous Windows. J'avais packagé mon logiciel sous Alire (le cargo d'Ada), et le process de soumission du crate vérifie que ça compile sous Windows et MacOS, mais je n'avais jamais lancé l'appli et encore moins exécuté la suite de test en dehors de Linux.

Incroyable mais vrai, ça marche, et il réussi à l'utiliser. (C'est quand même bien Ada!)
Heureusement d'ailleurs, parce que je voulais des retours sur les fonctionnalités, mais pas perdre mon temps avec de la portabilité. Et bien re-incroyable mais vrai, si le deuxième qui l'a utilisé était bien sous Linux, le troisième était sous Darwin!
La totale, j'aurai du faire appel à linuxFR en premier…

Quoi qu'il en soit, ils m'ont fait des remarques pertinentes, que j'ai prise en compte.
Ils ont utilisé l'outil tout à fait dans l'esprit : globalement, ils ont un fichier markdown qui décrit leur acceptance tests, l'ensemble étant exécuté avec une ligne dans un Makefile.
On ne peut pas faire plus simple et rapide.

Au mois de décembre, j'essaie l'outil en participant (une seule journée) aux défis de codage The Advent of Code.
Le résultat est là : les tests sont tellement rapides à écrire que je passe bien 95% de mon temps sur le code, ce qui est l'objectif.
(Le code est disponible ici, le scenario de test est dans le fichier .md).

Je prévoyais de faire mûrir l'outil encore un peu dans la discrétion, mais au mois de janvier, surprise, AdaCore, que je remercie une fois encore, attribue le prix "Ada crate of the year 2024" à bbt!

Donc je sors du bois.

Mais alors, c'est un outil de doc ou un outil de test? BDD ou test unitaire?

Bonnes questions.
Ce qui est sur, c'est que si tu écris la doc avec bbt, tu n'as pas de tests à écrire.
(hashtag #runthedoc)
Et si tu écris des tests avec bbt, ces tests seront documentés.

Mais tu n'as qu'un seul des deux à faire.

Sur l'esprit : si tu es dans une logique très Gherkin, tu va respecter certaines règles, officielles ou officieuses. Par exemple, mettre un seul "Then" par scenario,
(bbt dispose même d'une option --strict pour vérifier celà), ou respecter un plan de présentation identique pour chaque Feature, suivant tes habitudes ATDD, BDD, etc.

Mais si tu es dans une démarche de test, tu peux faire au plus simple.
L'exemple ci-avant qui teste la réaction de gcc à une mauvaise option sur la ligne de commande contient seulement un scenario, pas de Feature, ce qui est illégal en Gherkin.
De même, pour un test de non régression qui reproduit un bug utilisateur, on a envie de mettre toute les actions qui amènent au bug à la suite: on va avoir plusieurs "When", entrelacés avec des "Then", et peut être même des "Given" après le premier "When".

Ces deux points ne posent pas de problème à bbt : bbtest là pour aider, pas pour juger.

(mon service marketing a insisté pour que je mette cette formulation ici)

Et maintenant?

J'ai le sentiment que tout le monde a, à un moment ou un autre, quelques tests à faire rapidement sur un exe, et que bbt est tellement rapide à mettre en oeuvre qu'il peut être utile pour un très grand nombre de développeur.
Mais en fait je n'en sais rien, je me suis trop souvent enthousiasmé pour des idées qui au final n'intéressaient que moi.

C'est pourquoi je suis très curieux de l'accueil que vous ferez à l'idée d'avoir des tests exécutés à partir d'un document de spécification, et vous remercie par avance pour tout retour sur le concept, l'usage, la doc… sur tout en fait.

Le projet est très jeune (version 0.0.7, c'est tout dire). Il a déjà des cool-features, que je n'ai pas abordées ici. Mais si vous avez des idées nouvelles, je suis à l'écoute, dite moi!

Références

  • # Documentation exécutable, expect, tests unitaires

    Posté par  . Évalué à 5 (+3/-0). Dernière modification le 06 février 2025 à 06:05.

    La doc exécutable, je trouve ça très malin. Ça peut encourager à écrire de la doc quand on écrit des tests, et vice versa. D'une pierre deux coups, on améliore la qualité et la maintenabilité d'un logiciel. Avec une garantie que la doc est correcte et à jour, voire complète si on vérifie la couverture du code. Et des tests lisibles, compréhensibles et qui ont du sens. Ça me donne envie de m'y mettre.

    Ça fait beaucoup penser à l'outil unix expect, qui peut lancer des programmes, écrire dans l'entrée standard, tester la sortie… C'est très complet, et de façon amusante, dans le basique de chez basique, ça ressemble un peu à la grammaire de ton outil : les commandes commencent par un verbe en anglais.

    Par contre, ce n'est pas du tout orienté doc ; tu écrits un script expect quoi.

    Du coup, en partant de la supposition qu'il y aura fatalement des cas demander une telle complexité, ton outil propose-t-il des fonctionnalités du même genre qu'expect, ou est-ce prévu ?

    J'ai l'impression que quelqu'un pourrait implémenter ton idée en faisant un préprocesseur pour expect, qui mange du markdown ou autre en ne gardant que les lignes à destination de l'outil, et qui sort des scripts expect. Est-ce une piste que tu avais envisagé ?

    Y a-t-il des plans pour sortir du modèle "appeler un binaire" et permettre l'exécution des tests dans un code de test ? Ça donne envie de pouvoir documenter et tester des appels de fonctions / méthodes comme ça, où les exemples dans la doc seraient en fait des cas de tests. (Pour le coup, j'ai la vague impression qu'une implémentation en mode préprocesseur pour expect serait un poil incompatible) (et je comprends bien que ça sort probablement très largement du scope de ton implémentation et qu'un outil pour faire une chose bien, c'est pas mal aussi)

    Je suppose que ça demanderait de fournir une bibliothèque et des bindings dans chaque langage de programmation, où le fonctionnement actuel serait juste l'utilisation du binding pour le shell unix.

    En tout cas merci pour l'idée et le partage, et l'outil en libre. Que je me mette à utiliser ton implémentation ou non, c'est inspirant.

    • [^] # Re: Documentation exécutable, expect, tests unitaires

      Posté par  (site web personnel) . Évalué à 1 (+0/-0).

      Du coup, en partant de la supposition qu'il y aura fatalement des cas demander une telle complexité, ton outil propose-t-il des fonctionnalités du même genre qu'expect, ou est-ce prévu ?

      Merci pour le retour. Oui Expect est dans le radar.

      J'ai fait une petite liste des choses intéressantes que j'ai trouvé sur le net, qui m'ont inspirées pour des détails de syntaxe ou pour les fonctionnalités : https://github.com/LionelDraghi/bbt/blob/main/docs/comparables.md

      La constante, c'est que tous ces outils utilisent un langage trop éloigné à mon goût de l'anglais pour figurer directement dans une doc. Mon point principal c'est le chemin direct de la doc au test. Et faire une surcouche à Expect pourrait être une solution, mais le contraire est également possible (et a déjà été discuté), c'est à dire utiliser une librairie Ada qui offre une API Expect.

      Sur la roadmap, la fonction d'interaction (être capable de répondre yes ou no quand ça prompte) est prévue. Je n'en ai pas (encore) besoin pour mes applications, mais j'en ai besoin pour tester bbt lui-même, car il prompte l'utilisateur pour confirmer des effacements. Et pour l'instant, je ne teste pas ces comportements.

      De façon générale, les outils disponibles, et en particulier ceux que je liste ci-dessus, offrent plus de fonctionnalité que bbt. Mais bbt vient sur un créneau spécifique, dont la simplicité est une composante importante, et je ne souhaite pas le rendre trop complexe, ni imiter l'existant.

    • [^] # Re: Documentation exécutable, expect, tests unitaires

      Posté par  (site web personnel) . Évalué à 1 (+0/-0).

      Y a-t-il des plans pour sortir du modèle "appeler un binaire" et permettre l'exécution des tests dans un code de test ?

      A partir du moment ou tu te positionnes dans un code de test, ce n'est plus le créneau de bbt : tu peux utiliser des solutions existantes, et le fait d'exprimer le besoin en anglais plutôt que dans tel ou tel langage de programmation perd de son intérêt.

      Ou alors, je n'ai pas compris ce que tu proposes.

      • [^] # Re: Documentation exécutable, expect, tests unitaires

        Posté par  . Évalué à 3 (+1/-0). Dernière modification le 06 février 2025 à 12:45.

        On pourrait avoir un fichier Markdown, tout comme ce que tu as, mais qui, au lieu d'appeler des binaires, appelle des méthodes et des fonctions et teste leurs résultats. Directement lisible en tant que doc.

        Mais pour que ça marche, il faut un moyen d'appeler les tests depuis le système de tests (unitaires) du projet, en fonction du langage utilisé. Faut que le "test runner" trouve les tests dans les fichiers markdown. Pour ça, il faut probablement générer des fichiers de tests habituellement écrits à la main, ou être embarquable en tant que bibliothèque appelée par le "test runner".

        Bon après, peut-être que ça a beaucoup de sens d'avoir un système comme celui que tu proposes pour appeler des binaires parce que la documentation est celle à destination des utilisateurs finaux / utilisatrices finales, mais que ça n'a pas tant d'intérêt que ça pour des tests unitaires et de la doc pour les devs, qui peut se permettre d'être plus technique, avec plus facilement du code mis en avant.

        D'un autre côté, qui n'a jamais cherché comment on utilise un code pas suffisamment documenté en regardant ses tests unitaires, quand une doc lisible aurait été plus appréciable ? Naïvement, un bbt pour les tests unitaires pourrait sembler intéressant. Ça pourrait permettre d'ajouter une rubrique d'exemples d'utilisation pour chaque fonction à cette page par exemple, avec le résultat attendu. Pour certain projets, l'utilisateur final est un·e dev, par exemple pour les frameworks. Peut-être que ça devrait être un outil complémentaire à part, ça résout probablement un problème plus ou moins différent et demande une manière de faire différente.

        En tout cas merci pour tes réponses, bien cool ta doc comparables.md!

    • [^] # Re: Documentation exécutable, expect, tests unitaires

      Posté par  (site web personnel) . Évalué à 3 (+1/-0).

      En Python, il y a les doctests, qui sont des morceaux de code présents (ainsi que la sortie attendue) dans les blocs de documentation. Un outil (doctest) analyse tous les fichiers et exécute les morceaux de code et vérifie que la sortie correspond bien à l'attendu.

      def addition(x: int, y: int) -> int:
    """Additionne deux entiers.
    >>> addition(3, 4)
    7

    """
    return x + y

  • # Très intéressant commme approche

    Posté par  . Évalué à 2 (+2/-0). Dernière modification le 06 février 2025 à 06:10.

    Très intéressant comme approche. Après question outillage cela dépend beaucoup du langage de programmation utilisé : pour ma part j'aime beaucoup l'approche d'une doc rédigée directement dans le code, avec des exemples qui sont testés pour 1) rester à jour avec le code 2) vérifier les propriétés attendues. La doc est ensuite générée pour avoir un manuel approprié et on peut tester la couverture du code testé et documenté.

    Pour Haskell, il y ainsi doctest, très pratique.

    • [^] # Re: Très intéressant commme approche

      Posté par  (site web personnel) . Évalué à 2 (+1/-0).

      pour ma part j'aime beaucoup l'approche d'une doc rédigée directement dans le code, avec des exemples qui sont testés

      Merci pour le retour.
      Je ne vise pas en fait ce type de documentation, qui explicite le code et le design, et donc est légitime à être dans le code, et qui se destine aux personnes qui doivent intervenir dans le code ou la conception.

      Je cible plutôt une documentation vraiment "utilisateur", qui décrit le comportement attendu (cf. BDD, ATDD).

  • # Et l’approche inverse ?

    Posté par  . Évalué à 2 (+2/-0).

    Je viens de réaliser que ce serait peut-être plus simple de générer la doc à partir du code de test plutôt que l’inverse. C’est-à-dire utiliser l’approche programmation lettrée, où on mêlerait pure texte avec le langage de test plus formel, ce dernier étant ensuite remplacé par du texte à la génération de la doc ou exécuté quand on lance les tests. La différence avec l’approche présentée dans le billet est juste que le langage de test est clairement séparé et plus formel.

    Dans un autre domaine, je me souviens de Catala pour les textes législatifs, vous connaissez ?

    • [^] # Re: Et l’approche inverse ?

      Posté par  (site web personnel) . Évalué à 1 (+0/-0).

      La différence avec l’approche présentée dans le billet est juste que le langage de test est clairement séparé et plus formel.

      En fait, la différence essentielle est la nature du besoin, ce que j'ai évoqué dans ma réponse précédente. L'objectif n'est pas ici de faire du test unitaire, de définir, documenter ou prouver formellement le comportement du code.

      L'objectif est de décrire le comportement de l'appli vue de l'utilisateur. bbt est destiné au test "end-to-end", pas aux tests unitaires ou aux test d'intégration ou autre.

      Je viens de regarder Catala, très intéressant. C'est un DSL spécialisé, il y a bien un rapport avec bbt.
      Mais bbt fait en sorte que son DSL se fonde dans la langue anglaise (en masquant un cadre Gherkin et une syntaxe spécifique), Catala utilise une syntaxe très informatique, avec des if then else.

      Mais le use case de Catala est beaucoup plus complexe que celui de bbt, me semble-t-il, car pour l'analyse de texte juridique, si on a pas une modélisation formelle comme celle proposée par Catala, on doit en passer par des LLM, avec pas mal de verrous technologiques à la clé. Je sais que l'activité sur ce sujet est vraiment intense, mais je ne suis pas un spécialiste et je ne veux pas commenter.

    • [^] # Re: Et l’approche inverse ?

      Posté par  (site web personnel, Mastodon) . Évalué à 2 (+0/-0). Dernière modification le 07 février 2025 à 00:34.

      Pour la programmation lettrée en Ada, différentes chose ont été discutées et il y a même AWEB et Atangle qui ont vu le jour, puis récemment revtang. Ça vient de me rappeler que c’est dans ma liste de choses à explorer dès que j’ai des congés.

      Dans le cas présent, je me demande si on ne peut pas appeler cela, en miroir, du test lettré…? :D

      Édition : on en avait parlé ici de Catala ;)

      “It is seldom that liberty of any kind is lost all at once.” ― David Hume

      • [^] # Re: Et l’approche inverse ?

        Posté par  (site web personnel) . Évalué à 1 (+0/-0).

        Drôle, le deuxième lien sur la discussion, c'est vieux de vingt ans mais j'y avais participé!

        Comme aujourd'hui, je ne devais pas être convaincu par la machine à gaz du literate programming, qui était le sujet initial, et j'étais parti sur une façon pragmatique de générer de la doc à partir du code (ce qui n'est pas du literate programming).

        Bref, je ne sais pas ce qu'est le literate programming, mais je vois un point commun avec bbt : la documentation contient des tests, avec une description malgré tout formelle, au milieu d'un texte libre.

        Et une différence : il y a bien un mélange entre formel et informel (Donald Knuth parle de la nécessité d'avoir les deux pour que ce qu'il y a à comprendre rentre bien dans le crâne du lecteur). Mais sur la partie formelle (c'est à dire en gros les steps) on essaie d'être en anglais, aussi lisible que la partie informelle.

        Ce qui a bien changé pour moi depuis cette discussion d'il y a 20 ans, c'est que j'ai réalisé à quel point l'exercice de génération de documentation à partir du code était vain.

        1. Je ne lis jamais ces docs. Déjà à l'époque, tout les IDE (moi j'étais sous emacs) permettaient de sauter directement à la déclaration de la fonction truc, ou se trouvaient les commentaires permettant de générer la doc. Donc la doc ne servaient à rien.

        2. Au contraire, les tags mis dans les commentaires pour effectuer la génération viennent rendre la code moche et moins lisible. C'est pourquoi je faisais l'apologie de NaturalDocs à l'époque (et de Markdown maintenant) : embellir, OK, mais l'original doit rester lisible, tant que ce sera la que l'on travaillera en premier lieu.

        3. La doc la plus intéressante contient justement ce qui ne figure pas dans le code, ce que le code ne peut pas transcrire (cf. le niveau sémantique dont je parlais plus haut). Et, petit parallèle avec literate programming, il n'y a pas forcément d'endroit idéal dans le code pour mettre ces infos en commentaire.
          Des choix d'architecture, par exemple, pourquoi les mettres dans un source plutôt qu'un autre? Leurs place n'est en fait pas dans un source, mais dans un doc qui s'appele "choix d'architecture".

        4. je n'utilise plus de header systématique de fichier ou de fonction, qui stimule l'écriture de commentaires à 80% insipide. Si j'ai quelque chose à dire, je le dis. Dans la spec si ça concerne l'utilisateur, dans le body si ça concerne le mainteneur.

        Donc, j'essaie :
        1. d'écrire un code clair (quel pied quand il n'y a pas besoin de commentaire!)
        2. je mets des commentaires là ou il faut, et pas plus.
        3. je n'extrait plus rien du code, si tu veux voir le code, ben va voir le code!
        Mon code est beau :-), il n'a rien à cacher et n'a pas besoin de maquillage. Ton IDE est génial, tu peux naviguer avec, pas besoin d'html.
        4. la documentation qui m'intéresse le plus sur un outil, c'est celle qui m'explique ce que je peux faire avec. Or, et là on rejoint le sujet, cette doc donne généralement des exemples, des limitations et des cas d'erreurs, que l'on retrouve également dans les tests.
        Donc, terminé d'écrire deux fois les choses : maintenant, avec bbt, j'écris un seul des deux.

        Mais peut-être que dans encore 20 ans je dirai tout autre chose :-)

        (Si GPT 13.z me laisse encore programmer).

  • # Solution très (trop?) moderne?

    Posté par  . Évalué à 3 (+0/-0).

    C'est peut-être idiot, mais est-ce que l'écriture de la doc, ça ne serait pas un domaine où un LLM pourrait être particulièrement utile? L'avantage serait de ne travailler que sur le code, et de laisser une machine générer la documentation à partir du code, et éventuellement d'une sorte de description générale des principales fonctions. Il y aurait des erreurs, bien sûr, mais la doc humaine a aussi des erreurs mais surtout elle devient très rapidement obsolète, ce qui ne serait pas le cas de la doc automatique.

    • [^] # Re: Solution très (trop?) moderne?

      Posté par  (site web personnel) . Évalué à 2 (+1/-0). Dernière modification le 06 février 2025 à 14:40.

      pas idiot du tout, débat très intéressant au contraire!

      C'est le problème éternel du niveau sémantique.
      Le besoin du client n'est pas complètement traduit pas dans le code. Le LLM va être très bon pour décrire la logique du code (ca marche déjà très bien et c'est bien intégré dans vscode et autre).
      Mais pour le reste il va inventer, et si le code est faux, il va se tromper.

      Même la conception du logiciel n'est pas complètement traduite dans le code. Je prends un exemple qui provient du README du projet sur lequel j'utilise justement bbt pour faire les tests, acc : si le concepteur définit un logiciel en couches, couche C1 avec les modules A et B au dessus d'une couche C2 avec les modules C et D, le code n'embarque pas cette sémantique.
      Le LLM verra dans le code qu'il y a un include de C dans A, de D dans C, mais il ne verra pas forcément qu'il y a une architecture en couche.

      Parce que, en changeant de niveau sémantique, il y a perte d'information.

      Si on laisse les LLM faire ce qui nous amuse, c'est à dire le code, alors je pense qu'il est plus efficace de procéder dans l'autre sens : il vaut mieux générer le code à partir d'une description du besoin plutôt que de lui demander de reconstituer le besoin à partir du code.

      • [^] # Re: Solution très (trop?) moderne?

        Posté par  . Évalué à 3 (+0/-0).

        Le besoin du client n'est pas complètement traduit pas dans le code.

        Je pense que c'est indéniable, c'est pour ça que je suggérais quand même de rédiger le README ou le cahier des charges, et de laisser le LLM gérer la doc technique, c'est à dire tous les trucs liés au comportement attendu, aux différentes options, etc. Qui de mieux qu'un LLM pourrait documenter le comportement quand un fichier d'entrée est manquant, quand il y a un problème de réseau, etc?

        On s'écarte probablement un peu du sujet de base, mais un problème récurrent pour moi, c'est de chercher comment on fait quelque chose que je pense que le logiciel sait faire. Par exemple, comment passer une image en camaïeu de rose dans Gimp, comment réduire la taille des objets sans changer la distance entre eux dans Blender, etc. Pour ce genre de choses, la doc du logiciel est assez inutile : il faudra utiliser un moteur de recherche interne qui est en général peu efficace, sensible aux fautes de frappe ou à l'utilisation du mauvais terme, etc. Le seul moyen concret, c'est de demander à Google, avec l'espoir que quelqu'un sur un forum a déja posé la question. Et là, c'est le drame, tu as la réponse sur la procédure en 2014, et tout a changé.

        C'est typiquement le genre de situation où un LLM qui a mangé le code et quelques bribes de doc tapées par un humain pourrait être super-performant (*). Les docs des logiciels sont souvent inutiles parce que triviales (du style "Save -> Sauvegarder la version courante du fichier"), trop techniques ("k: valeur du coefficient de Kirwzesky"), obsolètes, et peu opérationnelles (elles décrivent comment le logiciel fonctionne, et pas comment utiliser le logiciel pour faire quelque chose d'utile).

        (*) En fait, je m'aperçois en écrivant que c'est peut-être complètement débile de demander à un LLM comment faire quelque chose quand on peut coupler un LLM avec un agent, qui fera la chose directement. Pour la manipulation d'image, typiquement, ça me semble à la fois faisable et extraordinaire. Du style "isole la fille en rouge du premier plan, corrige les yeux rouges, et insère-là dans un décor de Western avec un colt à la ceinture".

  • # bbt ?

    Posté par  (site web personnel) . Évalué à 2 (+2/-2).

    L'outil s'appelle bbt, ce qui veut simplement dire black box tester.

    et pourquoi pas tbbt ? :p

    (ah, on me glisse dans l'oreillette que TBBT est déjà pris :D)

  • # J'ai compris mais j'ai pas compris

    Posté par  . Évalué à 2 (+0/-0). Dernière modification le 07 février 2025 à 22:45.

    Salut,

    j'ai bien compris l'objectif d'unifier la doc et les tests, et je trouve le parti de bbt d'être facile d'accès super intéressant ! J'ai justement un outil à tester, je vais voir si ça colle.

    Par contre je n'ai pas compris l'intérêt d'avoir les cas de tests et les résultats attendus dans la doc. Je regarde les exemples, ça passe car c'est assez court (par exemple le run_error_msg.md). Mais j'imagine l'équivalent d'une page de manuel comme celle de ls, ce serait un peu indigeste , non ?

    C'est tout à fait possible que je sois à côté de la plaque quand à l'usage dans un certain type de doc, je suis preneur de plus de détails :).

    • [^] # Re: J'ai compris mais j'ai pas compris

      Posté par  (site web personnel, Mastodon) . Évalué à 2 (+0/-0).

      De mon point de vue, les résultats attendus permettent justement de s’assurer du bon fonctionnement (ou de la non régression) d’un côté et —en même temps— d’être des exemples testables dans la documentation. Je ne sais pas si c’est utilisable pour une commande comme ls mais on ne sait jamais.

      “It is seldom that liberty of any kind is lost all at once.” ― David Hume

      • [^] # Re: J'ai compris mais j'ai pas compris

        Posté par  (site web personnel) . Évalué à 2 (+0/-0).

        Mais j'imagine l'équivalent d'une page de manuel comme celle de ls, ce serait un peu indigeste , non ?

        pas forcément : il y aurait plus d'exemples dans la doc' des cas d'usage testés
        et les explications autour

        du gagnant-gagnant :

        • tu montres ce qui est testé ( et qui fonctionne)
        • tu documentes ce qui est fait autour (si cela a besoin d'un test, suffit de l'ajouter)

        perso hormis ls -l et ls -ailrt j'ai pas besoin de beaucoup plus :-)

    • [^] # Re: J'ai compris mais j'ai pas compris

      Posté par  (site web personnel) . Évalué à 2 (+1/-0).

      Mais j'imagine l'équivalent d'une page de manuel comme celle de ls, ce serait un peu indigeste , non ?

      Je ne sais pas, ça serait à explorer, j'attends d'avoir un bon use case!

      J'ai fait un embryon de ce que ça pourrait être avec le début de test de rpl qui se trouve dans les exemples.
      Je ne l'ai fait que pour une option, mais il me semble que ça pourrait s'étendre à plus.

      Je suis d'accord que les Given/When/Then sont un peu lourd dans une doc utilisateur.
      Ça ne dispensera pas de faire plus tard un truc court pour tdlr, de faire une man page, une faq, un guide utilisateur, etc.

      Mais dans un premier temps, le rapport temps passé pour avoir une doc quand même lisible et les tests qui vont avec me parait imbattable. Et pour plein de projet il n'y aura jamais besoin d'aller plus loin.

    • [^] # Re: J'ai compris mais j'ai pas compris

      Posté par  (site web personnel) . Évalué à 2 (+1/-0).

      J'ai justement un outil à tester, je vais voir si ça colle

      Dis moi si je peux aider!

      PS : attention, l'exemple que tu sites (run_error_msg.md) n'est pas dans la suite de tests, c'est du travail en cours. Tout ce qui est exécuté se trouve dans les sous-répertoires de docs, et principalement dans le répertoire features.

    • [^] # Re: J'ai compris mais j'ai pas compris

      Posté par  (site web personnel) . Évalué à 3 (+2/-0).

      Par contre je n'ai pas compris l'intérêt d'avoir les cas de tests et les résultats attendus dans la doc.

      En réalité, ça dépend de quelle doc on parle. Il y a une grande souplesse avec ce système.

      Par exemple dans les tests de bbt, j'ai séparé en plusieurs répertoires.
      1. les fonctions du logiciel : elles sont dans le répertoire features. Il s'agit en réalité de la totalité des tests d'acceptation. Ce n'est pas une doc utilisateur, qui doit être plus synthétique : ici, il y a plein de cas, y compris des tests de robustesses, et ce n'est pas structuré pour être pédagogique.
      2. les exemples : je ne veux pas que la doc donne des tests qui ne marchent plus, à cause d'une typo ou d'une évolution. Le problème est réglé comme ça, les exemples sont dans la suite de tests.
      3. les tests de non reg : en réalité ceux la n'ont rien à faire dans le répertoire docs (je vais les remettre dans le répertoire tests). C'est très utile, mais c'est pour les devs, pas pour les utilisateurs.

      Et dans le répertoire features, il y un sous répertoire proposed_features, qui permet de discuter de fonction non encore implémentées.

      Donc rien n'empêche d'avoir un guide utilisateur avec quelques exemples dans un doc, un cahier de recette avec des tests d'acceptation dans un autre doc, des tests qui ne passent pas encore dans un doc de backlog, etc.

Envoyer un commentaire

Suivre le flux des commentaires

Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.