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 jestGiven 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.