{"id":43740396,"url":"https://github.com/ascii8/nktest","last_synced_at":"2026-02-05T11:32:44.229Z","repository":{"id":50398644,"uuid":"517279275","full_name":"ascii8/nktest","owner":"ascii8","description":"Nakama test runner for Go","archived":false,"fork":false,"pushed_at":"2024-01-27T00:11:36.000Z","size":672,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-01-28T00:36:40.757Z","etag":null,"topics":["go","golang","nakama","nakama-server","testing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ascii8.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-07-24T09:26:17.000Z","updated_at":"2022-12-22T18:48:29.000Z","dependencies_parsed_at":"2024-01-27T00:33:12.135Z","dependency_job_id":"d4c33375-d563-4e9e-b945-260a4924610f","html_url":"https://github.com/ascii8/nktest","commit_stats":null,"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"purl":"pkg:github/ascii8/nktest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ascii8%2Fnktest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ascii8%2Fnktest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ascii8%2Fnktest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ascii8%2Fnktest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ascii8","download_url":"https://codeload.github.com/ascii8/nktest/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ascii8%2Fnktest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29120635,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T10:47:47.471Z","status":"ssl_error","status_checked_at":"2026-02-05T10:45:08.119Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","nakama","nakama-server","testing"],"created_at":"2026-02-05T11:32:43.153Z","updated_at":"2026-02-05T11:32:44.224Z","avatar_url":"https://github.com/ascii8.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# About\n\nPackage `nktest` provides a Nakama test runner that makes it easy to build and\ntest [Nakama module plugins](https://github.com/heroiclabs/nakama) with complex\nor advanced game logic using nothing but `go test`.\n\nSee also [`github.com/ascii8/nakama-go`](https://github.com/ascii8/nakama-go)\npackage for a web/realtime Nakama Go client.\n\n[![Tests](https://github.com/ascii8/nktest/workflows/Test/badge.svg)](https://github.com/ascii8/nktest/actions?query=workflow%3ATest)\n[![Go Report Card](https://goreportcard.com/badge/github.com/ascii8/nktest)](https://goreportcard.com/report/github.com/ascii8/nktest)\n[![Reference](https://pkg.go.dev/badge/github.com/ascii8/nktest\n[![Releases](https://img.shields.io/github/v/release/ascii8/nktest?display_name=tag\u0026sort=semver)](https://github.com/ascii8/nktest/releases)\n\n## Overview\n\nThis package uses [Podman](https://podman.io) to create \"rootless\" containers\n(specifically, [`docker.io/heroiclabs/nakama-pluginbuilder`](https://hub.docker.com/r/heroiclabs/nakama-pluginbuilder)\nand [`docker.io/heroiclabs/nakama`](https://hub.docker.com/r/heroiclabs)) to\nbuild Nakama's Go plugins and launch the necessary server components (PostgreSQL\nand Nakama).\n\nProvides a stable, repeatable, and quick mechanism for launching testable\nend-to-end Nakama servers for game modules (Go, Lua, or Javascript).\n\nProvides additional transport and logger types for use with Go clients to\nreadily aid in debugging Nakama's API calls.\n\n## Quickstart\n\nAdd to package/module:\n\n```go\ngo get github.com/ascii8/nktest\n```\n\nFrom Go's [`TestMain`](https://pkg.go.dev/testing#hdr-Main), use\n[`nktest.Main`](https://pkg.go.dev/github.com/ascii8/nktest#Main) to build Go\nmodules, and to setup/teardown PostgreSQL and Nakama server containers:\n\n```go\nimport \"github.com/ascii8/nktest\"\n\n// TestMain handles setting up and tearing down the postgres and nakama\n// containers.\nfunc TestMain(m *testing.M) {\n\tctx := context.Background()\n\tctx = nktest.WithAlwaysPullFromEnv(ctx, \"PULL\")\n\tctx = nktest.WithHostPortMap(ctx)\n\tnktest.Main(ctx, m,\n\t\tnktest.WithDir(\"./testdata\"),\n\t\tnktest.WithBuildConfig(\"./nksample\", nktest.WithDefaultGoEnv(), nktest.WithDefaultGoVolumes()),\n\t)\n}\n```\n\nThen, from within a `Test*` func, create a cancelable test context, and a\nproxy:\n\n```go\nimport \"github.com/ascii8/nktest\"\n\nfunc TestNakamaHealthcheck(t *testing.T) {\n\tctx, cancel, nk := nktest.WithCancel(context.Background(), t)\n\tdefer cancel()\n\turlstr, err := nktest.RunProxy(ctx)\n\tif err != nil {\n\t\tt.Fatalf(\"expected no error, got: %v\", err)\n\t}\n\tt.Logf(\"proxy: %s\", urlstr)\n\treq, err := http.NewRequestWithContext(ctx, \"GET\", urlstr+\"/healthcheck\", nil)\n\tif err != nil {\n\t\tt.Fatalf(\"expected no error, got: %v\", err)\n\t}\n\t// create a client with compression disabled (makes debugging the API\n\t// requests/responses easier)\n\tcl := \u0026http.Client{\n\t\tTransport: \u0026http.Transport{\n\t\t\tDisableCompression: true,\n\t\t},\n\t}\n\t// execute the request\n\tres, err := cl.Do(req)\n\tif err != nil {\n\t\tt.Fatalf(\"expected no error, got: %v\", err)\n\t}\n\tdefer res.Body.Close()\n\t// check response\n\tif res.StatusCode != http.StatusOK {\n\t\tt.Errorf(\"expected %d, got: %d\", http.StatusOK, res.StatusCode)\n\t}\n\tt.Logf(\"healthcheck status: %d\", res.StatusCode)\n\t// display connection information\n\tt.Logf(\"grpc: %s\", nk.GrpcLocal())\n\tt.Logf(\"http: %s\", nk.HttpLocal())\n\tt.Logf(\"console: %s\", nk.ConsoleLocal())\n\tt.Logf(\"http_key: %s\", nk.HttpKey())\n\tt.Logf(\"server_key: %s\", nk.ServerKey())\n}\n```\n\nUse the [`WithHostPortMap()` option](https://pkg.go.dev/github.com/ascii8/nktest#WithHostPortMap),\nto publish the Postgres and Nakama server's default ports on the host, and [making\nit easy to write `Example*` tests](example_test.go).\n\nFor more advanced testing scenarios, [see the `github.com/ascii8/nakama-go`\npackage](https://github.com/ascii8/nakama-go) for a full featured Go Nakama\nclient.\n\n## Examples\n\n* Testing (`nakama-go` package) - [github.com/ascii8/nakama-go/example_test.go](https://github.com/ascii8/nakama-go/blob/master/example_test.go)\n* Testing (this package) - [nktest_test.go](nktest_test.go)\n* CI/CD example (GitHub Actions, this repository) - [test.yml](.github/workflows/test.yml)\n* Go client for Nakama (usable with `GOOS=js GOOS=wasm`) - [`github.com/ascii8/nakama-go`](https://github.com/ascii8/nakama-go)\n* Pure Go implementation of Nakama's XOXO example - [github.com/ascii8/xoxo-go](https://github.com/ascii8/xoxo-go)\n\nSee the [Go package documentation](https://pkg.go.dev/github.com/ascii8/nktest)\nfor package level examples.\n\n## Why\n\nWhile Nakama provides a number of different languages with which to build out\ngame modules, building large-scale, complex logic for Nakama is best done using\nGo. For experienced (and even inexperienced!) Go developers, the `go test`\ncommand is simple, efficient and well understood, and works across platforms.\n\nAnd, for fully automated deployments of Nakama and game modules, a large amount\nof quick and reliable testing is needed to ensure rapid application development,\nand continuous integration/deployment (CI/CD).\n\nAs such, there was clear motivation to make it easy and repeatable to test\nentirely from `go test`,\n\n### Why Podman\n\nThe first version of `nktest` used Docker, but builds and tests were slow as it\nwas not possible to mount the user's Go build/mod cache directories without\nstomping on the local UID/GID and subsequently affecting the read/write\npermissions. Thus the change to Podman, which is able to run containers without\nroot permissions, and can keep user UID/GID's on files.\n\n## Notes\n\nmacOS:\n\n```sh\n# update homebrew formulas and upgrade packages\nbrew update \u0026\u0026 brew upgrade\n\n# install podman\nbrew install podman\n\n# install gpgme (needed for podman's Go binding dependenices)\nbrew install gpgme\n\n# if unable to do `go test -v` out of the box, re-init the podman machine\npodman machine stop podman-machine-default\npodman machine rm podman-machine-default\npodman machine init -v $HOME:$HOME\npodman machine start\n\n# if receiving a \"too many open files\" error on M1 macs, try:\npodman machine stop \u0026\u0026 ulimit -n unlimited \u0026\u0026 podman machine start\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fascii8%2Fnktest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fascii8%2Fnktest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fascii8%2Fnktest/lists"}