k6/net/grpc

gRPC client for making Remote Procedure Calls over HTTP/2

The k6/net/grpc module provides a gRPC client for making Remote Procedure Calls (RPC) over HTTP/2.

Overview

Use this module to test gRPC services by making unary and streaming RPC calls. The module supports loading protocol buffer definitions, establishing connections, and invoking RPC methods with full support for metadata and parameters.

Importing the Module

import grpc from 'k6/net/grpc';

API Reference

Client Class

new grpc.Client() · constructor

Creates a new gRPC client for making RPC calls to a gRPC server.

Client Methods

Client.load(importPaths, ...protoFiles) · function

Loads and parses protocol buffer definitions to be made available for RPC requests.

Parameters:

importPaths · string | string[]

Paths to search for imported proto files. Use null to load from current directory.

protoFiles · ...string · required

One or more proto file paths to load

Client.connect(address, params) · function

Connects to a gRPC service.

Parameters:

address · string · required

Server address (e.g., grpc.example.com:443)

params · Params

Connection parameters (TLS, credentials, timeout, etc.)

Client.invoke(url, request, params) · function

Makes a unary RPC call for the given service/method.

Parameters:

url · string · required

RPC method in format package.Service/Method

request · object · required

Request message object matching the proto definition

params · Params

Request-specific parameters (metadata, tags, timeout)

Returns:

response · Response

gRPC response object

Client.asyncInvoke(url, request, params) · function

Asynchronously makes a unary RPC call for the given service/method.

Parameters:

url · string · required

RPC method in format package.Service/Method

request · object · required

Request message object matching the proto definition

params · Params

Request-specific parameters

Returns:

promise · Promise<Response>

Promise that resolves to a gRPC Response

Client.close() · function

Closes the connection to the gRPC service.

Response Object

status · number

gRPC status code (see Constants below)

message · object

Response message from the server

headers · object

Response headers/metadata

trailers · object

Response trailers/metadata

error · object

Error information if the call failed

Params Object

metadata · object

Custom metadata to send with the request as key-value pairs.

tags · object

Custom metric tags for filtering results and setting thresholds.

timeout · string

Request timeout (e.g., "10s", "500ms")

plaintext · boolean

Use plaintext connection (no TLS). Default: false

Status Constants

The module provides constants to distinguish between gRPC response statuses:

Constant	Description
StatusOK	Success
StatusCanceled	Operation canceled (typically by caller)
StatusUnknown	Unknown error
StatusInvalidArgument	Client specified invalid argument
StatusDeadlineExceeded	Operation expired before completion
StatusNotFound	Requested entity not found
StatusAlreadyExists	Entity already exists
StatusPermissionDenied	Caller lacks permission
StatusResourceExhausted	Resource exhausted (quota, space, etc.)
StatusFailedPrecondition	System not in required state
StatusAborted	Operation aborted (concurrency issue)
StatusOutOfRange	Operation past valid range
StatusUnimplemented	Operation not implemented or supported
StatusInternal	Internal errors
StatusUnavailable	Service currently unavailable (transient)
StatusDataLoss	Unrecoverable data loss or corruption
StatusUnauthenticated	Request lacks valid authentication

Stream Support

For bidirectional and streaming RPCs:

new grpc.Stream(client, url, params) · constructor

Creates a new gRPC stream for bidirectional or streaming calls.

Stream.on(event, handler) · function

Adds an event listener for stream events: data, error, end

Stream.write(message) · function

Writes a message to the stream.

Stream.end() · function

Signals to the server that the client has finished sending.

gRPC Metrics

k6 automatically collects gRPC-specific metrics:

Metric	Type	Description
grpc_req_duration	Trend	Total request duration
grpc_streams	Counter	Total number of streams
grpc_streams_msgs_sent	Counter	Messages sent
grpc_streams_msgs_received	Counter	Messages received

Examples

Basic Unary RPC

Simple Unary Call

import grpc from 'k6/net/grpc';
import { check, sleep } from 'k6';

const client = new grpc.Client();
client.load(null, 'quickpizza.proto');

export default () => {
  client.connect('grpc-quickpizza.grafana.com:443', {
    // plaintext: false
  });

  const data = { ingredients: ['Cheese'], dough: 'Thick' };
  const response = client.invoke('quickpizza.GRPC/RatePizza', data);

  check(response, {
    'status is OK': (r) => r && r.status === grpc.StatusOK,
  });

  console.log(JSON.stringify(response.message));

  client.close();
  sleep(1);
};

import grpc from 'k6/net/grpc';
import { check } from 'k6';

const client = new grpc.Client();
client.load(['./protos'], 'service.proto');

export default () => {
  client.connect('localhost:50051', { plaintext: true });

  const params = {
    metadata: {
      'x-client-id': 'k6-test',
      'authorization': 'Bearer token123',
    },
    tags: { rpc_type: 'unary' },
  };

  const response = client.invoke(
    'mypackage.MyService/MyMethod',
    { name: 'k6' },
    params
  );

  check(response, {
    'status is OK': (r) => r.status === grpc.StatusOK,
    'response has data': (r) => r.message && r.message.result,
  });

  client.close();
};

Async Invocation

import grpc from 'k6/net/grpc';
import { check } from 'k6';

const client = new grpc.Client();
client.load(null, 'service.proto');

export default async () => {
  client.connect('grpc.example.com:443');

  // Make multiple concurrent requests
  const promises = [
    client.asyncInvoke('service.API/Method1', { id: 1 }),
    client.asyncInvoke('service.API/Method2', { id: 2 }),
    client.asyncInvoke('service.API/Method3', { id: 3 }),
  ];

  const responses = await Promise.all(promises);

  responses.forEach((response, i) => {
    check(response, {
      [`request ${i} status is OK`]: (r) => r.status === grpc.StatusOK,
    });
  });

  client.close();
};

Streaming RPC

import grpc from 'k6/net/grpc';

const client = new grpc.Client();
client.load(null, 'service.proto');

export default () => {
  client.connect('localhost:50051', { plaintext: true });

  const stream = new grpc.Stream(client, 'service.API/BiDiStream');

  stream.on('data', (message) => {
    console.log('Received:', JSON.stringify(message));
  });

  stream.on('error', (err) => {
    console.error('Stream error:', err);
  });

  stream.on('end', () => {
    console.log('Stream ended');
    client.close();
  });

  // Send messages
  stream.write({ message: 'Hello' });
  stream.write({ message: 'World' });
  
  // Signal we're done sending
  stream.end();
};

Status Code Checking

import grpc from 'k6/net/grpc';
import { check } from 'k6';

const client = new grpc.Client();
client.load(null, 'service.proto');

export default () => {
  client.connect('grpc.example.com:443');

  const response = client.invoke('service.API/GetUser', { id: 'invalid' });

  check(response, {
    'status is OK': (r) => r.status === grpc.StatusOK,
    'status is NOT_FOUND': (r) => r.status === grpc.StatusNotFound,
    'status is INVALID_ARGUMENT': (r) => r.status === grpc.StatusInvalidArgument,
  });

  if (response.status !== grpc.StatusOK) {
    console.error(`gRPC error: ${response.error.message}`);
  }

  client.close();
};

Related Resources

Response Object

gRPC response structure

Stream

Streaming RPC support

gRPC Testing Guide

Learn gRPC testing patterns

Protocol Buffers

Protocol buffer documentation