После миграции на MapLibre GL JS критически важным этапом становится проверка корректности работы всех слоёв карты, источников данных и пользовательских взаимодействий. Даже при формальной совместимости API с Mapbox GL JS различия в рендерере, обработке стилей и шрифтовых ресурсах могут приводить к визуальным и функциональным расхождениям, которые невозможно обнаружить без системного тестирования.
Первым уровнем тестирования выступает проверка создания экземпляра карты и корректной загрузки базового стиля. Важно убедиться, что карта не только инициализируется без ошибок, но и полностью завершает загрузку всех ресурсов.
Типовой сценарий проверки:
import maplibregl from "maplibre-gl";
const map = new maplibregl.Map({
container: "map",
style: "https://demotiles.maplibre.org/style.json",
center: [37.6173, 55.7558],
zoom: 10
});
map.on("load", () => {
console.assert(map.isStyleLoaded(), "Стиль должен быть полностью загружен");
});Ключевым индикатором корректной работы выступает событие
load и метод isStyleLoaded(). В тестовой среде
важно учитывать асинхронность загрузки тайлов и ресурсов шрифтов.
После миграции часто возникают расхождения в обработке источников
GeoJSON, Vector Tiles и Raster Tiles. Особое внимание уделяется
структуре sources, так как MapLibre GL JS более строго
обрабатывает некоторые поля спецификации стиля.
Проверка добавления источника:
map.on("load", () => {
map.addSource("cities", {
type: "geojson",
data: {
type: "FeatureCollection",
features: []
}
});
const source = map.getSource("cities");
console.assert(source, "Источник cities должен существовать");
});Тестирование должно включать:
setDataОсобое внимание уделяется setData, так как при миграции
могут проявляться различия в обновлении кэша рендера.
Слои являются центральным элементом визуального тестирования. После
миграции возможны изменения в порядке отрисовки, особенно при
использовании fill, line, symbol
и custom layers.
map.addLayer({
id: "cities-layer",
type: "circle",
source: "cities",
paint: {
"circle-radius": 6,
"circle-color": "#ff0000"
}
});Проверка должна включать:
map.getLayerbeforeIdlayout.visibility)Отдельное внимание требуется символическим слоям
(symbol), так как различия в шрифтах (glyphs) после
миграции могут приводить к пустым подписям.
MapLibre GL JS строго следует спецификации Mapbox Style Spec, однако некоторые edge-case поведения отличаются. Проверка стиля включает:
Пример валидации загрузки стиля:
map.on("styledata", () => {
const style = map.getStyle();
console.assert(style.sources, "sources должны быть определены");
console.assert(style.layers.length > 0, "layers должны присутствовать");
});Важно тестировать динамическую смену стилей:
map.setStyle("https://example.com/new-style.json");
map.once("style.load", () => {
console.assert(map.isStyleLoaded(), "Новый стиль должен загрузиться полностью");
});После миграции необходимо убедиться, что все пользовательские события продолжают работать корректно. MapLibre GL JS сохраняет API событий Mapbox GL JS, но порядок их срабатывания может отличаться в зависимости от версии WebGL контекста.
Основные события для тестирования:
loadidlerendermovezoomclick, mouseenter,
mouseleaveПример проверки клика по слою:
map.on("click", "cities-layer", (e) => {
console.assert(e.features.length > 0, "Должен быть хотя бы один feature");
});Особое внимание уделяется событию idle, так как оно
используется в тестах визуальной стабилизации карты.
После миграции наиболее критическим этапом становится визуальная проверка. Небольшие различия в антиалиасинге, отрисовке линий и текстов могут накапливаться и приводить к значительным расхождениям.
Типовой подход включает:
idle перед снимкомawait map.once("idle");
const canvas = map.getCanvas();В CI обычно применяется сравнение скриншотов с эталонными изображениями. Важно учитывать:
После миграции возможно изменение производительности из-за различий в оптимизациях WebGL слоя. Основные метрики:
Пример измерения времени загрузки:
const start = performance.now();
map.on("idle", () => {
const duration = performance.now() - start;
console.log("Время до idle:", duration);
});Также проверяется поведение при большом количестве слоёв и источников:
setDataMapLibre GL JS опирается на WebGL, поэтому различия между браузерами напрямую влияют на результат. Тестирование должно охватывать:
Проверяются:
preserveDrawingBufferif (!maplibregl.supported()) {
throw new Error("WebGL не поддерживается");
}На мобильных устройствах ключевыми становятся ограничения памяти и GPU. После миграции часто проявляются:
Проверяется:
touchstart,
touchmove)После миграции важно протестировать взаимодействие карты с backend-данными:
Пример динамического обновления:
setInterval(() => {
fetch("/api/geojson")
.then(res => res.json())
.then(data => {
const source = map.getSource("cities");
source.setData(data);
});
}, 5000);Проверка должна учитывать:
После миграции важно убедиться, что библиотека корректно обрабатывает ошибки:
Проверка поведения:
map.on("error", (e) => {
console.error("Map error:", e.error);
});Цель тестирования — отсутствие полного падения рендера при частичных ошибках источников.
Если в старой версии использовались кастомные слои или расширения WebGL, после миграции требуется проверка:
render(gl, matrix)Особенно критично при использовании анимаций и shader-based визуализаций.
После миграции тестирование должно выполняться автоматически. Типовой pipeline включает:
Пример структуры:
/tests
/unit
/integration
/visual
/performanceВ headless-режиме важно фиксировать окружение:
Тестирование после миграции на MapLibre GL JS становится многоуровневым процессом, охватывающим рендеринг, данные, взаимодействия и производительность, где каждый слой системы требует отдельной валидации и повторяемости результатов в разных средах исполнения.