Test esm loading to ensure modules load as expected

dcoj · github-actions[bot] · commit 602ff0238b1e · 2026-06-24T13:17:02.000Z
GitOrigin-RevId: ab8d2ea08e9ceab8af72cd51bec1f735a5fcbdb3
diff --git a/build/generate-access-token-script.js b/build/generate-access-token-script.js
@@ -1,6 +1,6 @@
 import fs from 'fs';
 
-const script = fs.readFileSync(new URL('../debug/access_token.js', import.meta.url), 'utf-8')
+const script = fs.readFileSync(new URL('../test/util/access_token.js', import.meta.url), 'utf-8')
     .replace('process.env.MapboxAccessToken',
         JSON.stringify(process.env.MapboxAccessToken))
     .replace('process.env.MAPBOX_ACCESS_TOKEN',
diff --git a/test/unit/esm_loading/building.test.ts b/test/unit/esm_loading/building.test.ts
@@ -0,0 +1,21 @@
+import {test, expect, waitFor} from '../../util/vitest';
+import {HD} from '../../../modules/hd_main_esm';
+import {makeMap, waitForLoaded} from './helpers';
+
+test('building layer triggers HD loading', async () => {
+    const geojson = {type: 'FeatureCollection', features: [{
+        type: 'Feature', properties: {},
+        geometry: {type: 'Polygon', coordinates: [[[0, 0], [0, 0.01], [0.01, 0.01], [0.01, 0], [0, 0]]]},
+    }]};
+    const map = makeMap(
+        [{id: 'bldg', type: 'building', source: 'geo', layout: {'building-base': 0, 'building-height': 10}, paint: {}}],
+        {geo: {type: 'geojson', data: geojson}},
+    );
+    try {
+        await waitFor(map, 'idle');
+        await waitForLoaded(HD);
+        expect(HD.loaded).toBe(true);
+    } finally {
+        map.remove();
+    }
+});
diff --git a/test/unit/esm_loading/helpers.ts b/test/unit/esm_loading/helpers.ts
@@ -0,0 +1,36 @@
+import {vi} from '../../util/vitest';
+import {Map} from '../../../src/index.esm';
+
+import type {LayerSpecification} from '../../../src/style-spec/types';
+
+export function makeContainer() {
+    const container = document.createElement('div');
+    Object.defineProperty(container, 'getBoundingClientRect',
+        {value: () => ({height: 200, width: 200}), configurable: true});
+    return container;
+}
+
+export function makeMap(layers: LayerSpecification[] = [], sources = {}) {
+    vi.spyOn(Map.prototype, '_detectMissingCSS').mockImplementation(() => {});
+    const map = new Map({
+        testMode: true,
+        container: makeContainer(),
+        zoom: 1,
+        center: [0, 0],
+        interactive: false,
+        attributionControl: false,
+        performanceMetricsCollection: false,
+        precompilePrograms: false,
+        style: {version: 8, sources, layers},
+    });
+    map._authenticate = () => {};
+    return map;
+}
+
+export async function waitForLoaded(mod: {loaded?: boolean}) {
+    await vi.waitUntil(() => mod.loaded === true, {timeout: 3000, interval: 20});
+}
+
+export async function settle() {
+    await new Promise<void>(resolve => { setTimeout(resolve, 150); });
+}
diff --git a/test/unit/esm_loading/line_hd_elevation.test.ts b/test/unit/esm_loading/line_hd_elevation.test.ts
@@ -0,0 +1,21 @@
+import {test, expect, waitFor} from '../../util/vitest';
+import {HD} from '../../../modules/hd_main_esm';
+import {makeMap, waitForLoaded} from './helpers';
+
+test('line with hd-road-markup elevation triggers HD loading', async () => {
+    const geojson = {type: 'FeatureCollection', features: [{
+        type: 'Feature', properties: {},
+        geometry: {type: 'LineString', coordinates: [[0, 0], [0.01, 0.01]]},
+    }]};
+    const map = makeMap(
+        [{id: 'road', type: 'line', source: 'geo', layout: {'line-elevation-reference': 'hd-road-markup'}, paint: {}}],
+        {geo: {type: 'geojson', data: geojson}},
+    );
+    try {
+        await waitFor(map, 'idle');
+        await waitForLoaded(HD);
+        expect(HD.loaded).toBe(true);
+    } finally {
+        map.remove();
+    }
+});
diff --git a/test/unit/esm_loading/line_no_elevation.test.ts b/test/unit/esm_loading/line_no_elevation.test.ts
@@ -0,0 +1,21 @@
+import {test, expect, waitFor} from '../../util/vitest';
+import {HD} from '../../../modules/hd_main_esm';
+import {makeMap, settle} from './helpers';
+
+test('line without elevation reference does not load HD', async () => {
+    const geojson = {type: 'FeatureCollection', features: [{
+        type: 'Feature', properties: {},
+        geometry: {type: 'LineString', coordinates: [[0, 0], [0.01, 0.01]]},
+    }]};
+    const map = makeMap(
+        [{id: 'road', type: 'line', source: 'geo', paint: {}}],
+        {geo: {type: 'geojson', data: geojson}},
+    );
+    try {
+        await waitFor(map, 'idle');
+        await settle();
+        expect(HD.loaded).toBeUndefined();
+    } finally {
+        map.remove();
+    }
+});
diff --git a/test/unit/esm_loading/mapbox_standard.test.ts b/test/unit/esm_loading/mapbox_standard.test.ts
@@ -0,0 +1,35 @@
+// Hits the real Mapbox Standard style to verify it loads Standard (which includes
+// model layers) but does not trigger HD. Guards against HD being accidentally
+// pulled in by Standard. Uses the localhost-scoped CI token; the test will fail
+// if the token is invalid or the API is unreachable.
+import {test, expect, vi, waitFor} from '../../util/vitest';
+import {Map, setAccessToken} from '../../../src/index.esm';
+import {LOCALHOST_CI_TOKEN} from '../../util/access_token.js';
+import {HD} from '../../../modules/hd_main_esm';
+import {Standard} from '../../../modules/standard_main_esm';
+import {makeContainer, settle, waitForLoaded} from './helpers';
+
+test('mapbox standard style loads Standard but not HD', {timeout: 30000}, async () => {
+    setAccessToken(LOCALHOST_CI_TOKEN);
+    vi.spyOn(Map.prototype, '_detectMissingCSS').mockImplementation(() => {});
+    const map = new Map({
+        testMode: true,
+        container: makeContainer(),
+        zoom: 1,
+        center: [0, 0],
+        interactive: false,
+        attributionControl: false,
+        performanceMetricsCollection: false,
+        precompilePrograms: false,
+        style: 'mapbox://styles/mapbox/standard',
+    });
+    try {
+        await waitFor(map, 'idle');
+        await waitForLoaded(Standard);
+        await settle();
+        expect(Standard.loaded).toBe(true);
+        expect(HD.loaded).toBeUndefined();
+    } finally {
+        map.remove();
+    }
+});
diff --git a/test/unit/esm_loading/mapbox_streets-v12.test.ts b/test/unit/esm_loading/mapbox_streets-v12.test.ts
@@ -0,0 +1,34 @@
+// Hits the real Mapbox Streets v12 style to verify it loads neither HD nor Standard.
+// Guards against regressions where a layer type added to Streets v12 accidentally
+// triggers a module load. Uses the localhost-scoped CI token; the test will fail
+// if the token is invalid or the API is unreachable.
+import {test, expect, vi, waitFor} from '../../util/vitest';
+import {Map, setAccessToken} from '../../../src/index.esm';
+import {LOCALHOST_CI_TOKEN} from '../../util/access_token.js';
+import {HD} from '../../../modules/hd_main_esm';
+import {Standard} from '../../../modules/standard_main_esm';
+import {makeContainer, settle} from './helpers';
+
+test('mapbox streets-v12 style loads neither HD nor Standard', {timeout: 30000}, async () => {
+    setAccessToken(LOCALHOST_CI_TOKEN);
+    vi.spyOn(Map.prototype, '_detectMissingCSS').mockImplementation(() => {});
+    const map = new Map({
+        testMode: true,
+        container: makeContainer(),
+        zoom: 1,
+        center: [0, 0],
+        interactive: false,
+        attributionControl: false,
+        performanceMetricsCollection: false,
+        precompilePrograms: false,
+        style: 'mapbox://styles/mapbox/streets-v12',
+    });
+    try {
+        await waitFor(map, 'idle');
+        await settle();
+        expect(HD.loaded).toBeUndefined();
+        expect(Standard.loaded).toBeUndefined();
+    } finally {
+        map.remove();
+    }
+});
diff --git a/test/unit/esm_loading/precipitation.test.ts b/test/unit/esm_loading/precipitation.test.ts
@@ -0,0 +1,18 @@
+// Precipitation triggers HD via a separate code path in painter.ts (line ~1169)
+// that is independent of mayUse and renderLayer. This test exercises that path.
+import {test, expect, waitFor} from '../../util/vitest';
+import {HD} from '../../../modules/hd_main_esm';
+import {makeMap, waitForLoaded} from './helpers';
+
+test('rain precipitation triggers HD loading via painter path', async () => {
+    const map = makeMap();
+    try {
+        await waitFor(map, 'idle');
+        map.painter._debugParams.forceEnablePrecipitation = true;
+        map.triggerRepaint();
+        await waitForLoaded(HD);
+        expect(HD.loaded).toBe(true);
+    } finally {
+        map.remove();
+    }
+});
diff --git a/test/unit/esm_loading/raster_particle.test.ts b/test/unit/esm_loading/raster_particle.test.ts
@@ -0,0 +1,27 @@
+// This is the primary regression test for the raster-particle bug: RasterParticleStyleLayer
+// was missing mayUse('HD'), so setupHD() was never triggered from renderLayer.
+// raster-particle bypasses the coords guard in renderLayer, so renderLayer fires even with
+// no tile data. A non-empty tiles URL is still required to pass style validation; tile loads
+// are mocked to 404 so no real network traffic occurs.
+import {test, expect} from '../../util/vitest';
+import {mockFetch} from '../../util/network';
+import {HD} from '../../../modules/hd_main_esm';
+import {Standard} from '../../../modules/standard_main_esm';
+import {makeMap, waitForLoaded} from './helpers';
+
+test('raster-particle layer triggers HD loading', async () => {
+    mockFetch({'.*': () => Promise.resolve(new Response(null, {status: 404}))});
+    const map = makeMap(
+        [{id: 'rp', type: 'raster-particle', source: 'wind', 'source-layer': 'u_component_of_wind', paint: {}}],
+        {wind: {type: 'raster-array', tiles: ['https://example.com/{z}/{x}/{y}.mrt'], tileSize: 512}},
+    );
+    try {
+        // Don't wait for idle (depends on tile load completion); just wait for
+        // setupHD() to fire, which happens on the first render frame.
+        await waitForLoaded(HD);
+        expect(HD.loaded).toBe(true);
+        expect(Standard.loaded).toBeUndefined();
+    } finally {
+        map.remove();
+    }
+});
diff --git a/test/unit/esm_loading/standard_layers.test.ts b/test/unit/esm_loading/standard_layers.test.ts
@@ -0,0 +1,26 @@
+import {test, expect, waitFor} from '../../util/vitest';
+import {HD} from '../../../modules/hd_main_esm';
+import {makeMap, settle} from './helpers';
+
+test('standard-style-like layers (fill/line/symbol/fill-extrusion) do not load HD', async () => {
+    const geojson = {type: 'FeatureCollection', features: [{
+        type: 'Feature', properties: {height: 20},
+        geometry: {type: 'Polygon', coordinates: [[[0, 0], [0, 0.01], [0.01, 0.01], [0.01, 0], [0, 0]]]},
+    }]};
+    const map = makeMap(
+        [
+            {id: 'fill',    type: 'fill',           source: 'geo', paint: {}},
+            {id: 'line',    type: 'line',           source: 'geo', paint: {}},
+            {id: 'symbol',  type: 'symbol',         source: 'geo', layout: {}},
+            {id: 'extrude', type: 'fill-extrusion', source: 'geo', paint: {'fill-extrusion-height': ['get', 'height']}},
+        ],
+        {geo: {type: 'geojson', data: geojson}},
+    );
+    try {
+        await waitFor(map, 'idle');
+        await settle();
+        expect(HD.loaded).toBeUndefined();
+    } finally {
+        map.remove();
+    }
+});
diff --git a/test/unit/style/style.test.ts b/test/unit/style/style.test.ts
@@ -3412,6 +3412,8 @@ describe('Style HD coverage source-cache wiring', () => {
             paint: {'fill-color': 'red', 'fill-opacity': 0}
         });
         await waitFor(style, 'style.load');
+        // Wait for HD Module to be loaded
+        await vi.waitUntil(() => style._hdCoverage !== null, {timeout: 2000});
 
         expect(style._hdCoverage).not.toBeNull();
         // The dedicated cache key is `hd-road-coverage:<sourceId>`.
@@ -3439,6 +3441,8 @@ describe('Style HD coverage source-cache wiring', () => {
         await waitFor(style, 'style.load');
 
         const cacheKey = `hd-road-coverage:hd-roads`;
+        // Wait for HD module to be loaded
+        await vi.waitUntil(() => style._sourceCaches[cacheKey] !== undefined, {timeout: 2000});
         expect(style._sourceCaches[cacheKey]).toBeDefined();
         // Only one coverage cache total for this source.
         const coverageKeys = Object.keys(style._sourceCaches).filter(k => k.startsWith('hd-road-coverage:'));
diff --git a/test/unit/style/utils.ts b/test/unit/style/utils.ts
@@ -24,6 +24,8 @@ export class StubMap extends Evented {
 
     setCamera() {}
 
+    _update() {}
+
     _getMapId() {
         return 1;
     }
diff --git a/test/util/access_token.js b/test/util/access_token.js
@@ -1,10 +1,12 @@
+// Domain-restricted to localhost. Safe to commit; used by debug pages and tests.
+export const LOCALHOST_CI_TOKEN = 'pk.eyJ1IjoiZ2wtanMtdGVhbSIsImEiOiJjbTV1d3l0d3AwMThnMmpzZ2M5OTNyeDE1In0.2nygBIo7PXbkFCCt6LEBgw';
+
 export function getAccessToken() {
     const accessToken =
         process.env.MAPBOX_ACCESS_TOKEN ||
         (new URLSearchParams(location.search).get('access_token')) ||
         localStorage.getItem('accessToken') ||
-        // this token is a fallback for CI and testing. it is domain restricted to localhost
-        'pk.eyJ1IjoiZ2wtanMtdGVhbSIsImEiOiJjbTV1d3l0d3AwMThnMmpzZ2M5OTNyeDE1In0.2nygBIo7PXbkFCCt6LEBgw'
+        LOCALHOST_CI_TOKEN;
 
     localStorage.setItem('accessToken', accessToken);
     return accessToken;
diff --git a/vitest.config.unit.ts b/vitest.config.unit.ts
@@ -1,5 +1,6 @@
 import {basename as pathBasename} from 'node:path';
 import {readFileSync, globSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
 import {mergeConfig, defineConfig} from 'vitest/config';
 import baseConfig, {isCI, chromiumBrowser} from './vitest.config.base';
 
@@ -66,6 +67,20 @@ function styleSpecFixtures() {
 }
 
 export default mergeConfig(baseConfig, defineConfig({
+    resolve: {
+        alias: [
+            // Mirror the Rollup ESM substitution so unit tests exercise the real
+            // lazy-loading path instead of the always-loaded static versions.
+            {
+                find: /.*\/modules\/hd_main$/,
+                replacement: fileURLToPath(new URL('./modules/hd_main_esm.ts', import.meta.url)),
+            },
+            {
+                find: /.*\/modules\/standard_main$/,
+                replacement: fileURLToPath(new URL('./modules/standard_main_esm.ts', import.meta.url)),
+            },
+        ],
+    },
     // Forbid Vite's on-demand dep discovery so it can't reload the page mid-run.
     // Only CJS deps (those needing ESM interop) must be listed; pure-ESM deps
     // work without it.
