Kotlin Academy · Leçon

Tester et faire évoluer des DSL sans perturber les utilisateurs

Concevez des API de DSL stables et testez-les avec des blocs d’assertions lisibles.

Tester et faire évoluer des DSL sans perturber les utilisateurs est une leçon Kotlin Academy gratuite sur CoddyKit. Ceci est la leçon 4 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage Kotlin Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours Kotlin Academy comprend 4 leçons au total.

Pourquoi les tests d'un DSL sont différents

Un DSL est une API publique. Ses modifications peuvent casser chaque site d'appel dans le code utilisateur. Tester un DSL signifie vérifier à la fois la sortie qu'il produit et la structure qu'il impose, notamment que les constructions non valides restent des erreurs de compilation.

Tester la sortie du DSL

Le test le plus simple consiste à construire un objet avec le DSL, puis à vérifier le résultat rendu ou l'état interne du générateur.

@Test
fun `div contains a paragraph`() {
    val result = html {
        body {
            div { p("Hi") }
        }
    }
    assertTrue(result.render().contains("<p>"))
}

Tester l'état du générateur

Au lieu de tester la chaîne rendue, testez directement le graphe d'objets du générateur. Cette approche résiste mieux aux modifications de mise en forme :

@Test
fun `server config has correct port`() {
    val cfg = server {
        host = "example.com"
        port = 9090
    }
    assertEquals(9090, cfg.port)
    assertEquals("example.com", cfg.host)
}

Tester les structures imbriquées

Parcourez l'arbre d'objets pour vérifier les relations d'imbrication :

@Test
fun `body contains one div`() {
    val page = html { body { div { } } }
    assertEquals(1, page.children
        .filterIsInstance<Body>().first()
        .children.filterIsInstance<Div>().size
    )
}

Tester les erreurs de compilation

Vous ne pouvez pas tester directement les erreurs de compilation avec des tests unitaires, mais vous pouvez ajouter des commentaires tels que // This should NOT compile en laissant le code qui échoue commenté. Certains projets utilisent la bibliothèque Kotlin Compile Testing pour vérifier que certains morceaux de code NE se compilent PAS.

Faire évoluer un DSL en toute sécurité : modifications additives

Ajouter de nouveaux paramètres facultatifs avec des valeurs par défaut, ou de nouvelles fonctions de construction, est rétrocompatible. Les sites d'appel existants se compilent sans modification.

// Before
fun server(block: ServerConfig.() -> Unit): ServerConfig
// After — additive: new optional feature
fun server(enableMetrics: Boolean = false, block: ServerConfig.() -> Unit): ServerConfig

Modification rompant la compatibilité : suppression ou changement de nom

Supprimer ou renommer une fonction de DSL casse les sites d'appel. Si vous devez la renommer, fournissez un alias obsolète et supprimez-le dans une future version majeure :

@Deprecated("Use database{} instead", ReplaceWith("database(block)"))
fun db(block: DbConfig.() -> Unit) = database(block)

Gérer les versions de votre DSL

Pour les DSL de bibliothèques, suivez la gestion sémantique des versions. Les modifications du DSL rompant la compatibilité (fonctions supprimées, types de récepteurs modifiés) justifient une augmentation du numéro de version majeure. Documentez-les dans un journal des modifications.

Utiliser @RequiresOptIn pour les fonctionnalités expérimentales du DSL

Marquez les extensions instables du DSL avec @RequiresOptIn. Les utilisateurs donnent explicitement leur accord, ce qui évite de dépendre accidentellement de fonctionnalités susceptibles de changer :

@RequiresOptIn(message = "This DSL feature is experimental and may change")
annotation class ExperimentalDsl

@ExperimentalDsl
fun ServerConfig.enableDebug() { /*...*/ }

Délégation de propriétés dans les DSL

Les DSL peuvent utiliser la délégation de propriétés pour imposer les champs obligatoires et fournir des messages d'erreur clairs lorsqu'une valeur obligatoire est absente :

class Required<T> {
    private var value: T? = null
    operator fun getValue(t: Any?, p: KProperty<*>): T = value ?: error("${p.name} is required")
    operator fun setValue(t: Any?, p: KProperty<*>, v: T) { value = v }
}

Tester les contrats entre les versions

Conservez un ensemble de morceaux de code d'utilisation du DSL « de référence » sous forme de tests. Si une refactorisation les casse, la suite de tests le détecte avant les utilisateurs. Ces morceaux servent également de documentation vivante.

Vérification rapide

Quel est le type de modification de DSL le plus sûr pour assurer la rétrocompatibilité ?

Récapitulatif : tester et faire évoluer les DSL

Points essentiels :

Tester la sortie du DSL et l'état des objets du générateur dans des tests unitaires
Les modifications additives (nouvelles fonctions ou nouveaux paramètres facultatifs) sont sûres
Utiliser @Deprecated(ReplaceWith=...) pour renommer sans casser le code des utilisateurs
Utiliser @RequiresOptIn pour les fonctionnalités expérimentales du DSL
Conserver des tests d'utilisation de référence pour détecter les régressions entre les versions

Questions Fréquemment Posées

La leçon « Tester et faire évoluer des DSL sans perturber les utilisateurs » est-elle gratuite ?

Oui — le texte complet de « Tester et faire évoluer des DSL sans perturber les utilisateurs » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours Kotlin Academy, passe à CoddyKit PRO. Le cours Kotlin Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Tester et faire évoluer des DSL sans perturber les utilisateurs » ?

Concevez des API de DSL stables et testez-les avec des blocs d’assertions lisibles. Tu pratiques Kotlin Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer Kotlin Academy ?

Aucune expérience préalable n'est requise. Kotlin Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 4 sur 4.

Combien de temps prend la leçon « Tester et faire évoluer des DSL sans perturber les utilisateurs » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon Kotlin Academy ?

Oui. Chaque leçon Kotlin Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

Lambda avec récepteur : fondement des DSL
@DslMarker : empêcher les fuites de récepteurs
Construire un DSL HTML/de configuration sûr du point de vue des types
Tester et faire évoluer des DSL sans perturber les utilisateurs

← Retour à Kotlin Academy