S01E106 — 11-11-2024.

Les méfaits d’une mauvaise documentation.

jour 106.

Je travaille sur du AstroJS saupoudré de TypeScript dans ma mission actuelle. J’aime beaucoup l’approche et la simplicité du langage surtout le fait qu’on utilise du VanillaJS et que ça c’est cool. Pas besoin de framework modernes pour créer un site statique. Par contre, il y a des trucs qui me dérangent. D’apparence, la documentation paraît riche et fournie au premier abord, Par contre, face à des cas concrêts comme par exemple les tests unitaires — c’est grave relou.

Dans le projet, on utilise l’API Container d’Astro pour implémenter nos tests unitaires. Nous testons, le composant suivant :

MonComposant.astro

<div>
  <slot />
</div>

Le slot est un emplacement réservé pour du contenu HTML externe (d’après la documentation Astro). Je peux ensuite l’utiliser comme ceci :

index.astro

<MonComposant>
  <div>1</div>
  <div>2</div>
  <div>3</div>
</MonComposant>

Ce qui génèrera du HTML :

index.html

<div>
  <div>1</div>
  <div>2</div>
  <div>3</div>
</div>

Voilà, ça marche bien et on est content. Maintenant, pour tester le slot. On procède ainsi :

import { expect, it } from "vitest";
import MonComposant from "./MonComposant.astro";
import { renderToString } from "../lib/test-utils.ts";

test("MonComposant", async () => {
  const result = await renderToString(MonComposant, {
    slots: {
      default: "Je suis un emplacement réservé",
    },
  });

  expect(result).toContain("Je suis un emplacement réservé");
});

Ce qui génèrera du HTML :

<div>Je suis un emplacement réservé</div>

Ce test est correct. Yeaaaaaaah ! Brrr brrrr brrrrrrrrrrrrrr !

C’est bien pour testé un slot vite fait. Maintenant comment qu’on fait pour tester des balises enfants. Logiquement, tu te dis :

import { expect, it } from "vitest";
import MonComposant from "./MonComposant.astro";
import { renderToString } from "../lib/test-utils.ts";

test("MonComposant", async () => {
  const result = await renderToString(MonComposant, {
    slots: {
      default: "<div>1</div><div>2</div><div>3</div>",
    },
  });

  expect(result).toContain("Je suis un emplacement réservé");
});

C’est la que le caca commence. Puisque la propriété default qui est dans l’objet slots va être nettoyé sans être considéré comme des balises HTML. Et va créer le code suivant :

<div>&lt;div&gt;1&lt;/div&gt;&lt;div&gt;2&lt;/div&gt;&lt;div&gt;3&lt;/div&gt;</div>

Je comprends le besoin, cependant Astro utilise cheerio sous le capot. Du coup, on n’a pas la possibilité de sélectionné les balises enfants. On peut transformer l’ensemble des enfants en text malheureusement ça va donner 123. Relou ! Si jamais tu sais comment faire, vasy, balance le jutsu.

Après ça reste expérimental, mais ça casse les burnes dans l’urne. C’est pourquoi, je considère qu’une documentation imprécise est un obstacle pour les développeurs. Derrière, cela nous rajoute du temps de compréhension, d’implémentation, de recherche inutile. Ce qui peut entraîner des erreurs coûteuses. Je comprends le concept de l’expérimentation. Tout de même, il faut fournir un minimum requis et aussi se rapprocher au mieux du comportement du langage de programmation avec lequel la librairie/framework est implémentée. On perd toute notion d’intuitivité, je suis frustré à me battre sur des choses qui sont censés être simples.

Stp ! Si tu cherches à créer des outils ou des APIs fait un baye simple.

@invisageable