Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
# SPDX-License-Identifier: MIT
# Copyright contributors to the kepler.gl project
"""Tests for save_to_html and HTML export functionality."""
import json
import os
import pandas as pd
import geopandas as gpd
import pytest
from shapely.geometry import Point
from keplergl import KeplerGl
from keplergl._html_export import (
_dataset_to_csv,
_dataset_to_geojson,
_geojson_dataset_names,
_fixup_geojson_columns,
_serialize_datasets_for_html,
export_map_html,
ES_MODULE_SHIMS_VERSION,
REACT_VERSION,
REDUX_VERSION,
)
class TestDatasetToCsv:
"""Tests for _dataset_to_csv conversion."""
def test_dataframe(self, sample_df):
result = _dataset_to_csv(sample_df)
assert "lat" in result
assert "lng" in result
assert "37.7749" in result
def test_geodataframe_converts_geometry_to_wkt(self, sample_gdf):
result = _dataset_to_csv(sample_gdf)
assert "name" in result
assert "POINT" in result
def test_geodataframe_reprojects_to_4326(self):
gdf = gpd.GeoDataFrame(
{"name": ["A"]},
geometry=[Point(500000, 4649776)],
crs="EPSG:32610",
)
result = _dataset_to_csv(gdf)
assert "POINT" in result
assert "name" in result
def test_geodataframe_already_4326_no_reproject(self, sample_gdf):
"""Ensure CRS EPSG:4326 data is not needlessly reprojected."""
result = _dataset_to_csv(sample_gdf)
assert "POINT" in result
assert "-122.41" in result
assert "37.77" in result
def test_geodataframe_no_crs_skips_reproject(self):
"""GeoDataFrame with no CRS should not trigger reprojection."""
gdf = gpd.GeoDataFrame(
{"name": ["A"]},
geometry=[Point(-122.4, 37.8)],
)
assert gdf.crs is None
result = _dataset_to_csv(gdf)
assert "POINT" in result
def test_csv_string_passthrough(self):
csv = "lat,lng\n37.7749,-122.4194"
assert _dataset_to_csv(csv) == csv
def test_unsupported_type_returns_none(self):
assert _dataset_to_csv(12345) is None
def test_empty_dataframe(self):
df = pd.DataFrame({"a": [], "b": []})
result = _dataset_to_csv(df)
assert "a" in result
assert "b" in result
class TestDatasetToGeojson:
"""Tests for _dataset_to_geojson conversion."""
def test_geodataframe(self, sample_gdf):
result = _dataset_to_geojson(sample_gdf)
assert result is not None
assert result["type"] == "FeatureCollection"
assert len(result["features"]) == 2
def test_geodataframe_reprojects_non_4326(self):
"""GeoDataFrame in non-4326 CRS should be reprojected."""
gdf = gpd.GeoDataFrame(
{"name": ["A"]},
geometry=[Point(500000, 4649776)],
crs="EPSG:32610",
)
result = _dataset_to_geojson(gdf)
assert result is not None
coords = result["features"][0]["geometry"]["coordinates"]
assert -125 < coords[0] < -119
assert 37 < coords[1] < 43
def test_geodataframe_already_4326_no_reproject(self, sample_gdf):
"""Ensure CRS EPSG:4326 data is not needlessly reprojected."""
result = _dataset_to_geojson(sample_gdf)
coords = result["features"][0]["geometry"]["coordinates"]
assert abs(coords[0] - (-122.4194)) < 1e-4
assert abs(coords[1] - 37.7749) < 1e-4
def test_geodataframe_no_crs_skips_reproject(self):
"""GeoDataFrame with no CRS should not trigger reprojection."""
gdf = gpd.GeoDataFrame(
{"name": ["A"]},
geometry=[Point(-122.4, 37.8)],
)
assert gdf.crs is None
result = _dataset_to_geojson(gdf)
assert result is not None
coords = result["features"][0]["geometry"]["coordinates"]
assert abs(coords[0] - (-122.4)) < 1e-4
def test_geojson_dict(self):
geojson = {"type": "FeatureCollection", "features": []}
assert _dataset_to_geojson(geojson) is geojson
def test_geojson_feature_dict(self):
feature = {
"type": "Feature",
"geometry": {"type": "Point", "coordinates": [0, 0]},
"properties": {},
}
assert _dataset_to_geojson(feature) is feature
def test_geojson_string(self):
geojson_str = json.dumps({"type": "FeatureCollection", "features": []})
result = _dataset_to_geojson(geojson_str)
assert result is not None
assert result["type"] == "FeatureCollection"
def test_non_geojson_dict_returns_none(self):
assert _dataset_to_geojson({"key": "value"}) is None
def test_non_geojson_string_returns_none(self):
assert _dataset_to_geojson("just a csv string\n1,2,3") is None
def test_dataframe_returns_none(self):
df = pd.DataFrame({"x": [1]})
assert _dataset_to_geojson(df) is None
def test_int_returns_none(self):
assert _dataset_to_geojson(42) is None
def test_geodataframe_with_datetime(self):
"""GeoDataFrame with datetime column should serialize without error."""
gdf = gpd.GeoDataFrame(
{
"name": ["A", "B"],
"timestamp": pd.to_datetime(["2024-01-01", "2024-06-15"]),
},
geometry=[Point(-122.4, 37.8), Point(-118.2, 34.0)],
crs="EPSG:4326",
)
result = _dataset_to_geojson(gdf)
assert result is not None
assert result["type"] == "FeatureCollection"
assert len(result["features"]) == 2
ts_val = result["features"][0]["properties"]["timestamp"]
assert "2024" in str(ts_val)
def test_geodataframe_with_datetime_custom_encoder(self):
"""json_encoder=None should raise on datetime columns."""
gdf = gpd.GeoDataFrame(
{
"name": ["A"],
"timestamp": pd.to_datetime(["2024-01-01"]),
},
geometry=[Point(-122.4, 37.8)],
crs="EPSG:4326",
)
with pytest.raises(TypeError):
_dataset_to_geojson(gdf, json_encoder=None)
class TestSerializeDatasetsForHtml:
"""Tests for _serialize_datasets_for_html JS snippet generation."""
def test_dataframe_produces_processCsvData_call(self, sample_df):
js = _serialize_datasets_for_html({"cities": sample_df})
assert "processCsvData" in js
assert '"cities"' in js
def test_geojson_dict_produces_processGeojson_call(self):
geojson = {"type": "FeatureCollection", "features": []}
js = _serialize_datasets_for_html({"geo": geojson})
assert "processGeojson" in js
assert '"geo"' in js
def test_geodataframe_produces_processGeojson_call(self, sample_gdf):
js = _serialize_datasets_for_html({"points": sample_gdf})
assert "processGeojson" in js
assert '"points"' in js
def test_csv_string_produces_processCsvData_call(self):
js = _serialize_datasets_for_html({"csv": "a,b\n1,2"})
assert "processCsvData" in js
def test_multiple_datasets(self, sample_df, sample_gdf):
js = _serialize_datasets_for_html({
"tabular": sample_df,
"spatial": sample_gdf,
})
assert "processCsvData" in js
assert "processGeojson" in js
assert '"tabular"' in js
assert '"spatial"' in js
def test_empty_data(self):
js = _serialize_datasets_for_html({})
assert js == ""
def test_geodataframe_with_datetime(self):
"""Datetime columns in GeoDataFrame should not break JS snippet generation."""
gdf = gpd.GeoDataFrame(
{
"name": ["A"],
"ts": pd.to_datetime(["2024-03-01"]),
},
geometry=[Point(-122.4, 37.8)],
crs="EPSG:4326",
)
js = _serialize_datasets_for_html({"events": gdf})
assert "processGeojson" in js
assert "2024" in js
class TestGeojsonDatasetNames:
"""Tests for _geojson_dataset_names."""
def test_identifies_geodataframe(self, sample_gdf):
names = _geojson_dataset_names({"geo": sample_gdf})
assert "geo" in names
def test_identifies_geojson_dict(self):
geojson = {"type": "FeatureCollection", "features": []}
names = _geojson_dataset_names({"fc": geojson})
assert "fc" in names
def test_excludes_dataframe(self, sample_df):
names = _geojson_dataset_names({"df": sample_df})
assert "df" not in names
def test_excludes_csv_string(self):
names = _geojson_dataset_names({"csv": "a,b\n1,2"})
assert "csv" not in names
def test_mixed_datasets(self, sample_df, sample_gdf):
names = _geojson_dataset_names({"tab": sample_df, "geo": sample_gdf})
assert "geo" in names
assert "tab" not in names
def test_empty_dict(self):
assert _geojson_dataset_names({}) == set()
class TestFixupGeojsonColumns:
"""Tests for _fixup_geojson_columns."""
def _layer(self, data_id, geojson_col="geometry"):
return {
"id": "layer1",
"config": {
"dataId": data_id,
"columns": {"geojson": geojson_col},
},
}
def _config(self, layers):
return {"config": {"visState": {"layers": layers}}}
def test_patches_geometry_column(self):
config = self._config([self._layer("geo")])
result = _fixup_geojson_columns(config, {"geo"})
col = result["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"]
assert col == "_geojson"
def test_skips_non_geojson_dataset(self, sample_df):
config = self._config([self._layer("tabular")])
result = _fixup_geojson_columns(config, {"geo"})
col = result["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"]
assert col == "geometry"
def test_skips_already_correct_column(self):
config = self._config([self._layer("geo", "_geojson")])
result = _fixup_geojson_columns(config, {"geo"})
col = result["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"]
assert col == "_geojson"
def test_returns_none_config_unchanged(self):
assert _fixup_geojson_columns(None, {"geo"}) is None
def test_returns_empty_config_unchanged(self):
result = _fixup_geojson_columns({}, {"geo"})
assert result == {}
def test_returns_config_unchanged_for_empty_geojson_names(self):
config = self._config([self._layer("geo")])
result = _fixup_geojson_columns(config, set())
col = result["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"]
assert col == "geometry"
def test_does_not_mutate_original(self):
config = self._config([self._layer("geo")])
original_col = config["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"]
_fixup_geojson_columns(config, {"geo"})
assert config["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"] == original_col
def test_multiple_layers(self):
layers = [self._layer("geo"), self._layer("other", "geometry")]
config = self._config(layers)
result = _fixup_geojson_columns(config, {"geo"})
patched = result["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"]
skipped = result["config"]["visState"]["layers"][1]["config"]["columns"]["geojson"]
assert patched == "_geojson"
assert skipped == "geometry"
class TestExportMapHtml:
"""Tests for the full export_map_html function."""
def test_returns_valid_html(self, sample_df):
html = export_map_html(data={"test": sample_df}, config={})
assert html.startswith("<!DOCTYPE html>")
assert "</html>" in html
def test_contains_kepler_gl_cdn_script(self, sample_df):
html = export_map_html(
data={"test": sample_df},
config={},
kepler_gl_version="3.2.6",
)
assert "unpkg.com/[email protected]/umd/keplergl.min.js" in html
assert "unpkg.com/[email protected]/umd/keplergl.min.css" in html
def test_default_cdn_version(self, sample_df):
html = export_map_html(data={"test": sample_df}, config={})
assert "unpkg.com/[email protected]/umd/keplergl.min.js" in html
assert "unpkg.com/[email protected]/umd/keplergl.min.css" in html
def test_contains_react_redux_deps(self, sample_df):
html = export_map_html(data={"test": sample_df}, config={})
# React 19 dropped UMD builds; dependencies are now loaded via an ESM
# import map (es-module-shims) rather than classic <script> UMD tags.
assert "esm.sh/react@" in html
assert "esm.sh/react-dom@" in html
assert "esm.sh/redux@" in html
assert "esm.sh/react-redux@" in html
assert "esm.sh/styled-components@" in html
assert "importmap-shim" in html
assert "es-module-shims" in html
def test_contains_dataset(self, sample_df):
html = export_map_html(data={"my_data": sample_df}, config={})
assert "my_data" in html
assert "processCsvData" in html
def test_read_only_mode(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={}, read_only=True)
assert "readOnly: true" in html
def test_edit_mode(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={}, read_only=False)
assert "readOnly: false" in html
def test_center_map(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={}, center_map=True)
assert "centerMap: true" in html
def test_mapbox_token_embedded(self, sample_df):
html = export_map_html(
data={"d": sample_df},
config={},
mapbox_token="pk.test_token_123",
)
assert "pk.test_token_123" in html
def test_config_embedded(self, sample_df):
config = {"version": "v1", "config": {"mapState": {"zoom": 12}}}
html = export_map_html(data={"d": sample_df}, config=config)
assert '"zoom": 12' in html
assert '"version": "v1"' in html
def test_empty_config(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={})
assert "var config = {};" in html
def test_none_config(self, sample_df):
html = export_map_html(data={"d": sample_df}, config=None)
assert "var config = {};" in html
def test_addDataToMap_dispatch(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={})
assert "addDataToMap" in html
assert "store.dispatch" in html
def test_geojson_dataset(self):
geojson = {
"type": "FeatureCollection",
"features": [{
"type": "Feature",
"geometry": {"type": "Point", "coordinates": [-122.4, 37.8]},
"properties": {"name": "SF"},
}],
}
html = export_map_html(data={"geo": geojson}, config={})
assert "processGeojson" in html
assert "FeatureCollection" in html
def test_light_theme(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={}, theme="light")
assert '"light"' in html
def test_dark_theme(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={}, theme="dark")
assert '"dark"' in html
def test_no_theme_omits_prop(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={}, theme="")
assert "theme:" not in html or "undefined" in html
def test_custom_app_name_in_title(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={}, app_name="My Dashboard")
assert "<title>My Dashboard embedded map</title>" in html
def test_custom_app_name_in_component(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={}, app_name="My Dashboard")
assert '"My Dashboard"' in html
def test_default_app_name(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={})
assert "<title>kepler.gl embedded map</title>" in html
def test_esm_shims_version_in_html(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={})
assert ES_MODULE_SHIMS_VERSION in html
assert f"es-module-shims@{ES_MODULE_SHIMS_VERSION}" in html
def test_react_version_in_importmap(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={})
assert f"esm.sh/react@{REACT_VERSION}" in html
def test_redux_version_in_importmap(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={})
assert f"esm.sh/redux@{REDUX_VERSION}" in html
def test_module_shim_bootstrap_type(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={})
assert 'type="text/kepler-bootstrap"' in html
assert 'type="module-shim"' in html
def test_app_name_html_escaped_in_title(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={}, app_name="<My & Map>")
assert "<title><My & Map> embedded map</title>" in html
def test_no_datasets(self):
html = export_map_html(data={}, config={})
assert "<!DOCTYPE html>" in html
assert "var datasets = [];" in html
def test_fixup_geojson_columns_applied_in_export(self):
"""GeoDataFrame export should patch geometry column ref to _geojson."""
gdf = gpd.GeoDataFrame(
{"name": ["SF"]},
geometry=[Point(-122.4, 37.8)],
crs="EPSG:4326",
)
config = {
"config": {"visState": {"layers": [{
"id": "l1",
"config": {
"dataId": "places",
"columns": {"geojson": "geometry"},
},
}]}}
}
html = export_map_html(data={"places": gdf}, config=config)
assert '"_geojson"' in html
assert '"geometry"' not in html.split("var config =")[1]
def test_center_map_false_by_default(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={})
assert "centerMap: false" in html
def test_empty_mapbox_token(self, sample_df):
html = export_map_html(data={"d": sample_df}, config={}, mapbox_token="")
assert 'MAPBOX_TOKEN = ""' in html
class TestSaveToHtml:
"""Tests for the KeplerGl.save_to_html widget method."""
def test_saves_file(self, sample_df, tmp_path):
widget = KeplerGl(data={"cities": sample_df})
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out)
assert os.path.exists(out)
with open(out) as f:
content = f.read()
assert "<!DOCTYPE html>" in content
assert "cities" in content
assert "unpkg.com/[email protected]/umd/keplergl.min.js" in content
def test_saves_with_config(self, sample_df, tmp_path):
config = {"version": "v1", "config": {"mapState": {"zoom": 5}}}
widget = KeplerGl(data={"d": sample_df}, config=config)
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out)
with open(out) as f:
content = f.read()
assert '"zoom": 5' in content
def test_saves_with_override_data(self, sample_df, tmp_path):
widget = KeplerGl(data={"original": sample_df})
override = pd.DataFrame({"x": [1, 2], "y": [3, 4]})
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out, data={"override": override})
with open(out) as f:
content = f.read()
assert "override" in content
assert "original" not in content
def test_saves_with_geodataframe(self, sample_gdf, tmp_path):
widget = KeplerGl(data={"geo": sample_gdf})
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out)
with open(out) as f:
content = f.read()
assert "processGeojson" in content
def test_saves_read_only(self, sample_df, tmp_path):
widget = KeplerGl(data={"d": sample_df})
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out, read_only=True)
with open(out) as f:
content = f.read()
assert "readOnly: true" in content
def test_default_filename(self, sample_df, tmp_path):
original_cwd = os.getcwd()
try:
os.chdir(tmp_path)
widget = KeplerGl(data={"d": sample_df})
widget.save_to_html()
assert os.path.exists("keplergl_map.html")
finally:
os.chdir(original_cwd)
def test_print_message(self, sample_df, tmp_path, capsys):
widget = KeplerGl(data={"d": sample_df})
out = str(tmp_path / "test.html")
widget.save_to_html(file_name=out)
captured = capsys.readouterr()
assert "Map saved to" in captured.out
assert out in captured.out
def test_html_is_utf8(self, tmp_path):
df = pd.DataFrame({"city": ["São Paulo", "Zürich"], "lat": [-23.5, 47.4], "lng": [-46.6, 8.5]})
widget = KeplerGl(data={"intl": df})
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out)
with open(out, encoding="utf-8") as f:
content = f.read()
assert "São Paulo" in content
assert "Zürich" in content
def test_saves_geodataframe_with_datetime(self, tmp_path):
"""Regression: GeoDataFrame with datetime column should export to HTML."""
gdf = gpd.GeoDataFrame(
{
"name": ["SF"],
"timestamp": pd.to_datetime(["2024-01-15 10:30:00"]),
},
geometry=[Point(-122.4, 37.8)],
crs="EPSG:4326",
)
widget = KeplerGl(data={"events": gdf})
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out)
with open(out, encoding="utf-8") as f:
content = f.read()
assert "processGeojson" in content
assert "2024" in content
def test_saves_with_custom_json_encoder(self, sample_gdf, tmp_path):
"""json_encoder parameter is forwarded through save_to_html."""
widget = KeplerGl(data={"geo": sample_gdf})
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out, json_encoder=repr)
assert os.path.exists(out)
def test_saves_with_light_theme(self, sample_df, tmp_path):
widget = KeplerGl(data={"d": sample_df}, theme="light")
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out)
with open(out) as f:
content = f.read()
assert '"light"' in content
def test_saves_with_theme_override(self, sample_df, tmp_path):
widget = KeplerGl(data={"d": sample_df}, theme="dark")
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out, theme="light")
with open(out) as f:
content = f.read()
assert '"light"' in content
def test_saves_with_custom_app_name(self, sample_df, tmp_path):
widget = KeplerGl(data={"d": sample_df}, app_name="My Map")
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out)
with open(out) as f:
content = f.read()
assert "<title>My Map embedded map</title>" in content
assert '"My Map"' in content
def test_saves_with_app_name_override(self, sample_df, tmp_path):
widget = KeplerGl(data={"d": sample_df}, app_name="Original")
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out, app_name="Override")
with open(out) as f:
content = f.read()
assert "<title>Override embedded map</title>" in content
assert '"Override"' in content
def test_center_map_default_true_in_save_to_html(self, sample_df, tmp_path):
"""save_to_html defaults center_map=True (unlike export_map_html's False)."""
widget = KeplerGl(data={"d": sample_df})
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out)
with open(out) as f:
content = f.read()
assert "centerMap: true" in content
def test_mapbox_token_inherited_from_widget(self, sample_df, tmp_path):
widget = KeplerGl(data={"d": sample_df}, mapbox_token="pk.widget_token")
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out)
with open(out) as f:
content = f.read()
assert "pk.widget_token" in content
def test_mapbox_token_override_in_save(self, sample_df, tmp_path):
widget = KeplerGl(data={"d": sample_df}, mapbox_token="pk.widget_token")
out = str(tmp_path / "map.html")
widget.save_to_html(file_name=out, mapbox_token="pk.override_token")
with open(out) as f:
content = f.read()
assert "pk.override_token" in content
assert "pk.widget_token" not in content