k6/net/grpc

gRPC client for testing gRPC services.

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