🚀 GraphQL Apollo Auto Mocker

Intelligent GraphQL mocking framework for Apollo Client with seamless real server fallback

✨ Features

• 🧠 Intelligent Mock Generation - Smart field detection using heuristics and faker.js
• 🔄 Hybrid Mode - Seamlessly switch between mock data and real server responses
• 🎯 Type-Safe Configuration - Full TypeScript support with fine-grained control
• ⚡ Zero Setup - Works out of the box with any GraphQL schema
• 🎛️ Flexible Control - Configure mocking at global, operation, type, and field levels
• 🔗 Apollo Integration - Drop-in replacement for your existing Apollo Client setup
• 📊 Rich Data Types - Built-in support for scalars, arrays, dates, and custom generators

📦 Installation

npm install @kozielgpc/graphql-apollo-auto-mocker @apollo/client graphql @faker-js/faker

yarn add @kozielgpc/graphql-apollo-auto-mocker @apollo/client graphql @faker-js/faker

🚀 Quick Start

Basic Setup

import { createAutoMockApolloClient } from '@kozielgpc/graphql-apollo-auto-mocker';

const schemaSDL = `
  type Query {
    getUser(id: ID!): User
    getOrders: [Order]
  }

  type User {
    id: ID!
    name: String!
    email: String!
    createdAt: String!
  }

  type Order {
    totalValue: Float!
    items: [Item!]!
    status: String!
    orderDate: String!
  }

  type Item {
    id: ID!
    name: String!
    quantity: Int!
    price: Float!
  }
`;

const client = createAutoMockApolloClient({
  schemaSDL,
  uri: 'https://your-graphql-server.com/graphql',
  mockConfig: {
    enabled: true, // Toggle this to enable/disable mocking
  }
});

With React

import React from 'react';
import { ApolloProvider, useQuery, gql } from '@apollo/client';
import { createAutoMockApolloClient } from '@kozielgpc/graphql-apollo-auto-mocker';

const GET_USER = gql`
  query GetUser($id: ID!) {
    getUser(id: $id) {
      id
      name
      email
      createdAt
    }
  }
`;

function UserProfile({ userId }: { userId: string }) {
  const { loading, error, data } = useQuery(GET_USER, {
    variables: { id: userId }
  });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <div>
      <h1>{data.getUser.name}</h1>
      <p>Email: {data.getUser.email}</p>
      <p>Member since: {data.getUser.createdAt}</p>
    </div>
  );
}

function App() {
  const client = createAutoMockApolloClient({
    schemaSDL: yourSchemaSDL,
    uri: '/graphql',
    mockConfig: { enabled: true }
  });

  return (
    <ApolloProvider client={client}>
      <UserProfile userId="123" />
    </ApolloProvider>
  );
}

🎛️ Configuration

Type-Safe MockConfig

Control mocking behavior with a fully typed configuration object:

import { MockConfig } from '@kozielgpc/graphql-apollo-auto-mocker';

const mockConfig: MockConfig = {
  // Global toggle
  enabled: true,
  
  // Per-operation control
  operations: {
    getOrders: { enabled: true },
    getUser: { enabled: false }, // This will use real server
    getUserProfile: { enabled: true }
  },
  
  // Per-type and per-field control
  types: {
    Order: {
      fields: {
        totalValue: { 
          min: 50, 
          max: 5000 
        },
        items: { 
          arrayMin: 1, 
          arrayMax: 10 
        },
        status: {
          value: () => ['pending', 'processing', 'shipped', 'delivered'][Math.floor(Math.random() * 4)]
        }
      }
    },
    Item: {
      fields: {
        quantity: { 
          min: 1, 
          max: 20 
        },
        price: { 
          min: 5, 
          max: 500 
        }
      }
    },
    User: {
      fields: {
        name: { 
          value: () => `Test User ${Math.floor(Math.random() * 1000)}` 
        },
        email: { 
          value: '[email protected]' 
        }
      }
    }
  }
};

Field Configuration Options

interface MockFieldConfig {
  // Number constraints
  min?: number;
  max?: number;
  
  // Date constraints
  minDate?: string; // ISO date string
  maxDate?: string; // ISO date string
  
  // Array constraints
  arrayMin?: number;
  arrayMax?: number;
  
  // Custom values
  value?: any | (() => any);
}

Advanced Setup with Custom Matcher

const client = createAutoMockApolloClient({
  schemaSDL,
  uri: '/graphql',
  mockConfig: {
    enabled: true,
  },
  // Custom logic to determine which operations to mock
  matcher: (operation) => {
    // Only mock read operations, not mutations
    return operation.operationName?.startsWith('get') ?? false;
  }
});

🧠 Intelligent Field Generation

