/grpc-web-compatibility-test

Test various implementations of gRPC-Web Clients with various implementations of gRPC-Web proxies

Primary LanguageJavaScriptMIT LicenseMIT

grpc-web-compatibility-test

CircleCI

This repository has been superceded by the official grpc-web interop tests, which can be found here.

Test various implementations of gRPC-Web Clients with various implementations of gRPC-Web proxies.

Definitions

Clients

Non-gRPC-Web clients tested

Proxies

Note: The websocket transport is not part of the gRPC-Web spec.

Requirements

docker, docker-compose.

Running

  1. Start the server implementation of your choice (envoy, grpcwebproxy, inprocess, grpcwsgi)
    $ docker-compose up -d grpcwebproxy
  2. Run the frontend tests of your choice (improbable, improbableWS, grpcWeb, grpcWebtext). Use the name of the chosen proxy in the grpc-host flag.
    $ docker-compose run frontend karma:improbable --grpc-host=http://grpcwebproxy:8080

Note: The inprocess and grpcwsgi proxies do not require echo-server to be running, they include the server themselves. envoy and grpcwebproxy will automatically start the echo-server container on up.

Proxy/Client compatbility status

Proxy / Client improbable grpcWeb grpcWebText improbableWS [1]
akkagrpc ✔️ ✔️️ ✔️
envoy ✔️ ✔️️ ✔️
grpcwebproxy ✔️️ ✔️ ✔️ ✔️️
inprocess ✔️️ ✔️ ✔️ ✔️️
grpcwsgi
  1. improbable-ws implements a non-standard websocket transport.

Client capability matrix

Client / Feature application/grpc-web application/grpc-web-text Unary Server Streams Client+Bidi streaming
improbable ✔️ ️ ✔️ ✔️
grpcWeb ✔️ ️ ✔️ ❌ [1]
grpcWebText ❌ ️ ✔️️ ✔️ ✔️
improbableWS [2] ✔️ ️ ✔️ ✔️ ✔️️
grpcwsgi ✔️ ️ ✔️ ✔️
  1. grpcWeb allows server streaming methods to be called, but it doesn't return data until the stream has closed. (issue)
  2. improbable-ws implements a non-standard websocket transport for client-side and bi-directional streams.

Building

Most of the build is managed by docker-compose but you may also want to manually rebuild some other things sometimes. Makefile commands are provided for building the protobuf bindings for all implementations and for rebuilding the Envoy container used in CI as this needs additional configuration.

To rebuild the protobuf bindings just run make generate and commit the new bindings. You will probably only need to do this when adding a new implementation.

To rebuild the Envoy CI image, run make envoy-circle-image. If you happen to be a contributor you'll also be able to do docker push public/grpcweb-testing-envoy:latest to push the new image to Docker Hub.

Running tests in your local browser

Requirements

node, npm.

Installation

Install the test suit locally:

$ cd frontend && npm install .

Running

Start the proxy and server of your choice:

$ docker-compose up -d grpcwebproxy

This will give you a server listening on port 8080 on localhost.

The tests are run from the frontend folder. Run the test of your choice via npx:

$ npx grunt karma:grpcWebText --grpc-host=http://localhost:8080

This will launch a headless Chrome instance and start running the tests in it. Look in the terminal you launched the tests from to see if the tests passed.

To run the tests in a visual browser, edit the browsers part of the karma config to Chrome.

If you want to debug the tests, you can open the debug tab in the karma page in Chrome and then use your browser devtools to poke around.

Running with other browsers

Install the karma launcher for the browser you want e.g. for Firefox:

$ npm install karma-firefox-launcher

Change the browsers config to Firefox and run the tests again:

$ npx grunt karma:grpcWebText --grpc-host=http://localhost:8080