Запуск тестов в Kotlin/JS

Добавление зависимостей для тестирования

При создании мультиплатформенного проекта можно добавить зависимости для тестирования во все наборы исходного кода, включая целевую платформу JavaScript, указав одну зависимость в commonTest:

// build.gradle.kts
kotlin {
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test")) // Enables test annotations and functionality in JS
        }
    }
}

// build.gradle
kotlin {
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test") // Enables test annotations and functionality in JS
            }
        }
    }
}

Настройка браузеров

В Kotlin/JS можно запускать тесты в определенных браузерах. Для этого измените настройки в блоке конфигурации browser {} файла сборки Gradle.

По умолчанию плагин использует Headless Chrome для запуска тестов в браузере. По умолчанию плагин Kotlin Multiplatform Gradle не включает в себя браузеры. Чтобы подключить дополнительные браузеры, используйте блок testTask {} для Karma и блок test {} для нового DSL тестирования в браузере. Все доступные параметры приведены здесь:

kotlin {
    js {
        browser {
            testTask {
                useKarma {
                    useIe()
                    useSafari()
                    useFirefox()
                    useChrome()
                    useChromeCanary()
                    useChromeHeadless()
                    usePhantomJS()
                    useOpera()
                }
            }
        }
    }
}

import org.jetbrains.kotlin.gradle.ExperimentalJsTestDsl

kotlin {
    js {
        browser {
            @OptIn(ExperimentalJsTestDsl::class)
            test {
                chromium()
                firefox()
                webkit() // Safari browser
            }
        }
    }
}

Добавление теста

Чтобы проверить, что тесты выполняются правильно, создайте файл src/jsTest/kotlin/AppTest.kt со следующим содержимым:

import kotlin.test.Test
import kotlin.test.assertEquals

@Test
fun thingsShouldWork() {
    assertEquals(listOf(3,2,1), listOf(1,2,3).reversed())
}

@Test
fun thingsShouldBreak() {
    assertEquals(listOf(1,2,3), listOf(1,2,3).reversed())
}

Запуск тестов

Чтобы запустить тесты в браузере, выполните задачу jsBrowserTest или используйте значки на полях в IntelliJ IDEA для запуска всех тестов или отдельных тестов:

Кроме того, чтобы запустить тесты в командной строке, используйте оболочку Gradle:

./gradlew jsBrowserTest

После запуска тестов в IntelliJ IDEA в окне инструментов Запуск отображаются результаты. Чтобы просмотреть трассировку стека для неудачных тестов и перейти к соответствующей реализации теста, дважды щелкните такой тест.

После каждого запуска тестов, независимо от способа запуска, в build/reports/tests/jsBrowserTest/index.html можно найти отчет Gradle с форматированием. Откройте этот файл в браузере, чтобы увидеть обзор результатов тестирования:

Если вы используете набор примеров тестов из фрагмента выше, один тест пройдет, а другой завершится с ошибкой, поэтому успешными будут 50% тестов. Чтобы получить больше информации об отдельных тестовых случаях, воспользуйтесь ссылками:

Расширенная конфигурация

Новый DSL для тестирования в браузере разработан как минималистичный и не зависящий от конкретных инструментов. Текущая реализация включает:

• Playwright выступает в роли драйвера браузера и средства управления дистрибутивами, поддерживающего браузерные движки Chromium, Firefox и WebKit (Safari).

• Mocha выступает в роли средства запуска тестов.

• webpack выступает в роли сборщика (в будущих выпусках его заменит Vite).

DSL предоставляет тайм-ауты, безголовый режим и параметры для отдельных средств запуска в виде свойств Gradle. Таким образом, вы можете использовать общие значения по умолчанию для разных средств запуска, переопределять их для конкретного браузера и вычислять значения отложенно с помощью провайдеров:

import org.jetbrains.kotlin.gradle.ExperimentalJsTestDsl
import kotlin.time.Duration.Companion.seconds

