Kotlin Academy · Lezione

Testare ed evolvere le DSL senza interrompere gli utenti

Progetti API DSL stabili e le testi con blocchi di asserzioni leggibili.

Testare ed evolvere le DSL senza interrompere gli utenti è una lezione Kotlin Academy gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Kotlin Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Kotlin Academy include 4 lezioni in totale.

Perché testare una DSL è diverso

Una DSL è una API pubblica. Le modifiche possono compromettere ogni punto di utilizzo presente nel codice degli utenti. Testare una DSL significa verificare sia l'output prodotto sia la struttura che impone, incluso il fatto che i costrutti non validi continuino a generare errori di compilazione.

Testare l'output della DSL

Il test più semplice consiste nel costruire un oggetto usando la DSL e verificare il risultato del rendering o lo stato interno del builder.

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

Testare lo stato del builder

Anziché testare la stringa renderizzata, testi direttamente il grafo di oggetti del builder. Questo rende i test più robusti rispetto alle modifiche di formattazione:

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

Testare le strutture annidate

Percorra l'albero degli oggetti per verificare le relazioni di annidamento:

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

Test degli errori di compilazione

Non è possibile testare direttamente gli errori di compilazione con gli unit test, ma si possono aggiungere commenti come // This should NOT compile lasciando commentato il codice che fallisce. Alcuni progetti usano la libreria Kotlin Compile Testing per verificare che determinati frammenti di codice NON vengano compilati.

Evolvere una DSL in sicurezza: modifiche additive

L'aggiunta di nuovi parametri opzionali con valori predefiniti o di nuove funzioni del builder è retrocompatibile. I punti di utilizzo esistenti continuano a essere compilati senza modifiche.

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

Modifica incompatibile: rimozione o ridenominazione

Rimuovere o ridenominare una funzione della DSL compromette i punti di utilizzo. Se deve ridenominare una funzione, fornisca un alias deprecato e lo rimuova in una futura versione major:

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

Gestire le versioni della DSL

Per le DSL delle librerie, segua il versionamento semantico. Le modifiche incompatibili alla DSL (funzioni rimosse o tipi di receiver modificati) richiedono un incremento della versione major. Le documenti in un changelog.

Usare @RequiresOptIn per le funzionalità sperimentali della DSL

Contrassegni le estensioni instabili della DSL con @RequiresOptIn. Gli utenti devono accettarle esplicitamente, evitando così di dipendere accidentalmente da funzionalità che potrebbero cambiare:

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

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

Delegazione delle proprietà nelle DSL

Le DSL possono usare la delegazione delle proprietà per imporre i campi obbligatori e fornire messaggi di errore chiari quando manca un valore richiesto:

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 }
}

Test dei contratti tra versioni

Mantenga una raccolta di frammenti «golden» che mostrano l'utilizzo della DSL e li usi come test. Se un refactoring li rompe, la suite di test lo rileva prima degli utenti. Questi frammenti fungono anche da documentazione vivente.

Verifica rapida

Qual è il tipo di modifica a una DSL più sicuro per garantire la retrocompatibilità?

Riepilogo: testare ed evolvere le DSL

Concetti chiave:

Testare l'output della DSL e lo stato degli oggetti builder negli unit test
Le modifiche additive (nuove funzioni o nuovi parametri opzionali) sono sicure
Usare @Deprecated(ReplaceWith=...) per ridenominare senza compromettere gli utenti
Usare @RequiresOptIn per le funzionalità sperimentali della DSL
Mantenere test di utilizzo «golden» per rilevare regressioni tra le versioni

Domande Frequenti

La lezione «Testare ed evolvere le DSL senza interrompere gli utenti» è gratuita?

Sì — il testo completo di «Testare ed evolvere le DSL senza interrompere gli utenti» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Kotlin Academy, passa a CoddyKit PRO. Il corso Kotlin Academy include 4 lezioni in totale.

Cosa imparerò in «Testare ed evolvere le DSL senza interrompere gli utenti»?

Progetti API DSL stabili e le testi con blocchi di asserzioni leggibili. Eserciti Kotlin Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Kotlin Academy?

Non è richiesta alcuna esperienza precedente. Kotlin Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.

Quanto tempo richiede la lezione «Testare ed evolvere le DSL senza interrompere gli utenti»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Kotlin Academy?

Sì. Ogni lezione Kotlin Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Lambda con receiver: la base delle DSL
@DslMarker: impedire la fuoriuscita del receiver
Costruire una DSL HTML/Config type-safe
Testare ed evolvere le DSL senza interrompere gli utenti

← Torna a Kotlin Academy