使用Vitest与React Testing Library测试时出现Leaflet '_leaflet_id'错误

问题本质 #

这个错误是Leaflet在尝试检查图层的_leaflet_id属性时，传入了null对象导致的。开发/生产环境中浏览器DOM加载完整，Leaflet地图实例能正常初始化，但测试环境下，React-Leaflet的地图实例可能还未就绪，组件就触发了图层添加操作，进而抛出异常。

可行解决方案 #

1. 给地图组件加初始化兜底判断 #

在地图组件中，通过whenCreated钩子确认地图实例就绪后，再渲染图层：

import { useState } from 'react';
import { MapContainer } from 'react-leaflet';

const MyMap = ({ layers }) => {
  const [mapReady, setMapReady] = useState(false);

  return (
    <MapContainer
      center={[51.505, -0.09]}
      zoom={13}
      whenCreated={() => setMapReady(true)}
    >
      {/* 仅在地图初始化完成后渲染图层 */}
      {mapReady && layers.map(layer => <YourLayer key={layer.id} {...layer} />)}
    </MapContainer>
  );
};

2. 在Vitest中模拟Leaflet核心方法 #

通过vi.mock改写Leaflet的工具方法，避免传入null时出错：

// 在测试文件顶部添加模拟逻辑
vi.mock('leaflet', async () => {
  const original = await vi.importActual('leaflet');
  return {
    ...original,
    Util: {
      ...original.Util,
      // 给stamp方法加null判断，避免报错
      stamp: (obj) => obj?._leaflet_id || Math.random(),
    },
  };
});

3. 用waitFor确保组件稳定后再操作 #

测试时不要立即执行断言，等待地图组件完成初始化：

import { render, waitFor, screen } from '@testing-library/react';
import App from './App';

test('渲染应用不触发Leaflet错误', async () => {
  render(<App />);
  // 等待地图元素出现，确认初始化完成
  await waitFor(() => {
    expect(screen.getByRole('map')).toBeInTheDocument();
  });
  // 这里添加你的业务逻辑断言
});

4. 统一封装安全的图层添加函数 #

如果项目中有多处addLayer调用，封装一个带校验的工具函数：

export const safeAddLayer = (map, layer) => {
  // 先校验map和layer是否存在，再执行添加
  if (map && layer) {
    map.addLayer(layer);
  }
};

额外提示 #

测试环境没有真实的Leaflet渲染上下文，建议聚焦测试组件的业务逻辑，而非Leaflet底层渲染细节；如果有异步加载图层的逻辑，要提前mock接口返回，确保测试数据同步可用。

内容的提问来源于stack exchange，提问作者C RICH