0Pricing
Kotlin Academy · Lekcja

Testowanie i rozwijanie DSL bez łamania zgodności użytkowników

Projektuj stabilne API DSL i testuj je za pomocą czytelnych bloków asercji.

Testowanie i rozwijanie DSL bez łamania zgodności użytkowników to bezpłatna lekcja Kotlin Academy na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Kotlin Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Kotlin Academy zawiera 4 lekcji w sumie.

Dlaczego testowanie DSL różni się od innych testów

DSL jest publicznym API. Zmiany w nim mogą zepsuć każde miejsce wywołania w kodzie użytkownika. Testowanie DSL oznacza weryfikację zarówno tworzonego przez niego wyniku, jak i wymuszanej przez niego struktury — w tym sprawdzenie, że nieprawidłowe konstrukcje nadal powodują błędy kompilacji.

Testowanie wyniku DSL

Najprostszy test polega na zbudowaniu obiektu za pomocą DSL i sprawdzeniu renderowanego wyniku lub wewnętrznego stanu buildera.

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

Testowanie stanu buildera

Zamiast testować wyrenderowany ciąg znaków, należy bezpośrednio przetestować graf obiektów buildera. Dzięki temu test jest odporniejszy na zmiany formatowania:

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

Testowanie struktur zagnieżdżonych

Należy przejść po drzewie obiektów, aby zweryfikować relacje zagnieżdżenia:

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

Testowanie błędów kompilacji

Nie można bezpośrednio testować błędów kompilacji za pomocą testów jednostkowych, ale można dodawać komentarze takie jak // This should NOT compile, pozostawiając kod powodujący błąd w komentarzu. Niektóre projekty korzystają z biblioteki Kotlin Compile Testing, aby sprawdzać, że określony kod NIE kompiluje się.

Bezpieczne rozwijanie DSL: zmiany addytywne

Dodawanie nowych opcjonalnych parametrów z wartościami domyślnymi lub nowych funkcji buildera jest zgodne wstecznie. Istniejące miejsca wywołań kompilują się bez zmian.

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

Zmiana powodująca niezgodność: usuwanie lub zmiana nazw

Usunięcie lub zmiana nazwy funkcji DSL powoduje niezgodność w miejscach jej wywołania. Jeśli zmiana nazwy jest konieczna, należy udostępnić przestarzały alias i usunąć go w przyszłej wersji głównej:

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

Wersjonowanie DSL

W przypadku bibliotek DSL należy stosować semantyczne wersjonowanie. Przełomowe zmiany w DSL, takie jak usunięcie funkcji lub zmiana typów odbiorników, uzasadniają zwiększenie numeru wersji głównej. Należy je opisać w dzienniku zmian.

Używanie @RequiresOptIn dla eksperymentalnych funkcji DSL

Niestabilne rozszerzenia DSL należy oznaczać adnotacją @RequiresOptIn. Użytkownicy wyrażają zgodę na ich użycie jawnie, co zapobiega przypadkowemu uzależnieniu kodu od funkcji, które mogą się zmienić:

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

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

Delegowanie właściwości w DSL

DSL może korzystać z delegowania właściwości, aby wymuszać podawanie wymaganych pól i wyświetlać jasne komunikaty o błędach, gdy brakuje wymaganej wartości:

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

Testowanie kontraktowe między wersjami

Należy przechowywać zestaw „wzorcowych” fragmentów użycia DSL w ramach testów. Jeśli refaktoryzacja je zepsuje, zestaw testów wykryje to, zanim zrobią to użytkownicy. Fragmenty te służą również jako żywa dokumentacja.

Szybkie sprawdzenie

Jaki rodzaj zmiany DSL jest najbezpieczniejszy z punktu widzenia zgodności wstecznej?

Podsumowanie: testowanie i rozwijanie DSL

Najważniejsze wnioski:

  • W testach jednostkowych należy testować wynik DSL oraz stan obiektów buildera
  • Zmiany addytywne, takie jak nowe opcjonalne funkcje lub parametry, są bezpieczne
  • Należy używać @Deprecated(ReplaceWith=...), aby zmienić nazwę bez powodowania niezgodności u użytkowników
  • Należy używać @RequiresOptIn dla eksperymentalnych funkcji DSL
  • Należy przechowywać testy wzorcowego użycia, aby wykrywać regresje między wersjami

Często zadawane pytania

Czy lekcja „Testowanie i rozwijanie DSL bez łamania zgodności użytkowników” jest bezpłatna?

Tak — pełny tekst „Testowanie i rozwijanie DSL bez łamania zgodności użytkowników” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Kotlin Academy, przejdź na CoddyKit PRO. Kurs Kotlin Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Testowanie i rozwijanie DSL bez łamania zgodności użytkowników”?

Projektuj stabilne API DSL i testuj je za pomocą czytelnych bloków asercji. Ćwiczysz Kotlin Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Kotlin Academy?

Nie wymagamy żadnego doświadczenia. Kotlin Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.

Ile czasu zajmuje lekcja „Testowanie i rozwijanie DSL bez łamania zgodności użytkowników”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Kotlin Academy?

Tak. Każda lekcja Kotlin Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Lambda z odbiorcą: podstawa DSL
  2. @DslMarker: zapobieganie wyciekaniu odbiorcy
  3. Budowanie bezpiecznego typowo DSL HTML/Config
  4. Testowanie i rozwijanie DSL bez łamania zgodności użytkowników
← Powrót do Kotlin Academy