Next.js中Jest结合Firebase模拟器测试遇import语法错误求助

问题原因 #

Jest默认采用CommonJS模块系统，而当前Firebase官方npm包为纯ESM格式，直接导入会触发SyntaxError: Cannot use import statement outside a module错误。

解决方案 #

1. 修改Jest配置，允许转译Firebase相关包 #

编辑项目根目录的jest.config.js，添加transformIgnorePatterns配置，让Jest转译node_modules中的Firebase相关包：

const nextJest = require('next/jest')

const createJestConfig = nextJest({
  dir: './',
})

const customJestConfig = {
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1', // 根据你的路径别名调整
  },
  // 关键配置：排除Firebase相关包，让Babel转译它们
  transformIgnorePatterns: [
    '/node_modules/(?!firebase|@firebase|firebase-admin)/',
  ],
  testEnvironment: 'jest-environment-jsdom',
}

module.exports = createJestConfig(customJestConfig)

2. 修正Firebase模拟器初始化逻辑 #

不要在describe顶层调用模拟器连接方法，建议在beforeAll中初始化模拟器，并在beforeEach中清空数据保证测试隔离：

import { render, screen } from '@testing-library/react';
import '@testing-library/jest-dom';
import { firestore } from '../src/lib/firebase';
import { connectFirestoreEmulator, clearFirestoreData } from 'firebase/firestore';

describe('Example', () => {
  beforeAll(() => {
    // 连接Firestore模拟器
    connectFirestoreEmulator(firestore, 'localhost', 8080);
  });

  beforeEach(async () => {
    // 每次测试前清空模拟器数据，避免测试污染
    await clearFirestoreData({ projectId: '你的测试项目ID' });
  });

  it('example test', () => {
    render(<div>Hello</div>);
    const heading = screen.getByText('Hello');
    expect(heading).toBeInTheDocument();
  });
});

3. GitHub Actions配置（自动运行带模拟器的测试） #

在.github/workflows/test.yml中添加以下配置，实现自动启动模拟器并运行测试：

name: Run Tests with Firebase Emulator

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - name: Install Dependencies
        run: npm ci
      - name: Install Firebase CLI
        run: npm install -g firebase-tools
      - name: Start Firebase Emulator & Run Tests
        run: |
          # 后台启动Firestore模拟器
          firebase emulators:start --only firestore --export-on-exit ./emulator-data &
          # 等待模拟器完全启动（可根据实际情况调整等待时间）
          sleep 10
          # 运行Jest测试
          npm run test

注意事项 #

• 确保Firebase初始化时使用的项目ID与模拟器配置的项目ID一致
• 若使用Next.js 13+ App Router，Jest配置无需额外调整，上述配置已兼容

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