The auto-mocker uses smart heuristics to generate realistic data based on field names and types:

Field Name Heuristics

• Email fields: email, userEmail → [email protected]
• Name fields: name, firstName, lastName, productName → John Doe / Premium Widget
• Date fields: createdAt, updatedAt, orderDate → 2023-08-15T10:30:00.000Z
• ID fields: id, userId, orderId, itemId → 550e8400-e29b-41d4-a716-446655440000
• Amount fields: quantity, price, totalValue → 5 / 1234.56
• Phone fields: phone, phoneNumber → +1-555-123-4567

GraphQL Type Mapping

• String → Lorem ipsum text
• Int → Random integer (0-100, configurable)
• Float → Random decimal (0-100, configurable)
• Boolean → Random true/false
• ID → UUID string
• Arrays → 1-3 items by default (configurable)

🔄 Hybrid Mode

The auto-mocker seamlessly combines mocked and real data:

const mockConfig: MockConfig = {
  enabled: true,
  operations: {
    // Mock these operations
    getOrders: { enabled: true },
    getUserProfile: { enabled: true },
    
    // Use real server for these
    updateUser: { enabled: false },
    processPayment: { enabled: false },
    createOrder: { enabled: false }
  }
};

// Queries will be mocked, mutations will hit the real server
const client = createAutoMockApolloClient({
  schemaSDL,
  uri: 'https://api.yourapp.com/graphql',
  mockConfig
});

🎯 Use Cases

Development & Testing

// Development environment
const isDevelopment = process.env.NODE_ENV === 'development';

const client = createAutoMockApolloClient({
  schemaSDL,
  uri: '/graphql',
  mockConfig: {
    enabled: isDevelopment, // Auto-enable in dev
    types: {
      User: {
        fields: {
          // Use consistent test data in development
          name: { value: 'Test User' },
          email: { value: '[email protected]' }
        }
      }
    }
  }
});

Feature Flagged Mocking

const client = createAutoMockApolloClient({
  schemaSDL,
  uri: '/graphql',
  mockConfig: {
    enabled: true
  },
  matcher: (operation) => {
    // Mock operations based on feature flags
    return window.featureFlags?.mockGraphQL === true;
  }
});

Storybook Integration

// .storybook/apollo-client.js
import { createAutoMockApolloClient } from '@kozielgpc/graphql-apollo-auto-mocker';

export const mockClient = createAutoMockApolloClient({
  schemaSDL: storybookSchema,
  uri: '', // Not used in Storybook
  mockConfig: {
    enabled: true,
    types: {
      User: {
        fields: {
          avatar: { value: 'https://via.placeholder.com/150' }
        }
      }
    }
  }
});

📚 API Reference

createAutoMockApolloClient(options)

Creates an Apollo Client with auto-mocking capabilities.

Parameters:

• schemaSDL (string): GraphQL schema definition
• uri (string): Real GraphQL server endpoint
• mockConfig? (MockConfig): Configuration object
• cacheOptions? (ApolloCache | object): Cache configuration

Returns: ApolloClient instance

createAutoMockLink(options)

Creates an Apollo Link for advanced use cases.

Parameters:

• schemaSDL (string): GraphQL schema definition
• mockConfig? (MockConfig): Configuration object
• matcher? (function): Custom operation matcher

mockOperation(schemaSDL, operationType, operationName, config?)

Low-level function to generate mock data for a specific operation.

🔧 Advanced Examples

Custom Cache Configuration

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

const client = createAutoMockApolloClient({
  schemaSDL,
  uri: '/graphql',
  mockConfig: { enabled: true },
  cacheOptions: new InMemoryCache({
    typePolicies: {
      User: {
        fields: {
          orders: {
            merge: false // Replace instead of merging arrays
          }
        }
      }
    }
  })
});

Complex Field Generators

const mockConfig: MockConfig = {
  enabled: true,
  types: {
    Order: {
      fields: {
        shippingInfo: {
          value: () => ({
            estimatedDays: Math.floor(Math.random() * 7) + 1, // 1-7 days
            carrier: ['FedEx', 'UPS', 'USPS', 'DHL'][Math.floor(Math.random() * 4)],
            trackingNumber: `TRK${Math.random().toString(36).substr(2, 9).toUpperCase()}`
          })
        },
        priority: {
          value: () => ['low', 'normal', 'high', 'urgent'][Math.floor(Math.random() * 4)]
        }
      }
    },
    Item: {
      fields: {
        category: {
          value: () => ['Electronics', 'Clothing', 'Home & Garden', 'Books', 'Sports'][Math.floor(Math.random() * 5)]
        }
      }
    }
  }
};

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Faker.js - For realistic mock data generation
• Apollo Client - For the excellent GraphQL client
• GraphQL - For the amazing query language