grpc-mocky

library0.1.31jsnpmunverified

grpc-mocky is a JavaScript library for creating mock gRPC servers during development and testing. Version 0.1.31 supports unary, server streaming, client streaming, and duplex streaming methods. It provides a CLI tool to generate mock templates from .proto files and offers a programmatic API to start a mock server with configurable address and port. Ships TypeScript definitions. Key differentiator: lightweight, focused on mocking without requiring full gRPC server setup. Ideal for integration testing and frontend development with gRPC-web.

testing

npm install grpc-mocky

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPC-MOCKY

grpc-mocky

testingjavascriptv0.1.31

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

run

✓ import { run } from 'grpc-mocky'

✗ import run from 'grpc-mocky'

Named export, not default. Use curly braces for import.

run

✓ const { run } = require('grpc-mocky')

✗ const run = require('grpc-mocky')

CommonJS destructure required; the default export is a non-function object.

service types

✓ import type { Proto, Service } from 'grpc-mocky'

TypeScript users can import Proto and Service interfaces for type-safe mock definitions. Available since v0.1.20.

Starts a mock gRPC server on port 50051 with a single unary method and a server-streaming method defined from a .proto file.

// Example: start a mock gRPC server with a single proto file import { run } from 'grpc-mocky'; const protos = [ { path: './helloworld.proto', pkg: 'helloworld', services: [ { name: 'Greeter', methods: [ { name: 'SayHello', output: { message: 'Hello, World!' } }, { name: 'SayHelloStream', output: [{ message: 'Hi' }, { message: 'Bye' }] } ] } ] } ]; run({ address: '0.0.0.0', port: '50051', protos }); console.log('Mock server running on port 50051');

Debug

Known issues

gotchaMethod names in mock config must exactly match proto definition (case-sensitive). A typo causes runtime failure.

fix

Verify method names in mock JSON match the proto file method names exactly.

affects: >=0.1.0

gotchaServer address defaults to '0.0.0.0' if omitted, which listens on all interfaces. This can be a security concern in production-like environments.

fix

Specify an explicit address like '127.0.0.1' for local-only mocking.

affects: >=0.1.0

deprecatedThe 'options' field in proto config is deprecated and will be removed in future versions. Use proto-loader options directly via 'protoOptions'.

fix

Use 'protoOptions' field instead of 'options' when passing loader options.

affects: >=0.1.25

gotchaOutput for server-streaming and duplex-streaming must be an array of messages; providing a single object causes streaming to complete immediately.

fix

Wrap single output in an array: [{ message: 'hello' }] instead of { message: 'hello' }.

affects: <0.1.30

Errors

Common errors & fixes

Error: Cannot find module '@grpc/grpc-js'

Missing runtime dependency; automatic install may not include peer dependencies.

fix

Install peer dependencies manually: npm install @grpc/grpc-js @grpc/proto-loader

TypeError: Cannot read properties of undefined (reading 'methods')

The 'services' array is empty or missing in the proto config.

fix

Ensure each proto object has a 'services' array with at least one service definition containing a 'methods' array.

Error: EADDRINUSE: address already in use :::50051

Port 50051 is already occupied by another process (e.g., another mock server).

fix

Choose a different port: run({ port: '50052' }) or kill the process using port 50051.

Upgrade

Version history

0.1.31latest on npm

Audit

Dependencies

@grpc/grpc-jsrequiredCore gRPC implementation used for server creation

@grpc/proto-loaderrequiredLoads .proto files to create gRPC service definitions

protobufjsrequiredUsed internally for protobuf serialization/deserialization

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/activeguild/grpc-mocky ↗

packagegrpc-mocky ↗

homepagehttps://github.com/activeguild/grpc-mocky/blob/master/README.md ↗