{"id":15637927,"url":"https://github.com/dhui/dktest","last_synced_at":"2025-04-07T16:17:43.081Z","repository":{"id":34919698,"uuid":"164104048","full_name":"dhui/dktest","owner":"dhui","description":"Integration testing in Go with Docker","archived":false,"fork":false,"pushed_at":"2024-09-08T20:58:16.000Z","size":159,"stargazers_count":105,"open_issues_count":2,"forks_count":15,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-29T11:13:37.514Z","etag":null,"topics":["docker","go","golang","integration-testing","testing-tools"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhui.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-04T12:19:31.000Z","updated_at":"2024-09-10T17:47:32.000Z","dependencies_parsed_at":"2024-04-15T06:54:22.323Z","dependency_job_id":"fca94594-cd94-4619-85dd-f72c02e08c7a","html_url":"https://github.com/dhui/dktest","commit_stats":{"total_commits":100,"total_committers":13,"mean_commits":"7.6923076923076925","dds":0.24,"last_synced_commit":"46198177016106dd3b053e31a9c76d2274a78bd8"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhui%2Fdktest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhui%2Fdktest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhui%2Fdktest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhui%2Fdktest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhui","download_url":"https://codeload.github.com/dhui/dktest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247685628,"owners_count":20979085,"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":["docker","go","golang","integration-testing","testing-tools"],"created_at":"2024-10-03T11:15:23.073Z","updated_at":"2025-04-07T16:17:43.061Z","avatar_url":"https://github.com/dhui.png","language":"Go","readme":"# dktest\n\n![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/dhui/dktest/go.yml?branch=master) [![Coverage Status](https://img.shields.io/coveralls/github/dhui/dktest/master.svg)](https://coveralls.io/github/dhui/dktest?branch=master) [![GoDoc](https://godoc.org/github.com/dhui/dktest?status.svg)](https://godoc.org/github.com/dhui/dktest) [![Go Report Card](https://goreportcard.com/badge/github.com/dhui/dktest)](https://goreportcard.com/report/github.com/dhui/dktest) [![GitHub Release](https://img.shields.io/github/release/dhui/dktest/all.svg)](https://github.com/dhui/dktest/releases) ![Supported Go versions](https://img.shields.io/badge/Go-1.22%2C%201.23-lightgrey.svg)\n\n`dktest` is short for **d**oc**k**er**test**.\n\n`dktest` makes it stupidly easy to write integration tests in Go using Docker. Pulling images, starting containers, and cleaning up (even if your tests panic) is handled for you automatically!\n\n## API\n\n`Run()` is the workhorse\n\n```golang\ntype ContainerInfo struct {\n    ID        string\n    Name      string\n    ImageName string\n    IP        string\n    Port      string\n}\n\ntype Options struct {\n    Timeout   time.Duration\n    ReadyFunc func(ContainerInfo) bool\n    Env       map[string]string\n    // If you prefer to specify your port bindings as a string, use nat.ParsePortSpecs()\n    PortBindings nat.PortMap\n    PortRequired bool\n}\n\nfunc Run(t *testing.T, imgName string, opts Options, testFunc func(*testing.T, ContainerInfo))\n```\n\n## Example Usage\n\n```golang\nimport (\n    \"context\"\n    \"testing\"\n)\n\nimport (\n    \"github.com/dhui/dktest\"\n    _ \"github.com/lib/pq\"\n)\n\nfunc pgReady(ctx context.Context, c dktest.ContainerInfo) bool {\n    ip, port, err := c.FirstPort()\n    if err != nil {\n        return false\n    }\n    connStr := fmt.Sprintf(\"host=%s port=%s user=postgres dbname=postgres sslmode=disable\", ip, port)\n    db, err := sql.Open(\"postgres\", connStr)\n    if err != nil {\n        return false\n    }\n    defer db.Close()\n    return db.PingContext(ctx) == nil\n}\n\nfunc Test(t *testing.T) {\n    dktest.Run(t, \"postgres:alpine\", dktest.Options{PortRequired: true, ReadyFunc: pgReady},\n        func(t *testing.T, c dktest.ContainerInfo) {\n        ip, port, err := c.FirstPort()\n        if err != nil {\n            t.Fatal(err)\n        }\n        connStr := fmt.Sprintf(\"host=%s port=%s user=postgres dbname=postgres sslmode=disable\", ip, port)\n        db, err := sql.Open(\"postgres\", connStr)\n        if err != nil {\n            t.Fatal(err)\n        }\n        defer db.Close()\n        if err := db.Ping(); err != nil {\n            t.Fatal(err)\n        }\n        // Test using db\n    })\n}\n```\n\nFor more examples, see the [docs](https://godoc.org/github.com/dhui/dktest).\n\n## Debugging tests\n\nRunning `go test` with the `-v` option will display the container lifecycle log statements\nalong with the container ID.\n\n### Short lived tests/containers\n\nRun `go test` with the `-v` option and specify the `LogStdout` and/or `LogStderr` `Options`\nto see the container's logs.\n\n### Interactive tests/containers\n\nRun `go test` with the `-v` option to get the container ID and check the container's logs with\n`docker logs -f $CONTAINER_ID`.\n\n## Cleaning up dangling containers\n\nIn the unlikely scenario where `dktest` leaves dangling containers,\nyou can find and removing them by using the `dktest` label:\n\n```shell\n# list dangling containers\n$ docker ps -a --filter label=dktest\n# stop dangling containers\n$ docker ps --filter label=dktest | awk '{print $1}' | grep -v CONTAINER | xargs docker stop\n# remove dangling containers\n$ docker container prune --filter label=dktest\n```\n\n## Roadmap\n\n* [x] Support multiple ports in `ContainerInfo`\n* [ ] Use non-default network\n* [ ] Add more `Options`\n  * [x] Volume mounts\n  * [ ] Network config\n* [ ] Support testing against multiple containers. It can be faked for now by nested/recursive `Run()` calls but that serializes the containers' startup time.\n\n## Comparisons\n\nLast updated: 2020/01/03\n\n### [dockertest](https://github.com/ory/dockertest)\n\n#### Why `dktest` is better\n\n* Uses the [official Docker SDK](https://github.com/docker/docker)\n  * [docker/docker](https://github.com/docker/docker) (aka [moby/moby](https://github.com/moby/moby)) uses [import path checking](https://golang.org/cmd/go/#hdr-Import_path_checking), so needs to be imported as `github.com/docker/docker`\n* Designed to run in the Go testing environment\n  * Smaller API surface\n  * Running Docker containers are automatically cleaned up\n* Has better test coverage\n* Uses package management (Go modules) properly. e.g. not [manually vendored](https://github.com/ory/dockertest/pull/122)\n\n#### Why `dockertest` is better\n\n* Has been around longer and API is more stable\n* More options for configuring Docker containers\n* Has more Github stars and contributors\n\n### [testcontainers-go](https://github.com/testcontainers/testcontainers-go)\n\nTBD\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhui%2Fdktest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhui%2Fdktest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhui%2Fdktest/lists"}