About
Package nktest
provides a Nakama test runner that makes it easy to build and
test Nakama module plugins with complex
or advanced game logic using nothing but go test
.
See also github.com/ascii8/nakama-go
package for a web/realtime Nakama Go client.
[![Reference](https://pkg.go.dev/badge/github.com/ascii8/nktest
Overview
This package uses Podman to create "rootless" containers
(specifically, docker.io/heroiclabs/nakama-pluginbuilder
and docker.io/heroiclabs/nakama
) to
build Nakama's Go plugins and launch the necessary server components (PostgreSQL
and Nakama).
Provides a stable, repeatable, and quick mechanism for launching testable
end-to-end Nakama servers for game modules (Go, Lua, or Javascript).
Provides additional transport and logger types for use with Go clients to
readily aid in debugging Nakama's API calls.
Quickstart
Add to package/module:
go get github.com/ascii8/nktest
From Go's TestMain
, use
nktest.Main
to build Go
modules, and to setup/teardown PostgreSQL and Nakama server containers:
import "github.com/ascii8/nktest"
func TestMain(m *testing.M) {
ctx := context.Background()
ctx = nktest.WithAlwaysPullFromEnv(ctx, "PULL")
ctx = nktest.WithHostPortMap(ctx)
nktest.Main(ctx, m,
nktest.WithDir("./testdata"),
nktest.WithBuildConfig("./nksample", nktest.WithDefaultGoEnv(), nktest.WithDefaultGoVolumes()),
)
}
Then, from within a Test*
func, create a cancelable test context, and a
proxy:
import "github.com/ascii8/nktest"
func TestNakamaHealthcheck(t *testing.T) {
ctx, cancel, nk := nktest.WithCancel(context.Background(), t)
defer cancel()
urlstr, err := nktest.RunProxy(ctx)
if err != nil {
t.Fatalf("expected no error, got: %v", err)
}
t.Logf("proxy: %s", urlstr)
req, err := http.NewRequestWithContext(ctx, "GET", urlstr+"/healthcheck", nil)
if err != nil {
t.Fatalf("expected no error, got: %v", err)
}
cl := &http.Client{
Transport: &http.Transport{
DisableCompression: true,
},
}
res, err := cl.Do(req)
if err != nil {
t.Fatalf("expected no error, got: %v", err)
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
t.Errorf("expected %d, got: %d", http.StatusOK, res.StatusCode)
}
t.Logf("healthcheck status: %d", res.StatusCode)
t.Logf("grpc: %s", nk.GrpcLocal())
t.Logf("http: %s", nk.HttpLocal())
t.Logf("console: %s", nk.ConsoleLocal())
t.Logf("http_key: %s", nk.HttpKey())
t.Logf("server_key: %s", nk.ServerKey())
}
Use the WithHostPortMap()
option,
to publish the Postgres and Nakama server's default ports on the host, and making
it easy to write Example*
tests.
For more advanced testing scenarios, see the github.com/ascii8/nakama-go
package for a full featured Go Nakama
client.
Examples
See the Go package documentation
for package level examples.
Why
While Nakama provides a number of different languages with which to build out
game modules, building large-scale, complex logic for Nakama is best done using
Go. For experienced (and even inexperienced!) Go developers, the go test
command is simple, efficient and well understood, and works across platforms.
And, for fully automated deployments of Nakama and game modules, a large amount
of quick and reliable testing is needed to ensure rapid application development,
and continuous integration/deployment (CI/CD).
As such, there was clear motivation to make it easy and repeatable to test
entirely from go test
,
Why Podman
The first version of nktest
used Docker, but builds and tests were slow as it
was not possible to mount the user's Go build/mod cache directories without
stomping on the local UID/GID and subsequently affecting the read/write
permissions. Thus the change to Podman, which is able to run containers without
root permissions, and can keep user UID/GID's on files.
Notes
macOS:
brew update && brew upgrade
brew install podman
brew install gpgme
podman machine stop podman-machine-default
podman machine rm podman-machine-default
podman machine init -v $HOME:$HOME
podman machine start
podman machine stop && ulimit -n unlimited && podman machine start