Blog

Introducing grpcmd-script: Powerful gRPC Testing with JavaScript

Aug 4, 2024

Introduction

I’m excited to announce the release of grpcmd-script! grpcmd-script provides a powerful framework allowing you to easily test your gRPC endpoints using JavaScript from the command line.

Key Features

1. JavaScript testing

grpcmd-script offers you the flexibility of crafting your tests in the JavaScript language. You are able to define all the parameters of the gRPC request and make test assertions on all the gRPC response fields such as the headers, data messages, and trailers. In addition, you can import and make use of the chai assertion library.

2. One binary; no dependencies

You only need two files to perform tests: the grpcmd-script executable and a test suite in JavaScript. The grpcmd-script executable is natively available for multiple platforms (macOS, Windows, and Linux) and architectures (386, amd64, and arm64), has a size of only 20MB, and doesn’t require any external dependency like the Node.js JavaScript runtime.

Because of this, grpcmd-script can run almost anywhere and provide powerful flexibility with JavaScript while consuming minimal resources.

3. Powered by grpcmd

Internally, the gRPC calls are executed using the same code as the open-source grpcmd project.

Quick Demonstation

First, create a file to contain your test suite, such as tests.js. Then, within the file:

1. Import functions from the chai assertion library as well as our helper library:

   const { expect } = require('chai');
   const { call, test, runTests } = require('grpcmd-script/test');

2. Define your tests containing gRPC requests and response assertions:

   test('UnaryMethod', () => {
       const res = call({
           address: 'localhost:50051',
           method: 'UnaryMethod',
           messages: [
               {
                   name: 'Bob'
               }
           ]
       });
   
       expect(res.messages).to.have.length(1);
       expect(res.messages).to.deep.equal([
           {
               message: 'Hello, Bob!'
           }
       ]);
       expect(res.trailers).to.include({
           'status-code': '0'
       });
   });

3. Finally, run all the tests:

   runTests();

$

grpc-script ./tests.js

┌──────────┬────────┬────────┬───────┬─────────┬──────┐
│   File   │ Failed │ Passed │ Total │ Percent │ Time │
├──────────┼────────┼────────┼───────┼─────────┼──────┤
│ tests.js │      0 │      1 │     1 │ 100.00% │ 25ms │
└──────────┴────────┴────────┴───────┴─────────┴──────┘

Errors

In case of any errors, the assertion details will be printed along with any console output.

$

grpc-script ./tests.js

✕ UnaryMethod

    AssertionError: expected { ‘status-code’: ‘0’ } to have property ‘status-code’ of ‘1’, but got ‘0’  
       ├──at tests.js:21:36(48)
       └──at tests.js:26:9(29)

console.log output for debugging

┌──────────┬────────┬────────┬───────┬─────────┬──────┐
│   File   │ Failed │ Passed │ Total │ Percent │ Time │
├──────────┼────────┼────────┼───────┼─────────┼──────┤
│ tests.js │      1 │      0 │     1 │   0.00% │ 25ms │
└──────────┴────────┴────────┴───────┴─────────┴──────┘

Conclusion

I’m looking forward to seeing the different use cases being served from this product. grpcmd-script is now available for purchase at this checkout link. Stay tuned for more!