Testing and Debugging

This document provides a comprehensive overview of the testing frameworks and debugging tools available in Mapbox GL JS. It covers how to run tests, set up debugging environments, and effectively troubleshoot issues in the library.

Overview of Testing Framework

Mapbox GL JS employs a robust testing infrastructure to ensure reliability across different environments and use cases. The testing framework consists of several test types that run on multiple platforms and browsers.

100%

Unit Tests

Unit tests verify the functionality of individual components in isolation. These tests focus on JavaScript logic and are browser-independent.

Integration Tests

The integration test suite includes several test types:

Render Tests

Render tests compare rendered map outputs against expected images to detect visual regressions. These tests run across different browsers and platforms.

100%

Query Tests

Query tests verify the behavior of map querying functions like queryRenderedFeatures(), ensuring that the correct features are returned when querying the map.

Other Test Types

• Expression Tests: Verify the operation of Mapbox GL JS expressions
• Style Specification Tests: Check compliance with the Mapbox GL style specification
• TypeScript Tests: Verify TypeScript type definitions
• CSP Tests: Ensure Content Security Policy compliance
• uSVG Tests: Test SVG rendering

CI/CD Pipeline

Mapbox GL JS uses CircleCI for continuous integration. The configuration defines jobs for different test types across various platforms and browsers.

100%

Debugging Tools

Mapbox GL JS provides several debugging tools and options to help identify and fix issues.

Map Debugging Options

The devtools option can be enabled when creating a map to provide additional debugging information:

var map = new mapboxgl.Map({
    container: 'map',
    devtools: true,
    // other options...
});

Collision Box Debugging

Collision boxes for text and icons can be visualized by enabling the collisionDebug option. This helps debug symbol placement issues by showing:

• Red boxes for colliding labels (hidden)
• Blue boxes for visible labels

100%

Debug Pages

The repository includes several HTML pages in the debug/ directory for specific debugging scenarios:

Terrain Debug

The terrain debug page allows toggling various terrain-related features:

• Terrain elevation
• Globe projection
• Satellite imagery
• Buildings
• Hillshade
• Custom layers

Other Debug Pages

• Padding Debug: Test map padding functionality
• RTL Debug: Test right-to-left text rendering
• Canvas Size Debug: Test canvas sizing issues

Running Tests Locally

To run tests locally, you can use the following npm scripts:

# Run unit tests
npm run test-unit

# Run render tests with Chrome
npm run test-render

# Run render tests with Firefox
npm run test-render-firefox

# Run query tests
npm run test-query

# Run expression tests
npm run test-expressions

# Run style specification tests
npm run test-style-spec

Test Directory Structure

100%

Advanced Debugging Techniques

WebGL Debugging

Since Mapbox GL JS uses WebGL for rendering, browser WebGL debugging tools are essential:

1. Chrome WebGL Inspector: Enable in Developer Tools > Settings > Experiments > WebGL Developer Tools
2. Firefox WebGL Debugger: Available in Developer Tools > Settings > Available Tools > WebGL Shader Editor

Performance Profiling

Performance issues can be debugged using:

1. Browser Performance Tools: Use the Performance tab in browser developer tools
2. Frame Rate Counter: Enable with map.showTileBoundaries = true;
3. Tile Boundaries: Enable with map.showTileBoundaries = true;

Common Debugging Scenarios

Text Placement and Collision Issues

For debugging symbol placement and collision issues:

1. Enable collision debugging to visualize collision boxes
2. Check text-pitch-alignment and text-rotation-alignment settings
3. Examine symbol-placement and text field configuration

Terrain and 3D Issues

For debugging terrain and 3D rendering:

1. Use the terrain debug page to isolate terrain-related problems
2. Check elevation data sources and terrain configuration
3. Examine fill-extrusion layers for building problems

Contributing New Tests

When adding a new feature or fixing a bug, it's important to add tests:

1. Unit tests for new functions and methods
2. Render tests for visual changes
3. Query tests for changes to querying behavior

A typical render test consists of:

1. A style.json file that defines the map style and test parameters
2. An expected.png file showing the expected rendering output

A query test requires:

1. A style.json file with test configuration
2. An expected.json file with the expected query results

Conclusion

Mapbox GL JS provides comprehensive testing and debugging tools to ensure reliability and help troubleshoot issues. By understanding these tools and techniques, you can effectively identify and fix problems in your Mapbox GL JS applications.