使用MockedProvider进行React GraphQL测试出现文档解析报错如何解决

Invariant Violation: Expecting a parsed GraphQL document. Perhaps you need to wrap the query string in a "gql" tag?

该报错本质是Apollo Client运行时检测到传入的GraphQL操作（查询/突变）没有被解析为标准AST文档对象，仍为原始字符串格式，无法通过类型校验。常见触发场景如下：

• Mock配置中的request.query字段直接传入字符串形式的GraphQL语句，未使用gql标签处理
• 业务组件内部调用接口时使用的查询语句未添加gql标签
• 项目依赖版本不匹配，gql标签的解析逻辑执行异常
• Mock配置的查询语句与组件实际调用的查询语句存在格式、字段、参数差异，导致匹配失败后触发底层校验

• 所有使用GraphQL语句的位置（包括业务组件、Mock配置）都需要使用gql标签包裹，示例代码如下：

// Apollo Client 3.x 直接从包内导入gql，无需单独安装graphql-tag
import { gql, MockedProvider } from '@apollo/client';

// 用gql标签包裹查询语句，解析为AST文档对象
const GET_USER_INFO = gql`
  query GetUserInfo($userId: ID!) {
    user(id: $userId) {
      id
      name
      avatar
    }
  }
`;

// Mock配置中直接传入解析后的AST对象即可
const mocks = [
  {
    request: {
      query: GET_USER_INFO,
      variables: { userId: '123' }
    },
    result: {
      data: {
        user: {
          id: '123',
          name: '张三',
          avatar: 'https://example.com/avatar.png'
        }
      }
    }
  }
];

• 校验Mock配置的查询语句与组件实际调用的查询语句完全一致，包括字段顺序、查询命名、参数名、换行空格都不能有差异
• 统一依赖版本，确保@apollo/client、graphql的主版本适配，避免多个版本的graphql-tag被同时加载
• 若使用Webpack等打包工具，检查loader配置是否正确处理gql标签，不要将gql包裹的内容当作普通字符串处理

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