Security and testing

Learn how to set up CSP directives, referrer policies and how to implement unit tests.

What is a CSP?

Content Security Policies (CSPs) are features that help reduce the risk of security threats like XSS attacks and clickjacking. CSPs assume that an attacker has already accessed your website, and can now execute code on your site. CSPs add rules (known as directives) to restrict what code executed on your site can do, where it can be loaded from and where it can make requests to.

Setting CSPs

CSP's should be delivered to the browser from the server's Content-Security-Policy response header. If you are operating in a serverless environment (like a client-side-rendered single page app), you can use the HTML <meta> element. But, this option does not support all CSP features.

Using CSP directives with Mapbox Search JS

To use a Content Security Policy with Mapbox Search JS the following directives are required:

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

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.

Unit testing

To run unit tests with Mapbox Search JS, you may be able to mock our web components or individual parts based on your needs.

We use Jest internally for unit testing both user applications and Mapbox Search JS itself.

Unit testing with Jest requires JSDOM 16 with HTML Custom Element support. This is shipped by default in Jest v26 and higher. If using below that version, you may need the jest-environment-jsdom-sixteen package to run unit tests.

This is our Jest setup file for Search JS Web. Since we have very high test coverage, you may not need all of these mocks for your own application.

test/jest_framework_setup.js:

import fetch from 'node-fetch';
import { AbortController } from 'abort-controller';

import { polyfillFetch } from '@mapbox/search-js-core';

/**
 * We need to mock the HTMLDocument to return itself in order to use Scoped DOM.
 *
 * Bug: https://github.com/jsdom/jsdom/issues/3179
 * Reference: https://jestjs.io/docs/manual-mocks#mocking-methods-which-are-not-implemented-in-jsdom
 */
export const htmlDocFunc = jest.spyOn(
  document.implementation,
  'createHTMLDocument'
);
htmlDocFunc.mockImplementation(() => {
  return document;
});

// Needed for the 'no-scroll' package.
window.scroll = jest.fn();

// Mock ResizeObserver.
window.ResizeObserver = jest.fn(() => {
    return {
        observe: jest.fn(),
        unobserve: jest.fn(),
        disconnect: jest.fn()
    }
});

polyfillFetch({ fetch, AbortController });

jest.config.js:

{
    "setupFilesAfterEnv": [
      "<rootDir>/test/jest_framework_setup.js"
    ]
}

Was this page helpful?