gRPC Testing in Node.js: Unit Tests, Integration Tests, and Mocking

gRPC Testing in Node.js: Unit Tests, Integration Tests, and Mocking

gRPC in Node.js uses @grpc/grpc-js and generated code from protoc or @grpc/proto-loader. Testing patterns differ from REST because there's no HTTP to intercept — you work with the generated service and stub objects directly.

Project Setup

npm install @grpc/grpc-js @grpc/proto-loader
npm install --save-dev jest

Given a proto file:

// product.proto
syntax = "proto3";
package product;

service ProductService {
  rpc GetProduct (GetProductRequest) returns (ProductResponse);
  rpc ListProducts (ListProductsRequest) returns (stream ProductResponse);
}

message GetProductRequest { string product_id = 1; }
message ListProductsRequest { string category = 1; }
message ProductResponse {
  string id = 1;
  string name = 2;
  double price = 3;
  string category = 4;
}

Load the proto dynamically (no codegen needed in Node.js):

// grpc-client.js
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const path = require('path');

const packageDefinition = protoLoader.loadSync(
  path.join(__dirname, 'product.proto'),
  { keepCase: true, longs: String, enums: String, defaults: true, oneofs: true }
);

const proto = grpc.loadPackageDefinition(packageDefinition).product;

module.exports = { proto, grpc };

Unit Testing the Service Handler

The service handler is a plain object with method functions. Unit test them directly.

// product-service.js
class ProductService {
  constructor(productRepo) {
    this.productRepo = productRepo;
  }
  
  getProductHandler() {
    return async (call, callback) => {
      const { product_id } = call.request;
      
      if (!product_id) {
        return callback({
          code: require('@grpc/grpc-js').status.INVALID_ARGUMENT,
          message: 'product_id is required'
        });
      }
      
      try {
        const product = await this.productRepo.findById(product_id);
        if (!product) {
          return callback({
            code: require('@grpc/grpc-js').status.NOT_FOUND,
            message: `Product ${product_id} not found`
          });
        }
        callback(null, product);
      } catch (err) {
        callback({
          code: require('@grpc/grpc-js').status.INTERNAL,
          message: 'Internal server error'
        });
      }
    };
  }
}
// product-service.test.js
const { status } = require('@grpc/grpc-js');
const ProductService = require('./product-service');

describe('ProductService#getProductHandler', () => {
  test('returns product when found', async () => {
    const product = { id: 'p1', name: 'Widget', price: 9.99, category: 'tools' };
    const mockRepo = { findById: jest.fn().mockResolvedValue(product) };
    
    const service = new ProductService(mockRepo);
    const handler = service.getProductHandler();
    
    const mockCall = { request: { product_id: 'p1' } };
    const mockCallback = jest.fn();
    
    await handler(mockCall, mockCallback);
    
    expect(mockCallback).toHaveBeenCalledWith(null, product);
  });
  
  test('returns INVALID_ARGUMENT when product_id is empty', async () => {
    const mockRepo = { findById: jest.fn() };
    const service = new ProductService(mockRepo);
    const handler = service.getProductHandler();
    
    const mockCall = { request: { product_id: '' } };
    const mockCallback = jest.fn();
    
    await handler(mockCall, mockCallback);
    
    expect(mockCallback).toHaveBeenCalledWith(
      expect.objectContaining({ code: status.INVALID_ARGUMENT })
    );
    expect(mockRepo.findById).not.toHaveBeenCalled();
  });
  
  test('returns NOT_FOUND when product does not exist', async () => {
    const mockRepo = { findById: jest.fn().mockResolvedValue(null) };
    const service = new ProductService(mockRepo);
    const handler = service.getProductHandler();
    
    const mockCall = { request: { product_id: 'p999' } };
    const mockCallback = jest.fn();
    
    await handler(mockCall, mockCallback);
    
    expect(mockCallback).toHaveBeenCalledWith(
      expect.objectContaining({
        code: status.NOT_FOUND,
        message: expect.stringContaining('p999')
      })
    );
  });
  
  test('returns INTERNAL on repository error', async () => {
    const mockRepo = {
      findById: jest.fn().mockRejectedValue(new Error('DB down'))
    };
    const service = new ProductService(mockRepo);
    const handler = service.getProductHandler();
    
    const mockCall = { request: { product_id: 'p1' } };
    const mockCallback = jest.fn();
    
    await handler(mockCall, mockCallback);
    
    expect(mockCallback).toHaveBeenCalledWith(
      expect.objectContaining({ code: status.INTERNAL })
    );
  });
});

Unit Testing Server Streaming

Server streaming handlers call call.write() for each message and call.end() when done.

