{"id":23127703,"url":"https://github.com/hlfshell/docker-harness","last_synced_at":"2026-03-07T20:01:46.618Z","repository":{"id":165795983,"uuid":"641218231","full_name":"hlfshell/docker-harness","owner":"hlfshell","description":"A testing harness for quick docker containers for golang tests","archived":false,"fork":false,"pushed_at":"2023-05-17T23:48:46.000Z","size":32,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-09T17:14:55.162Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hlfshell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-16T02:57:28.000Z","updated_at":"2025-01-01T20:28:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"705c7a39-6c6f-49de-8728-97762d5daba7","html_url":"https://github.com/hlfshell/docker-harness","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hlfshell%2Fdocker-harness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hlfshell%2Fdocker-harness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hlfshell%2Fdocker-harness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hlfshell%2Fdocker-harness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hlfshell","download_url":"https://codeload.github.com/hlfshell/docker-harness/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247128738,"owners_count":20888234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-12-17T09:14:32.138Z","updated_at":"2026-03-07T20:01:46.613Z","avatar_url":"https://github.com/hlfshell.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docker-harness\n\n`docker-harness` is a golang package that provides a simple interface for using docker for testing applications. It also provides several useful applications pre-built and ready-to-use for testing as either out-of-the-box utilities or examples to follow.\n\n## Module Structure\n\nThis repository uses a multi-module structure, allowing you to install only what you need:\n\n1. **Core Harness** (`github.com/hlfshell/docker-harness`) - The main framework for launching Docker containers\n2. **Individual Database Modules** - Each database is its own installable module:\n   - PostgreSQL: `github.com/hlfshell/docker-harness/databases/postgres`\n   - MySQL: `github.com/hlfshell/docker-harness/databases/mysql`\n   - Redis: `github.com/hlfshell/docker-harness/databases/redis`\n   - Memcached: `github.com/hlfshell/docker-harness/databases/memcached`\n\n### Installation\n\n**For just the core harness:**\n```bash\ngo get github.com/hlfshell/docker-harness\n```\n\n**For specific databases (each installs only its own dependencies):**\n```bash\n# PostgreSQL only\ngo get github.com/hlfshell/docker-harness/databases/postgres\n\n# MySQL only\ngo get github.com/hlfshell/docker-harness/databases/mysql\n\n# Redis only\ngo get github.com/hlfshell/docker-harness/databases/redis\n\n# Memcached only\ngo get github.com/hlfshell/docker-harness/databases/memcached\n```\n\nThis granular separation ensures you only pull the dependencies for the databases you actually use. Each database module automatically includes the core harness as a dependency.\n\n**What each module includes:**\n- **Core Harness**: Docker client, container management utilities\n- **PostgreSQL**: Core harness + `github.com/lib/pq` (PostgreSQL driver)\n- **MySQL**: Core harness + `github.com/go-sql-driver/mysql` (MySQL driver)\n- **Redis**: Core harness + `github.com/redis/go-redis/v9` (Redis client)\n- **Memcached**: Core harness + `github.com/bradfitz/gomemcache` (Memcached client)\n\n## Development\n\nThis project uses [Just](https://just.systems/) as a command runner for common development tasks.\n\n### Available Commands\n\n- 🧪 `just test` - Run all tests (core + all databases)\n- 📊 `just coverage` - Generate test coverage report\n- 🧹 `just clean` - Clean test cache and artifacts\n- 📦 `just build` - Build all modules\n- 🎨 `just format` - Format all Go code\n- 🔍 `just vet` - Run `go vet` on all modules\n- 📝 `just version` - Show the current version tag\n- 🚀 `just release \u003cversion\u003e` - Tag and push a new version (e.g., `just release 1.2.3`)\n\n### Quick Start\n\n```bash\n# Run all tests\njust test\n\n# Format code\njust format\n\n# Release a new version\njust release 1.2.3\n```\n\n## Example Usage\n```golang\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n\n\tharness \"github.com/hlfshell/docker-harness\"\n)\n\nfunc main() {\n\t// The following will create a new postgres container that maps port 3306 to\n\t// any open port on the host machine. Since the tag is not specified, it will\n\t// default to \"latest\".\n\tcontainer, err := harness.NewContainer(\n\t\t// Container name - if left blank it'll allow docker to set it\n\t\t\"TestContainer\",\n\t\t// Image name\n\t\t\"postgres\",\n\t\t// Image tag - \"\" is defaulted to \"latest\"\n\t\t\"\",\n\t\t// Port mapping/exposing\n\t\tmap[string]string{\n\t\t\t\"3306\": \"\",\n\t\t},\n\t\t// Env vars\n\t\tmap[string]string{\n\t\t\t\"POSTGRES_USER\":     \"postgres\",\n\t\t\t\"POSTGRES_PASSWORD\": \"postgres\",\n\t\t\t\"POSTGRES_DB\":       \"postgres\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\terr = container.Start()\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer container.Cleanup()\n\n\trunning, err := container.IsRunning()\n\tif err != nil {\n\t\tpanic(err)\n\t} else if !running {\n\t\tfmt.Println(\"Container did not start properly\")\n\t} else {\n\t\tfmt.Println(\"Container is running!\")\n\t}\n\n\tfmt.Println(\"Container is listening on ports:\", container.GetPorts())\n\n\ttime.Sleep(3 * time.Second)\n}\n```\n\nThe name is assumed unique for the given container instance - thus if a container already exists with the same name, it will be destroyed when the next instance is created.\n\n## Postgres Example\n```golang\npackage main\n\nimport (\n\t\"database/sql\"\n\t\"time\"\n\n\t\"github.com/hlfshell/docker-harness/databases/postgres\"\n)\n\nfunc main() {\n\tcontainer, err := postgres.NewPostgres(\n\t\t// Container name - if left blank it'll allow docker to set it\n\t\t\"TestContainer\",\n\t\t// Image tag - \"\" is defaulted to \"latest\"\n\t\t\"\",\n\t\t// Username\n\t\t\"donatello\",\n\t\t// Password\n\t\t\"super-secret\",\n\t\t// Database\n\t\t\"database\",\n\t)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\terr = container.Create()\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer container.Cleanup()\n\n\tdb, err := container.ConnectWithTimeout(10 * time.Second)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer db.Close()\n\t\n\t// Use db (*sql.DB) here...\n\t_ = db\n}\n```\n\n## Mysql Example\n```golang\npackage main\n\nimport (\n\t\"database/sql\"\n\t\"time\"\n\n\t\"github.com/hlfshell/docker-harness/databases/mysql\"\n)\n\nfunc main() {\n\tcontainer, err := mysql.NewMysql(\n\t\t// Container name - if left blank it'll allow docker to set it\n\t\t\"TestContainer\",\n\t\t// Image tag - \"\" is defaulted to \"latest\"\n\t\t\"\",\n\t\t// Username\n\t\t\"donatello\",\n\t\t// Password\n\t\t\"super-secret\",\n\t\t// Database\n\t\t\"database\",\n\t)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\terr = container.Create()\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer container.Cleanup()\n\n\tdb, err := container.ConnectWithTimeout(10 * time.Second)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer db.Close()\n\t\n\t// Use db (*sql.DB) here...\n\t_ = db\n}\n```\n\n## Redis Example\n\n```golang\npackage main\n\nimport (\n\t\"context\"\n\t\"time\"\n\n\t\"github.com/hlfshell/docker-harness/databases/redis\"\n\t\"github.com/redis/go-redis/v9\"\n)\n\nfunc main() {\n\tr, err := redis.NewRedis(\"TestContainer\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\terr = r.Create()\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer r.Cleanup()\n\n\tclient, err := r.ConnectWithTimeout(10 * time.Second)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer client.Close()\n\t\n\t// Use client (*redis.Client) here...\n\tctx := context.Background()\n\t_ = client.Ping(ctx)\n}\n```\n\n## Memcached Example\n\n```golang\npackage main\n\nimport (\n\t\"time\"\n\n\t\"github.com/bradfitz/gomemcache/memcache\"\n\t\"github.com/hlfshell/docker-harness/databases/memcached\"\n)\n\nfunc main() {\n\tm, err := memcached.NewMemcached(\"TestContainer\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\t// Create the container\n\terr = m.Create()\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer m.Cleanup()\n\n\t// Connect to memcached\n\tclient, err := m.ConnectWithTimeout(10 * time.Second)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\t\n\t// Use client (*memcache.Client) here...\n\t_ = client.Set(\u0026memcache.Item{\n\t\tKey:   \"test\",\n\t\tValue: []byte(\"value\"),\n\t})\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhlfshell%2Fdocker-harness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhlfshell%2Fdocker-harness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhlfshell%2Fdocker-harness/lists"}