Dummy Client for Testing

QueryLeaf provides a DummyQueryLeaf class that helps you test and debug your SQL queries without connecting to a real MongoDB database. This is useful for:

Development without a MongoDB instance
Unit testing without database dependencies
Debugging SQL to MongoDB translations
Generating MongoDB commands for documentation

This guide explains how to use the dummy client effectively.

Basic Usage

The DummyQueryLeaf class mimics the real QueryLeaf but logs operations instead of executing them:

import { DummyQueryLeaf } from '@queryleaf/lib';

// Create a dummy client (no MongoDB client required)
const dummyLeaf = new DummyQueryLeaf('mydb');

// Execute a query (will be logged, not executed)
await dummyLeaf.execute('SELECT name, email FROM users WHERE age > 21');
// [DUMMY MongoDB] FIND in mydb.users with filter: {"age":{"$gt":21}}
// [DUMMY MongoDB] Executing find on users with projection: {"name":1,"email":1}

Debugging SQL Translation

The dummy client is particularly useful for understanding how SQL queries are translated to MongoDB commands:

import { DummyQueryLeaf } from '@queryleaf/lib';

async function debugSqlTranslation() {
  const dummyLeaf = new DummyQueryLeaf('testdb');

  console.log('===== SELECT with WHERE =====');
  await dummyLeaf.execute(
    'SELECT name, email FROM users WHERE age > 21 AND (status = "active" OR role = "admin")'
  );

  console.log('\n===== JOIN =====');
  await dummyLeaf.execute(`
    SELECT u.name, o.total 
    FROM users u 
    JOIN orders o ON u._id = o.userId 
    WHERE o.status = "completed"
  `);

  console.log('\n===== GROUP BY with Aggregation =====');
  await dummyLeaf.execute(`
    SELECT category, COUNT(*) as count, AVG(price) as avg_price 
    FROM products 
    GROUP BY category
  `);
}

debugSqlTranslation().catch(console.error);

This will output detailed logs showing how each SQL query is translated to MongoDB operations.

Using in Unit Tests

The dummy client is especially useful in unit tests where you want to verify that your application generates the correct SQL queries without actually executing them:

import { DummyQueryLeaf } from '@queryleaf/lib';

// Mock console.log to capture output
let consoleOutput: string[] = [];
const originalLog = console.log;
console.log = (message: string) => {
  consoleOutput.push(message);
  originalLog(message);
};

describe('User Service', () => {
  let dummyLeaf: DummyQueryLeaf;
  let userService: UserService;

  beforeEach(() => {
    consoleOutput = [];
    dummyLeaf = new DummyQueryLeaf('testdb');
    userService = new UserService(dummyLeaf);
  });

  afterAll(() => {
    console.log = originalLog;
  });

  test('getActiveUsers should generate correct SQL', async () => {
    await userService.getActiveUsers();

    // Check that the correct query was generated
    expect(consoleOutput.some(log => 
      log.includes('FIND in testdb.users with filter: {"status":"active"}')
    )).toBe(true);
  });

  test('createUser should generate correct INSERT', async () => {
    const user = { name: 'Test User', email: '[email protected]', age: 30 };
    await userService.createUser(user);

    // Check that the correct insert was generated
    expect(consoleOutput.some(log => 
      log.includes('INSERT in testdb.users')
    )).toBe(true);
  });
});

How the Dummy Client Works

The DummyQueryLeaf class follows the same flow as the real QueryLeaf:

Parses the SQL query to an AST
Compiles the AST to MongoDB commands
Instead of executing the commands, it logs them

This means it validates that your SQL syntax is correct and shows how it would be executed, without actually running the operations.

Customizing the Dummy Client

You can extend the DummyQueryLeaf class for custom testing scenarios:

import { DummyQueryLeaf, Command } from '@queryleaf/lib';

class TestingQueryLeaf extends DummyQueryLeaf {
  public commands: Command[] = [];

  // Override to capture commands for assertions
  protected async executeDummyCommand(command: Command): Promise<any> {
    this.commands.push(command);
    return await super.executeDummyCommand(command);
  }

  // Override to provide mock data
  protected executeDummyFind(command: Command): any[] {
    // Return fake data based on the collection
    if (command.collection === 'users') {
      return [
        { _id: '1', name: 'Alice', email: '[email protected]', age: 28 },
        { _id: '2', name: 'Bob', email: '[email protected]', age: 35 }
      ];
    }
    return [];
  }

  // Clear captured commands between tests
  public reset(): void {
    this.commands = [];
  }
}

// Usage in tests
const testLeaf = new TestingQueryLeaf('testdb');
await testLeaf.execute('SELECT * FROM users WHERE age > 30');

// Now you can assert on the captured commands
expect(testLeaf.commands.length).toBe(1);
expect(testLeaf.commands[0].type).toBe('FIND');
expect(testLeaf.commands[0].filter).toEqual({ age: { $gt: 30 } });

Common Testing Patterns

Testing Query Generation

test('should generate correct MongoDB filter from SQL WHERE clause', async () => {
  const dummyLeaf = new DummyQueryLeaf('testdb');

  // Capture console output
  const spy = jest.spyOn(console, 'log');

  await dummyLeaf.execute(
    'SELECT * FROM users WHERE status = "active" AND age BETWEEN 18 AND 65'
  );

  // Verify the correct filter was generated
  expect(spy).toHaveBeenCalledWith(
    expect.stringContaining('"status":"active"')
  );
  expect(spy).toHaveBeenCalledWith(
    expect.stringContaining('"age":{"$gte":18,"$lte":65}')
  );

  spy.mockRestore();
});

Testing Error Handling

test('should throw error on invalid SQL syntax', async () => {
  const dummyLeaf = new DummyQueryLeaf('testdb');

  // Test invalid SQL
  await expect(
    dummyLeaf.execute('SELECT * FORM users') // Typo in FROM
  ).rejects.toThrow();
});

Next Steps

Now that you understand how to use the dummy client for testing, you can:

Learn about MongoDB Client Integration for real execution
Explore SQL Syntax Support for supported features
Check out Usage Examples for more complex scenarios