Debug Pages Review

[austyle]

Summary

I would like to present my notes taken after reviewing the 57 debug pages in the maplibre-gl-js repository: https://github.com/maplibre/maplibre-gl-js/tree/main/test/debug-pages. The purpose of this review was to figure out which debug pages are working and which ones are not as well as what do the debug pages test, accomplish and/or prove. Below I have identified some overall themes and problematic patterns as well as some suggestions for us to consider to revamp the current state of the debug pages. I am posting this in the community github as a discussion to solicit feedback and contributions from other developers. If you have contributed to the debug pages it would be very helpful if you could add a description of what a debug pages does to include: purpose, what is being tested, and what assertions and assumptions are being made.

Overall Themes and Problematic Patterns

• Debug pages do not have any comments that describe what is being tested or debugged. This makes it difficult to understand what is being accomplished by the code and what are the expected effects.
• Mapbox styles were replaced with demotiles in this PR: Remove mapbox access-token from debug pages and use custom style environment #88
  • when merged it broke a lot of the debug pages which were never repaired to execute their intent due to the demotiles not being a 1 for 1 replacement for mapbox
• Many of the debug pages request the fonts: Open Sans Semibold and Arial Unicode MS Bold. This returns a 404 Not Found Error and causes issues in rendering.
• There are still a lot of debug pages that us the mapbox url as a source
• A number of debug pages have a dependency on a layer called "country-label-lg" which I believe comes from the removed mapbox styles. The common error is:
  • Error: Cannot add layer "countries" before non-existing layer "country-label-lg".
• Multiple debug pages have broken references to other files in the repository due to the change in placement in the repo. I think a lot of these can easily be fixed by repairing the relative path to the referenced assets.

Suggestions to Revamp

• Separate script logic from HTML templates and add TypeScript that compiles to JavaScript
  • Each debug pages should have its own directory
  • The directory would include: HTML, TypeScript and a README
  • By adding stronger Typing to the debug pages we can lint them on build and discover errors and regressions faster
  • A README file would help future developers better understand what the purpose of the debug page is, what assertions and assumptions are being made, and what is being tested.
• E2E integrations tests on debug pages using either Cypress or Playwright
  • CI/CD Pipeline using GitHub actions to run the test
  • I am not sure if the juice is worth the squeeze here we would need to:
    • Setup a test repository
    • Setup infrastructure and GitHub actions to run the tests
    • Write tests that cover each of the 57 debug pages (some pages maybe not be testable)

2762

Github: https://github.com/maplibre/maplibre-gl-js/blob/95b0ca42bf8376561db7e96c616d76696d8f65f7/debug/2762.html

It is not clear what this debug page is testing or trying to accomplish. From reading the code there is a point in an empty map and on map click it calls setPaintProperty on the map object to color the point and translate its position.

3895

Github: https://github.com/maplibre/maplibre-gl-js/blob/bf9896c4f0cd22cab613a5f28a52335ccf4a4e1f/debug/3895.html

This page is a victim of the merge where mapbox styles were replaced with demotiles. From the looks of it it is supposed to get the water layer from the map and flicker it by removing it from the map and adding it back on the map on a set interval.

We would need to recover the geometry from the mapbox style for this to work again.

7438

Github: https://github.com/maplibre/maplibre-gl-js/blob/e60fb1581b3192583c8f042ec64593e9626bd54c/debug/7438.html

Debug page for ScaleControl component. Currently is working from what I can tell.

7517

Github: https://github.com/maplibre/maplibre-gl-js/blob/ea9fbeee5725ffbb9aafd52ebfa81c10dc5ac205/debug/7517.html

Map gets camera based on bounding box with padding and offset. Map then eases from initial coordinates and zoom to camera center, zoom and bearing. Looks like it is working.

animate

Github: https://github.com/maplibre/maplibre-gl-js/blob/c4e323ba2d5c4079b9c7f5688ecdcb43fce1d2be/debug/animate.html

Creates an animate on top of the map. Two lines that cross each other are rotated counter clockwise. Animation updates seem to occur 60 fps. No clue as to where the function requestAnimationFrame comes from. Seems to be working.

bounds

