Skip to main content
The k6/net/grpc module provides a gRPC client for testing gRPC services.

​
Client

The Client class is used to interact with gRPC services.

​
Constructor

import grpc from 'k6/net/grpc';

const client = new grpc.Client();

​
Methods

​
load(importPaths, …protoFiles)

Loads protocol buffer definitions from proto files.
​
importPaths
array
Array of import paths for proto files
​
protoFiles
...string
Proto file paths to load
import grpc from 'k6/net/grpc';

const client = new grpc.Client();
client.load(['./protos'], 'service.proto');
The load() method must be called in the init context.

​
loadProtoset(protosetPath)

Loads a compiled protoset file.
​
protosetPath
string
Path to the protoset file
client.loadProtoset('service.protoset');

​
connect(address, [params])

Connects to a gRPC server.
​
address
string
Server address (host:port)
​
params
object
Connection parameters
​
result
boolean
Returns true on successful connection
import grpc from 'k6/net/grpc';

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

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

​
Connection Parameters

​
plaintext
boolean
default:false
Use plaintext connection (no TLS)
​
timeout
string
default:"60s"
Connection timeout
​
maxReceiveSize
number
Maximum message size to receive (bytes)
​
maxSendSize
number
Maximum message size to send (bytes)
​
tls
object
TLS configuration
​
reflect
boolean
Use server reflection protocol
​
authority
string
Override the :authority pseudo-header

​
invoke(method, request, [params])

Invokes a unary gRPC method.
​
method
string
Fully qualified method name (e.g., “package.Service/Method”)
​
request
object
Request message object
​
params
object
Request parameters
​
response
object
Response object containing status, message, headers, and trailers
const response = client.invoke('main.RouteGuide/GetFeature', {
  latitude: 409146138,
  longitude: -746188906,
});

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

​
Response Object

​
status
number
gRPC status code
​
message
object
Response message
​
headers
object
Response headers metadata
​
trailers
object
Response trailers metadata
​
error
object
Error information if request failed

​
asyncInvoke(method, request, [params])

Invokes a unary gRPC method asynchronously.
​
method
string
Fully qualified method name
​
request
object
Request message object
​
params
object
Request parameters
​
promise
Promise
Promise that resolves with the response
const promise = client.asyncInvoke('main.RouteGuide/GetFeature', {
  latitude: 409146138,
  longitude: -746188906,
});

promise.then(response => {
  console.log(JSON.stringify(response.message));
});

​
close()

Closes the gRPC connection. 
client.close();

​
Constants

​
Status Codes

  • grpc.StatusOK - 0
  • grpc.StatusCanceled - 1
  • grpc.StatusUnknown - 2
  • grpc.StatusInvalidArgument - 3
  • grpc.StatusDeadlineExceeded - 4
  • grpc.StatusNotFound - 5
  • grpc.StatusAlreadyExists - 6
  • grpc.StatusPermissionDenied - 7
  • grpc.StatusResourceExhausted - 8
  • grpc.StatusFailedPrecondition - 9
  • grpc.StatusAborted - 10
  • grpc.StatusOutOfRange - 11
  • grpc.StatusUnimplemented - 12
  • grpc.StatusInternal - 13
  • grpc.StatusUnavailable - 14
  • grpc.StatusDataLoss - 15
  • grpc.StatusUnauthenticated - 16

​
Examples

​
Basic gRPC Test

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

const GRPC_ADDR = '127.0.0.1:10000';
const GRPC_PROTO_PATH = './proto/route_guide.proto';

let client = new grpc.Client();
client.load([], GRPC_PROTO_PATH);

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

  const response = client.invoke('main.FeatureExplorer/GetFeature', {
    latitude: 410248224,
    longitude: -747127767,
  });

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

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

  client.close();
};

​
With TLS

import grpc from 'k6/net/grpc';

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

export default () => {
  client.connect('api.example.com:443', {
    tls: {
      cert: open('./client.crt'),
      key: open('./client.key'),
      cacerts: [open('./ca.crt')],
    },
  });

  const response = client.invoke('service.MyService/MyMethod', {
    field: 'value',
  });

  console.log(response.message);
  client.close();
};

​
With Metadata

import grpc from 'k6/net/grpc';

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

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

  const params = {
    metadata: {
      'authorization': 'Bearer token123',
      'x-custom-header': 'value',
    },
    timeout: '10s',
  };

  const response = client.invoke('service.MyService/MyMethod', 
    { field: 'value' },
    params
  );

  console.log(response.message);
  client.close();
};

​
Server Reflection

import grpc from 'k6/net/grpc';

const client = new grpc.Client();

export default () => {
  // Use server reflection to discover services
  client.connect('localhost:50051', {
    plaintext: true,
    reflect: true,
  });

  const response = client.invoke('service.MyService/MyMethod', {
    field: 'value',
  });

  console.log(response.message);
  client.close();
};
gRPC connections cannot be used in the init context. Connect to the server in the VU context (default function).

Build docs developers (and LLMs) love

Get started for freeTalk to us