React测试GraphQL查询报错：TypeError: (0 , _client.gql) is not a function

算力阿峰

2026-7-7

解决Jest测试中Apollo Client gql 不是函数的问题

核心原因

CRA默认的Jest配置没正确处理Apollo Client的ES模块导出，或者测试环境里gql函数的导出未被正确模拟。

可行解决方案

1. 统一`gql`的导入路径

确保业务代码和测试文件里的gql都从@apollo/client导入，别混用旧版的apollo-boost或其他路径：

import { gql } from '@apollo/client';

2. 手动模拟`gql`函数

单个测试文件内模拟

在测试文件顶部添加模拟逻辑：

import { gql } from '@apollo/client';

// 保留Apollo Client其他原有导出，仅替换gql为模拟函数
jest.mock('@apollo/client', () => ({
  ...jest.requireActual('@apollo/client'),
  gql: jest.fn((query) => query),
}));

// 你的测试用例
describe('useFetchPlayers', () => {
  // 编写测试逻辑
});

全局模拟（一次配置所有测试生效）

在项目根目录新建__mocks__/@apollo/client.js文件，写入以下内容：

const actual = jest.requireActual('@apollo/client');

module.exports = {
  ...actual,
  gql: jest.fn((query) => query),
};

3. 适配`gql`模板字符串特性

如果你的查询用了模板字符串语法，调整模拟逻辑以支持该特性：

gql: jest.fn().mockImplementation((literals, ...placeholders) => {
  return literals.reduce((acc, val, i) => acc + val + (placeholders[i] || ''), '');
});

4. 给测试hook配置Apollo Provider

测试自定义hook时，必须用ApolloProvider包裹，并传入测试用的客户端实例：

import { renderHook } from '@testing-library/react';
import { ApolloProvider, ApolloClient, InMemoryCache } from '@apollo/client';

// 创建测试用客户端
const testClient = new ApolloClient({
  uri: 'https://test.example.com/graphql',
  cache: new InMemoryCache(),
});

// 封装Provider作为测试包裹器
const wrapper = ({ children }) => (
  <ApolloProvider client={testClient}>{children}</ApolloProvider>
);

// 执行hook测试
test('useFetchPlayers能正常获取数据', () => {
  const { result } = renderHook(() => useFetchPlayers(), { wrapper });
  // 编写断言逻辑
});