Github: https://github.com/maplibre/maplibre-gl-js/blob/a00bf99458b1422e1eab0453f47e09546abfb249/debug/bounds.html

On map load gets the bounds of the the map extent then creates a polygon which is added to the map. The page listens to the map object for a rotateend event in which the callback gets the bounds of the map and updates the geometry of the bounds polygon. I think this is done incorrectly because when zooming out after rotating the map the bounds exceeds the previous zoom levels map extent and the orientation of the bounds is rotated by 46 degrees.

cache_api

Github: https://github.com/maplibre/maplibre-gl-js/blob/500320f891bfbd3f2c81cec772e4517ed625daa6/debug/cache_api.html

This page still has a dependency on mapbox and is broken. Lots of error messages in the console.

Notably:

Fetch API cannot load mapbox://mapbox.mapbox-traffic-v1. 
URL scheme "mapbox" is not supported.

canvas

Github: https://github.com/maplibre/maplibre-gl-js/blob/10eb02b04a781691c68df449d82171c8cb9ef963/debug/canvas.html

Not sure what the purpose of this page is. But it looks to be executing everything it is programmed to do properly. It draws 2 rectangles to a canvas element and two rectangles to and empty map object using canvas as a source.

chinese

Github: https://github.com/maplibre/maplibre-gl-js/blob/e60fb1581b3192583c8f042ec64593e9626bd54c/debug/chinese.html

Seems to be working properly. Not sure what this test is proving. Looks like data is loaded from a file containing points and then there is a “layout” configuration defined for the points added to the map. It looks like one of the images cannot be loaded successfully. Getting a warning in the console. Something like an image “icon” property might be undefined in the data.

circles

Github: https://github.com/maplibre/maplibre-gl-js/blob/72c136477c98cf6896da6227fb92de98bc6e51c4/debug/circles.html

Loads circle data from integration directory, then plots circles on map. Defines properties for custom circle radius and color. Defines layout of text annotation. Appears to be working properly. No errors in the console.

cluster

Github: https://github.com/maplibre/maplibre-gl-js/blob/bf88cd735b06eacc607c188a2508c9912140768d/debug/cluster.html

Issues: data don’t appear on initial load, you must zoom in on the map for data to appear. There is an 404 error in the console:

maplibre-gl-dev.js:1256          
GET 
https://demotiles.maplibre.org/font/Open%20Sans%20Semibold,Arial%20Unicode%20MS%20Bold/0-255.pbf 
404

I think this has to do with the “cluster_label” since it references both of these fonts.

I don’t believe, I can see any clusters in the map. Only “unclustered_point” circles. So none of the custom cluster business logic can be evaluated.

color_spaces

Github: https://github.com/maplibre/maplibre-gl-js/blob/b0eaa56b2be98e1c05e960f0d805409b76bdc3b3/test/debug-pages/color_spaces.html

Issues: The data coming from the cloudfront domain might have changed because we are now getting the following console error:

Error: Cannot add layer "countries" before non-existing 
layer "country-label-lg".

Leads me to believe that there used to be a layer called “country-label-lg” that was added to the map from the cloudfront data.

I believe the purpose of this debug page is to test “rgb”, “hcl” and “lab” colorSpaces.

csp-static

Github: https://github.com/maplibre/maplibre-gl-js/blob/e60fb1581b3192583c8f042ec64593e9626bd54c/debug/csp-static.html

Issues:

• Page does not load
• CSP still depends on a mapbox domain
• source path to “maplibre-gl-csp.js” and “maplibre-gl-csp-worker.js” are broken

GET 
http://localhost:9966/dist/maplibre-gl-csp.js 
net::ERR_ABORTED 404 (Not Found)

csp

Github: https://github.com/maplibre/maplibre-gl-js/blob/b0eaa56b2be98e1c05e960f0d805409b76bdc3b3/test/debug-pages/csp.html

Isssues:

