Browsers and testing

Learn how to set up CSP directives and referrer policies and how to write automated tests.

CSP directives

As a mitigation for Cross-Site Scripting and other types of web security vulnerabilities, you may use a Content Security Policy (CSP) to specify security policies for your website. If you do, Mapbox GL JS requires the following CSP directives:

worker-src blob: ;
child-src blob: ;
img-src data: blob: ;
connect-src https://*.tiles.mapbox.com https://api.mapbox.com https://events.mapbox.com ;

Strict CSP environments

In strict CSP environments where worker-src blob: ; child-src blob: ; cannot be used, you can use the mapbox-gl-csp.js file instead of mapbox-gl.js. The strict CSP bundle also requires manually setting the path to the GL JS worker source to use the mapbox-gl-csp-worker.js file. Note that workers must obey the same-origin policy, which means that mapbox-gl-csp-worker.js must be served from the same origin as the page that loads it.

<script src='https://api.mapbox.com/mapbox-gl-js/v3.1.2/mapbox-gl-csp.js'></script>
<script>
mapboxgl.workerUrl = "https://api.mapbox.com/mapbox-gl-js/v3.1.2/mapbox-gl-csp-worker.js";
...
</script>

If you use the sandbox directive, and your access token is restricted to certain URLs, the allow-same-origin value is required. This allows requests to have a Referer header that is not null. See the section on Referrer Policies for further information.

Referrer policies

If you use a URL-restricted access token, you have to make sure that the browser sends the correct referrer header. This is the default setting. But if you use the Referrer-Policy header on your website, pick a value that still sends a Referer header, like no-referrer-when-downgrade, origin, origin-when-cross-origin, or strict-origin. Specifically, same-origin and no-referrer will never send a referrer header, and thus Mapbox API calls won't work.

If you limit the referrer to the origin, make sure that the URL you restrict your access token to doesn't contain path information, because the Origin header doesn't contain a path by definition.

Automated tests

Run automated browser tests without an access token by setting the testMode Map option. The resulting Map instance does not produce visual output, but still loads locally hosted fixtures for styles and tiles and maintains full JavaScript API compatibility. This means that automated tests can exercise and assert state via the public API. This includes but is not limited to:

• Listen for interaction events like click, mouseover etc on Layers.
• Extract feature data with map.queryRenderedFeatures().
• Update view state center, pitch, bearing, map.easeTo(), map.flyTo() etc.
• Interact with Marker and Popup instances.

Example initialization of a Map in testMode:

const map = new mapboxgl.Map({
    container: 'map',
    zoom: 1,
    fadeDuration: 0,
    center: [0, 0],
    testMode: true,
    // Load inline style
    style: {
        version: 8,
        sources: {
            land: {
                type: 'geojson',
                data: `${location.origin}/test/browser/fixtures/land.json` // Load local geojson fixture
            }
        },
        layers: [
            {
                id: 'land',
                type: 'fill',
                source: 'land',
                paint: {
                    'fill-color': '#f0e9e1'
                }
            }
        ]
    }
});

For a more detailed demo of using testMode with Selenium, explore our sample browser tests.