kotlin {
    js {
        browser {
            @OptIn(ExperimentalJsTestDsl::class)
            test {
                // Configures the default timeout for all runners with kotlin.Duration
                timeout = 30.seconds

                // Configures headless mode using Gradle providers
                headless = providers
                    .environmentVariable("IS_IN_CI")
                    .map { it.toBoolean() }
                    .orElse(false)

                // Enables and configures the Chromium runner with a custom name
                chromium("chromium-no-webgl2") {
                    // Overrides the default timeout for this runner
                    timeout = 10.seconds

                    // Chromium-specific extra launch argument
                    launchArgs.add("--disable-webgl2")
                }

                // Enables the Firefox runner
                firefox()

                // Enables and configures the WebKit runner
                webkit("safari") {
                    timeout = 35.seconds
                }
            }
        }
    }
}

Параметры для всех средств запуска тестов можно задать непосредственно в блоке test {}. Чтобы переопределить эти общие параметры для определенного средства запуска, укажите для него собственное имя и задайте другие значения в блоке средства запуска. В этом примере браузеры Chromium и WebKit (Safari) используют тайм-ауты 10 и 35 секунд соответственно, а Firefox использует общий тайм-аут в 30 секунд.

Каждое средство запуска регистрируется под собственным именем, поэтому в отчете о тестировании указано, в каком браузере получен тот или иной результат.

Настройка для авторов плагинов

Если вы разрабатываете плагин Gradle на основе плагина Kotlin Multiplatform Gradle, новый DSL для тестирования в браузере также предоставляет доступ к средствам запуска браузеров и расположению созданного пакета тестов.

Kotlin создает пакет тестов для запуска тестов в браузере, используя стандартную страницу запуска тестов. Ее можно заменить, указав другое расположение в свойстве testsLocation:

kotlin {
    js {
        browser {
            @OptIn(ExperimentalJsTestDsl::class)
            test {
                // Implement customJsTestsLocation to modify or replace the default JS test bundle
                @OptIn(DelicateKotlinGradlePluginApi::class)
                testsLocation = customJsTestsLocation(extendFrom = defaultTestsLocationProvider)

                chromium()
            }
        }
    }
}

Ваш собственный сборщик тестов может включать собственный сервер разработки, сборщик или средство запуска тестов. Свойство defaultTestsLocationProvider предоставляет доступ к стандартному расположению, позволяя использовать его как основу вместо реализации всего с нуля.

Для каждого расположения тестов через интерфейс KotlinJsTestsLocation доступны каталог с созданным пакетом тестов (bundleLocation), имя страницы тестов (testHtmlFileName) и URL-адрес, который открывает браузер (url).

С помощью этих API можно:

• Настроить URL-адрес, который открывает браузер. У каждого средства запуска браузера есть собственное расположение тестов, поэтому его можно переопределить для всех средств запуска в блоке test {} или для отдельного средства запуска.

• Переопределить само расположение пакета, например, чтобы добавить в пакет дополнительные файлы.

• Выполнить постобработку созданного пакета тестов. Зарегистрируйте собственную задачу и измените в ней файлы до того, как браузер их откроет, например, чтобы добавить собственную конфигурацию в test.html.

При создании плагинов с помощью этих API учитывайте следующие ограничения:

• Настройка subtarget.test включает новый конвейер тестирования и отключает Karma. В настоящее время нет надежного способа определить, какой конвейер выбрал пользователь.

• Нет надежного способа отложенно настроить конкретное средство запуска браузера, поэтому настройку необходимо выполнять в afterEvaluate. Вместо этого предложите пользователям явно задать расположение тестов или предоставьте декорирующие функции, например myPluginChromium().

Оставить отзыв

Новый DSL для тестирования в браузере активно разрабатывается. В следующих выпусках Kotlin планируется добавить новые функции, например отладку.

Будем признательны за отзывы в YouTrack или в канале Slack #javascript.