• page does not load
• CSP still depends on a mapbox domain
• demotiles.maplibre.org (http://demotiles.maplibre.org/) url violates the CSP directive so cannot fetch
• unpkg.com (http://unpkg.com/) url violates the CSP directive so cannot fetch

custom3d

Github: https://github.com/maplibre/maplibre-gl-js/blob/f556bee30d36d1001825f18734eda723b1174209/debug/custom3d.html

Seems to be working properly. Creates a custom 3D layer using the “gl” library in scope and adds it to the map.

debug

Github: https://github.com/maplibre/maplibre-gl-js/blob/725697ab4bf3bff35d75638a73d2ef673301fb2a/debug/debug.html

Not sure what the purpose of this page is. It seems that some items are working and others are not.

Issues:

• there used to be a layer called “country-label-lg” that was added to the map but is no longer present
• Issues loading fonts from demotiles.maplibre.org (http://demotiles.maplibre.org/)

Features:

• show tiles boundaries is working
• show collision boxes is working
• show overdraw inspector is working
• drag rotate’s pitch with rotate is NOT working
• Map HTML Popup is working

default-image

Github: https://github.com/maplibre/maplibre-gl-js/blob/68cfea9935853d47649e077b6c9bc24c6ec9dbd4/debug/default-image.html

Issues:

• Issues loading fonts from demotiles.maplibre.org (http://demotiles.maplibre.org/)

maplibre-gl-dev.js:452 Image "foo" could not be loaded. 
Please make sure you have added the image with map.addImage() 
or a "sprite" property in your style. You can provide missing 
images by listening for the "styleimagemissing" map event.

Features:

• supposedly adds points to the map with icon images but images are not found

events

Github: https://github.com/maplibre/maplibre-gl-js/blob/c496a32f15b1d721ec65ca77afeea8fa3ddaeb97/debug/events.html

Tests for the following map events: [
'touchstart', 'touchend', 'touchmove', 'touchcancel',
'mouseout', 'mousedown', 'mouseup', 'mousemove',
'click', 'dblclick', 'contextmenu',
'dragstart', 'drag', 'dragend',
'movestart', 'move', 'moveend',
'zoomstart', 'zoom', 'zoomend',
'rotatestart', 'rotate', 'rotateend',
'pitchstart', 'pitch', 'pitchend',
'boxzoomstart', 'boxzoomend', 'boxzoomcancel'
]

All seem to be working. But I don’t know how to test the events: 'touchstart', 'touchend', 'touchmove', 'touchcancel'

extrusion-query

Github: https://github.com/maplibre/maplibre-gl-js/blob/2119eaa3ea6d85fd8157defb6353d21fadd01b31/debug/extrusion-query.html

Not working properly. The purpose of this debug page is to extrude buildings into 3D; however, the building features are not found. This might be due to the demotiles migration.

featurestate

Github: https://github.com/maplibre/maplibre-gl-js/blob/b3046ea99a73cc027aa5d45ddba5285670097af8/debug/featurestate.html

Issues:

• Still configured to use mapbox url for source

Fetch API cannot load mapbox://mapbox.82pkq93d. 
URL scheme "mapbox" is not supported.

geojson-updates

Github: https://github.com/maplibre/maplibre-gl-js/blob/9e2bed3bb4f2fe4f04b11d2e6b4f364507e95ae2/test/debug-pages/geojson-updates.html

Appears to be working properly. Plots points from geojson then calculates animation of points moving and shows a linestring of the trail of the points path history. No errors in console.

heatmap

Github: https://github.com/maplibre/maplibre-gl-js/blob/15a0db742d21ace602f7eedfddeb1ae888f8bd6c/debug/heatmap.html

Broken but easily fixable.

Error: Cannot add layer "heatmap" before non-existing layer "waterway-label".

Issues:

• “waterway-label” is undefined probably due to demotile migration. If removed from logic the heatmap will render.

highlightpoints

Github: https://github.com/maplibre/maplibre-gl-js/blob/b01a5d3bc78662de493f800ec9430cb7ea42555f/debug/highlightpoints.html

Appears to be working correctly. Points are plotted on map. When user’s mouse hovers over point the style of the point changes.

hillshade

Github: https://github.com/maplibre/maplibre-gl-js/blob/f13c86ea356c384fdab31855b9152f5bf5ef97b8/debug/hillshade.html

NOT working.

Issues:

• still using mapbox url for sources
• layer “waterway-river-canal-shadow” is not found probably due to demotiles migration

iframe-blob

Github: https://github.com/maplibre/maplibre-gl-js/blob/e78ad7944ef768e67416daa4af86b0464bd0f617/debug/iframe-blob.html

Broken, NOT working.

Issues:

• the relative path to the maplibre javascript and css files are broken

iframe

Github: https://github.com/maplibre/maplibre-gl-js/blob/16f9f076a68a1838d734be65116781723bcf8025/debug/iframe.html

Works. This test doesn’t test any of our logic, not sure if it is necessary.

image

Github: https://github.com/maplibre/maplibre-gl-js/blob/e78ad7944ef768e67416daa4af86b0464bd0f617/debug/image.html

Appears to work.

Features:

• Adds a raster image to the empty map

is-safari

Github: https://github.com/maplibre/maplibre-gl-js/blob/e60fb1581b3192583c8f042ec64593e9626bd54c/debug/is-safari.html

Appears to be working.

Features:

• Tests the isSafari method on maplibregl

line-gradient

Github: https://github.com/maplibre/maplibre-gl-js/blob/8fa3d4d7211810beb7b8712c9e0147d0ef62e06f/debug/line-gradient.html

Appears to be working.

Features:

• Creates a gradient of colors along a a line

markers

Github: https://github.com/maplibre/maplibre-gl-js/blob/f92048996f6240007e77f65596b2184dd0f72195/debug/markers.html

Appears to be working.

Features:

• Showcases the different various of rotation and pitch alignments of markers on a map
• Animates the markers by spinning them in a 360 degree animation

mobile_scroll

Github: https://github.com/maplibre/maplibre-gl-js/blob/e78ad7944ef768e67416daa4af86b0464bd0f617/debug/mobile_scroll.html

Appears to be working.

Features:

• Sets height of map to 50 percent of view height and the body to 200 percent of view height to allow for scrolling

multiple

Github: https://github.com/maplibre/maplibre-gl-js/blob/7edb25676fd6df9445f1c4973582356961ecacf5/debug/multiple.html

Broken: is NOT working.

Issues:

• Still uses mapbox url for sources

Features:

• creates multiple instances of of map objects and adds them to their respective container elements

no_wrap

Github: https://github.com/maplibre/maplibre-gl-js/blob/f7da63452bc88feffd963780ec375cc8ae765d07/debug/no_wrap.html

Appears to be working.

Features:

• “renderWorldCopies” on the map object is set to false; this prevents the continuous wrap of the map

popup

Github: https://github.com/maplibre/maplibre-gl-js/blob/e78ad7944ef768e67416daa4af86b0464bd0f617/debug/popup.html

Appears to be working

Features:

• creates a popup on the map object that tracks the cursor pointer

query_features

Github: https://github.com/maplibre/maplibre-gl-js/blob/e60fb1581b3192583c8f042ec64593e9626bd54c/debug/query_features.html

Broken: is NOT working. Could be an easy fix.

Issues:

• Cannot find layer probably due to demotiles migration

maplibre-gl-dev.js:1606 
Error: Cannot add layer "query" before non-existing layer "country-label-sm".

raster-streets

Github: https://github.com/maplibre/maplibre-gl-js/blob/e78ad7944ef768e67416daa4af86b0464bd0f617/debug/raster-streets.html

Broken: is NOT working.

Issues:

• still using mapbox url for source url

route

Github: https://github.com/maplibre/maplibre-gl-js/blob/6b80a8174cb89d484dd0900a617261eee73758f0/test/debug-pages/route.html

Appears to be MOSTLY working.

Issues:

• Lots of 404s from demotiles terrain-tiles

Features:

• plays a animated “flight route” of a linestring through 3D terrain

rtl

Github: https://github.com/maplibre/maplibre-gl-js/blob/e60fb1581b3192583c8f042ec64593e9626bd54c/debug/rtl.html

I do not know enough about RTL to know if this is working correctly or not. When I click to load the rtlTextPlugin Async it just gives me the status of deferred and does not change. No console errors, maybe we need better edge case handling?

satellite

Github: https://github.com/maplibre/maplibre-gl-js/blob/8a49205cf09a479579142a4d745c932eef49c2b1/debug/satellite.html

I do not think this is working because I don’t see anything in the map that would give context to the file name “satellite”. I don’t see anything in the code that references satellite either, maybe there are stale defaults and a lack of assertions?

setstyle

Github: https://github.com/maplibre/maplibre-gl-js/blob/b0eaa56b2be98e1c05e960f0d805409b76bdc3b3/test/debug-pages/setstyle.html

Appears to be working.

Features:

• on an interval switches map style from light to dark mode

shield-rotation

Github: https://github.com/maplibre/maplibre-gl-js/blob/a763e8c3ea62fc4418f5b22014d78d5631273220/debug/shield-rotation.html

Appears to be working.

Features:

• on rotation and pitch events the test changes the layout of the annotation text

stretchable

Github: https://github.com/maplibre/maplibre-gl-js/blob/e78ad7944ef768e67416daa4af86b0464bd0f617/debug/stretchable.html

I don’t know enough about this page to determine if it is working properly without more context. There are no errors in the console.

switch-pattern

Github: https://github.com/maplibre/maplibre-gl-js/blob/8b7ad981bf78d2853c75213ff555a104f7c8164b/test/debug-pages/switch-pattern.html

This COULD be working. I am suspicious that it isn’t working because I cannot find a view that shows an extruded height of a polygon. But I was able to get the polygon to be placed a certain height above the ground. I was under the impression that extruded meant creating a 3D object.

symbols

Github: https://github.com/maplibre/maplibre-gl-js/blob/fe18f985d6126f0849d5d3de22f2a0dd9f66f6e9/debug/symbols.html

Appears to be working.

Features:

• Adds various symbols to points on the map.

terrain-hillshade

Github: https://github.com/maplibre/maplibre-gl-js/blob/6b07410279b800fa3223dfae1f3eb1673679ceb4/test/debug-pages/terrain-hillshade.html

Appears to be working properly.

Features:

• From what I can tell, test adds the TerrainControl plugin to the map which will change the exaggeration of the hillshade in the map.

terrain-osm

Github: https://github.com/maplibre/maplibre-gl-js/blob/5afb59206874205180b4c277c21d930c37b4a21e/debug/terrain.html

Appears to be working properly.

Features:

• Draps OSM tiles over terrain and hillshade

terrain-satellite

Github: https://github.com/maplibre/maplibre-gl-js/blob/981c0d3506cafc5fe474313f8ba953d251f4a314/test/debug-pages/terrain-satellite.html

Appears to be working properly.

Features:

• Draps satellite imagery over the terrain

textsize

Github: https://github.com/maplibre/maplibre-gl-js/blob/b0eaa56b2be98e1c05e960f0d805409b76bdc3b3/test/debug-pages/textsize.html

Broken: is NOT working.

Issues:

• Depends on mapbox url as a source for sprites and glyphs

threejs

Github: https://github.com/maplibre/maplibre-gl-js/blob/f556bee30d36d1001825f18734eda723b1174209/debug/threejs.html

Broken: is NOT working. Could be an easy fix.

Issues:

• layer “3d-buildings” not found probably due to demotiles migration

Error: layers.3d-buildings: source "composite" not found

Features:

• custom layer made with ThreeJS. creates a 3D cube that is rotated on the map

tinysdf

Github: https://github.com/maplibre/maplibre-gl-js/blob/f5886802d8208008dd786f9b85edb0815addcdfb/debug/tinysdf.html

I don’t have enough context to tell if this page is working properly. After examining the code I still have no context as to what “tiny” or “sdf” references. No errors in the console.

Features:

• two maps in the viewport
• after the map’s load event is fired the map styles are “localized”

transform-style

Github: https://github.com/maplibre/maplibre-gl-js/blob/dfbad266cb4f3da6acb1cefc50d8cd28dabb7019/test/debug-pages/transform-style.html

Appears to be working correctly.

Features:

• transformStyle can be used to compose a desired style representation on runtime before the style gets applied to map

update_image

Github: https://github.com/maplibre/maplibre-gl-js/blob/e78ad7944ef768e67416daa4af86b0464bd0f617/debug/update_image.html

Broken: is NOT working. Could be an easy fix.

Issues:

• Looks like the relative path to the images might be broken

Features:

• Toggles image path urls on an interval

variable-anchor-with-icon-text-fit

Github: https://github.com/maplibre/maplibre-gl-js/blob/e78ad7944ef768e67416daa4af86b0464bd0f617/debug/variable-anchor-with-icon-text-fit.html

Broken: is NOT working.

Issues:

• Still has a dependency on mapbox url for sprite and glyphs url sources

video

Github: https://github.com/maplibre/maplibre-gl-js/blob/fc37056bd4436199f36e8cb85e724ec18780c37f/test/debug-pages/video.html

Appears to be working properly. Still has a dependency on mapbox video assets

Features:

• plays a video as a type of raster

wms

Github: https://github.com/maplibre/maplibre-gl-js/blob/2ebe717f7e8817f545fbe52b6ba4855909df41ae/debug/wms.html

Appears to be working properly.

Features:

• adds wms tiles as a layer of type raster

[HarelM]

Thanks for looking into this!!
Pages that have numbers are probably related to mspbox-gl issues, so I would consider looking in that repo if you want to understand the history, also you can use blame and see when was the file created and for what PR.
I generally don't see a lot of value in adding e2e tests to these pages, I would consider adding more tests you our existing e2e browser tests which use playwright in our CI pipeline, I think it's a far better use of resources.
Keeping the debug code in the debug page is very convenient, so I wouldn't rush into moving it to a different file, typescript, transpile etc, seems like an overkill although it might keep the pages more stable.
In most cases, people are adding their debug pages and those are rarely used afterward, I believe, so I would consider adding some basic debug pages which cover the most common use cases and remove all the rest.
This is of course my personal opinion only.

[louwers]

Nice work! I am really new to MapLibre, that said:

• Fixing / removing broken debug pages sounds great.
• Adding a short description to each sounds good as well, although I think they are not meant to be polished user-facing documentation or examples.
• Transpiling / type checking TypeScript... It may be helpful to avoid having to debug the debug pages and thus keeping them as simple as possible, if you know what I mean. 😄

But I don’t know how to test the events: 'touchstart', 'touchend', 'touchmove', 'touchcancel'

I set up a file server and opened events.html with remote debugging with my phone. They seem to work as well, although I couldn't get a touchcancel to fire.

[bdon]

Awesome work!

chinese

Github: https://github.com/maplibre/maplibre-gl-js/blob/e60fb1581b3192583c8f042ec64593e9626bd54c/debug/chinese.html

Seems to be working properly. Not sure what this test is proving. Looks like data is loaded from a file containing points and then there is a “layout” configuration defined for the points added to the map. It looks like one of the images cannot be loaded successfully. Getting a warning in the console. Something like an image “icon” property might be undefined in the data.

I believe this is just the 2,500 most common Simplified Chinese characters arranged randomly in 5-character-long labels. The console failure should be irrelevant as it was specific to the map style that was loaded before. I'm guessing this was designed to test performance of different SDF glyph range designs before the Local Ideographs code path was introduced, which means the debug page does not have to make any font requests.

tinysdf

Github: https://github.com/maplibre/maplibre-gl-js/blob/f5886802d8208008dd786f9b85edb0815addcdfb/debug/tinysdf.html

I don’t have enough context to tell if this page is working properly. After examining the code I still have no context as to what “tiny” or “sdf” references. No errors in the console.

Features:

two maps in the viewport
after the map’s load event is fired the map styles are “localized”

It looks like this is related to the above and loads a basemap view of Shanghai with default labels in English name_en, and then load a second view with default labels name which will be in Simplified Chinese. I'm guessing this is a more integration-y version of the above test on real data, it refers to the tiny-sdf library which is used by the local ideographs code path by default for Han script (Chinese + Japanese Kanji) text display.

[HarelM]

TSC discussion summary: "Interesting" debug pages that can be added to the examples pages should go there, other that are interested for testing (if any) should move there, or adopted to be using rendering test or browser test, the rest should be deleted and we should keep an eye for PRs that add a debug page (or delete the library and index creation code to avoid this in the future).
Thanks again @austyle for the great work you did here!!