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.
# Documentation exécutable, expect, tests unitaires
Posté par raphj (site web personnel) . En réponse au journal Documenter ou tester, il faut trancher (j'ai pas trouvé de rime avec choisir...). Évalué à 5. 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.