// streaming handler
listProductsHandler() {
  return async (call) => {
    const { category } = call.request;
    
    try {
      const products = await this.productRepo.findByCategory(category);
      for (const product of products) {
        if (call.cancelled) break;
        call.write(product);
      }
      call.end();
    } catch (err) {
      call.destroy(new Error('Stream failed'));
    }
  };
}
describe('ProductService#listProductsHandler', () => {
  test('writes all products and ends stream', async () => {
    const products = [
      { id: 'p1', name: 'Widget', price: 9.99, category: 'tools' },
      { id: 'p2', name: 'Gadget', price: 19.99, category: 'tools' }
    ];
    const mockRepo = { findByCategory: jest.fn().mockResolvedValue(products) };
    
    const service = new ProductService(mockRepo);
    const handler = service.listProductsHandler();
    
    const writtenMessages = [];
    const mockCall = {
      request: { category: 'tools' },
      cancelled: false,
      write: jest.fn((msg) => writtenMessages.push(msg)),
      end: jest.fn(),
      destroy: jest.fn()
    };
    
    await handler(mockCall);
    
    expect(writtenMessages).toHaveLength(2);
    expect(writtenMessages[0].name).toBe('Widget');
    expect(mockCall.end).toHaveBeenCalled();
    expect(mockCall.destroy).not.toHaveBeenCalled();
  });
  
  test('stops writing when call is cancelled', async () => {
    const products = Array.from({ length: 10 }, (_, i) => ({
      id: `p${i}`, name: `Product ${i}`, price: i * 10, category: 'tools'
    }));
    const mockRepo = { findByCategory: jest.fn().mockResolvedValue(products) };
    
    const service = new ProductService(mockRepo);
    const handler = service.listProductsHandler();
    
    let writeCount = 0;
    const mockCall = {
      request: { category: 'tools' },
      get cancelled() { return writeCount >= 3; }, // cancel after 3 writes
      write: jest.fn(() => writeCount++),
      end: jest.fn(),
      destroy: jest.fn()
    };
    
    await handler(mockCall);
    
    expect(writeCount).toBe(3);
  });
});

Integration Testing with a Real gRPC Server

// test/integration/product-service.integration.test.js
const grpc = require('@grpc/grpc-js');
const { proto } = require('../../grpc-client');
const { createServer } = require('../../server');

let server;
let client;

beforeAll(async () => {
  const { host, port } = await new Promise((resolve, reject) => {
    const s = createServer(new InMemoryProductRepo([
      { id: 'p1', name: 'Widget', price: 9.99, category: 'tools' },
      { id: 'p2', name: 'Gadget', price: 19.99, category: 'tools' }
    ]));
    
    s.bindAsync('127.0.0.1:0', grpc.ServerCredentials.createInsecure(), (err, port) => {
      if (err) return reject(err);
      s.start();
      server = s;
      resolve({ host: '127.0.0.1', port });
    });
  });
  
  client = new proto.ProductService(
    `${host}:${port}`,
    grpc.credentials.createInsecure()
  );
});

afterAll(() => {
  client.close();
  server.forceShutdown();
});

test('getProduct returns product', (done) => {
  client.getProduct({ product_id: 'p1' }, (err, response) => {
    expect(err).toBeNull();
    expect(response.name).toBe('Widget');
    done();
  });
});

test('getProduct returns NOT_FOUND for missing product', (done) => {
  client.getProduct({ product_id: 'nonexistent' }, (err) => {
    expect(err).not.toBeNull();
    expect(err.code).toBe(grpc.status.NOT_FOUND);
    done();
  });
});

test('listProducts streams results', (done) => {
  const received = [];
  const stream = client.listProducts({ category: 'tools' });
  
  stream.on('data', (product) => received.push(product));
  stream.on('end', () => {
    expect(received).toHaveLength(2);
    expect(received.map(p => p.name)).toContain('Widget');
    done();
  });
  stream.on('error', done);
});

Mocking a gRPC Client (When Your Code Calls gRPC)

When testing code that uses a gRPC client, mock the client object.

// order-service.js — calls ProductService via gRPC
class OrderService {
  constructor(productClient) {
    this.productClient = productClient;
  }
  
  async createOrder(productId, quantity) {
    const product = await new Promise((resolve, reject) => {
      this.productClient.getProduct({ product_id: productId }, (err, res) => {
        if (err) reject(err);
        else resolve(res);
      });
    });
    
    return {
      productId,
      productName: product.name,
      quantity,
      total: product.price * quantity
    };
  }
}
// order-service.test.js
test('createOrder calculates total from product price', async () => {
  const mockProductClient = {
    getProduct: jest.fn((request, callback) => {
      callback(null, { id: 'p1', name: 'Widget', price: 9.99, category: 'tools' });
    })
  };
  
  const orderService = new OrderService(mockProductClient);
  const order = await orderService.createOrder('p1', 3);
  
  expect(order.total).toBeCloseTo(29.97);
  expect(order.productName).toBe('Widget');
});

test('createOrder propagates gRPC NOT_FOUND error', async () => {
  const notFoundError = Object.assign(new Error('Product not found'), {
    code: grpc.status.NOT_FOUND
  });
  
  const mockProductClient = {
    getProduct: jest.fn((request, callback) => {
      callback(notFoundError, null);
    })
  };
  
  const orderService = new OrderService(mockProductClient);
  
  await expect(orderService.createOrder('p999', 1))
    .rejects.toMatchObject({ code: grpc.status.NOT_FOUND });
});

The mock client pattern is the same as any dependency injection — pass a fake object that controls what the callback receives. No network, no server, just the gRPC response your test needs.

Read more

Start now free