tck

README

http-wasm technology compatibility kit (TCK)

The TCK is a test suite for checking conformance of http-wasm implementations versus the http-wasm ABI specification.

It consists of a guest Wasm binary and a test runner which issues HTTP requests to a given endpoint. The requests drive different test cases implemented in the Wasm binary, and the runner verifies that the resulting response from the endpoint matches expectations for that binary.

Running the TCK

The TCK is implemented using Go's standard testing framework, so it can be loaded as a package for Go hosts. A TCK standalone runner is also provided for use with Non-Go hosts, or Go hosts that would like to run the TCK outside the standard testing framework.

The basic steps for running the TCK are

1. Implement the backend handler, which is the business logic wrapped by middleware
2. Set up the middleware using the TCK guest Wasm module
3. Start an HTTP server serving this middleware
4. Run the tests, pointing at the URL for the HTTP server

The general flow of the HTTP request looks like the follows. Depending on the test case, the guest Wasm may or may not pass the request to the backend.

graph LR;
    A[TCK Runner] --> B[TCK Guest Wasm]
    B[TCK Guest Wasm] -.-> C[Backend]

We provide an implementation of the backend handler using the Go http.Handler interface, tck.BackendHandler.

If the Go host uses http.Handler or types that can be easily coerced to it, it can be simplest to initialize this handler directly as the backend being wrapped by the middleware.

It is also possible to use tck.StartBackend to start an HTTP server using this backend handler. This is often the easiest method for proxy servers.

Otherwise, it may be simplest to reimplement the logic in the backend handler using the Go host's framework, following the logic in BackendHandler.

The binary for the guest wasm module is provided as tck.GuestWASM.

With the HTTP server started and serving the middleware and backend, the tests can be run using tck.Run.

TestTCK demonstrates a full example for the net/http middleware provided in this repository.

Documentation

Index

• Variables
• func BackendHandler() http.Handler
• func Run(t *testing.T, client *http.Client, url string)
• func StartBackend(addr string) *httptest.Server

Variables

var GuestWASM []byte

GuestWASM is the guest wasm module used by the TCK. The host must load this module in the server being tested by Run.

Functions

func BackendHandler

func BackendHandler() http.Handler

BackendHandler is a http.Handler implementing the logic expected by the TCK. It serves to echo back information from the request to the response for checking expectations.

func Run

func Run(t *testing.T, client *http.Client, url string)

Run executes the TCK. The client is http.DefaultClient, or a different value to test the HTTP/2.0 transport. The url must point to a server with the TCK's guest wasm module loaded on top of the TCK's backend handler.

For example, here's how to run the tests against a httptest.Server.

server := httptest.NewServer(h)
tck.Run(t, server.Client(), server.URL)

func StartBackend

func StartBackend(addr string) *httptest.Server

StartBackend starts a httptest.Server at the given address implementing BackendHandler.