package dktest
import "github.com/dhui/dktest"
Package dktest provides an easy way to write integration tests using Docker
dktest is short for dockertest
Code:play
Code:play
Example (Nginx)¶
package main
import (
"context"
"fmt"
"net/http"
"net/url"
"testing"
"github.com/dhui/dktest"
_ "github.com/lib/pq"
)
func main() {
dockerImageName := "nginx:alpine"
readyFunc := func(ctx context.Context, c dktest.ContainerInfo) bool {
ip, port, err := c.FirstPort()
if err != nil {
return false
}
u := url.URL{Scheme: "http", Host: ip + ":" + port}
req, err := http.NewRequest(http.MethodGet, u.String(), nil)
if err != nil {
fmt.Println(err)
return false
}
req = req.WithContext(ctx)
if resp, err := http.DefaultClient.Do(req); err != nil {
return false
} else if resp.StatusCode != 200 {
return false
}
return true
}
// dktest.Run() should be used within a test
dktest.Run(&testing.T{}, dockerImageName, dktest.Options{PortRequired: true, ReadyFunc: readyFunc},
func(t *testing.T, c dktest.ContainerInfo) { // nolint:revive
// test code here
})
}
Example (Postgres)¶
package main
import (
"context"
"database/sql"
"fmt"
"testing"
"github.com/dhui/dktest"
_ "github.com/lib/pq"
)
func main() {
dockerImageName := "postgres:alpine"
readyFunc := func(ctx context.Context, c dktest.ContainerInfo) bool {
ip, port, err := c.FirstPort()
if err != nil {
return false
}
connStr := fmt.Sprintf("host=%s port=%s user=postgres password=password dbname=postgres sslmode=disable", ip, port)
db, err := sql.Open("postgres", connStr)
if err != nil {
return false
}
defer db.Close() // nolint:errcheck
return db.PingContext(ctx) == nil
}
// dktest.Run() should be used within a test
dktest.Run(&testing.T{}, dockerImageName, dktest.Options{
PortRequired: true,
ReadyFunc: readyFunc,
Env: map[string]string{"POSTGRES_PASSWORD": "password"}},
func(t *testing.T, c dktest.ContainerInfo) {
ip, port, err := c.FirstPort()
if err != nil {
t.Fatal(err)
}
connStr := fmt.Sprintf("host=%s port=%s user=postgres password=password dbname=postgres sslmode=disable", ip, port)
db, err := sql.Open("postgres", connStr)
if err != nil {
t.Fatal(err)
}
defer db.Close() // nolint:errcheck
if err := db.Ping(); err != nil {
t.Fatal(err)
}
// Test using db
})
}
Index ¶
- Variables
- func Run(t *testing.T, imgName string, opts Options, testFunc func(*testing.T, ContainerInfo))
- func RunContext(ctx context.Context, logger Logger, imgName string, opts Options, testFunc func(ContainerInfo) error) (retErr error)
- type ContainerInfo
- func (c ContainerInfo) FirstPort() (hostIP string, hostPort string, err error)
- func (c ContainerInfo) FirstUDPPort() (hostIP string, hostPort string, err error)
- func (c ContainerInfo) Port(containerPort uint16) (hostIP string, hostPort string, err error)
- func (c ContainerInfo) String() string
- func (c ContainerInfo) UDPPort(containerPort uint16) (hostIP string, hostPort string, err error)
- type Logger
- type Options
Examples ¶
Variables ¶
var ( // DefaultPullTimeout is the default timeout used when pulling images DefaultPullTimeout = time.Minute // DefaultTimeout is the default timeout used when starting a container and checking if it's ready DefaultTimeout = time.Minute // DefaultReadyTimeout is the default timeout used for each container ready check. // e.g. each invocation of the ReadyFunc DefaultReadyTimeout = 2 * time.Second // DefaultCleanupTimeout is the default timeout used when stopping and removing a container DefaultCleanupTimeout = 15 * time.Second )
Functions ¶
func Run ¶
Run runs the given test function once the specified Docker image is running in a container
func RunContext ¶
func RunContext(ctx context.Context, logger Logger, imgName string, opts Options, testFunc func(ContainerInfo) error) (retErr error)
RunContext is similar to Run, but takes a parent context and returns an error and doesn't rely on a testing.T.
Types ¶
type ContainerInfo ¶
ContainerInfo holds information about a running Docker container
func (ContainerInfo) FirstPort ¶
func (c ContainerInfo) FirstPort() (hostIP string, hostPort string, err error)
FirstPort gets the first published/bound/mapped TCP port. It is always safer to use Port(). This provided as a convenience method and should only be used with Docker images that only expose a single port. If the Docker image exposes multiple ports, then the "first" port will not always be the same.
func (ContainerInfo) FirstUDPPort ¶
func (c ContainerInfo) FirstUDPPort() (hostIP string, hostPort string, err error)
FirstUDPPort gets the first published/bound/mapped UDP port. It is always safer to use UDPPort(). This provided as a convenience method and should only be used with Docker images that only expose a single port. If the Docker image exposes multiple ports, then the "first" port will not always be the same.
func (ContainerInfo) Port ¶
func (c ContainerInfo) Port(containerPort uint16) (hostIP string, hostPort string, err error)
Port gets the specified published/bound/mapped TCP port
func (ContainerInfo) String ¶
func (c ContainerInfo) String() string
String gets the string representation for the ContainerInfo. This is intended for debugging purposes.
func (ContainerInfo) UDPPort ¶
func (c ContainerInfo) UDPPort(containerPort uint16) (hostIP string, hostPort string, err error)
UDPPort gets the specified published/bound/mapped UDP port
type Logger ¶
type Logger interface {
Log(...interface{})
}
Logger is the interface used to log messages.
type Options ¶
type Options struct { // PullTimeout is the timeout used when pulling images PullTimeout time.Duration // Timeout is the timeout used when starting a container and checking if it's ready Timeout time.Duration // ReadyTimeout is the timeout used for each container ready check. // e.g. each invocation of the ReadyFunc ReadyTimeout time.Duration // CleanupTimeout is the timeout used when stopping and removing a container CleanupTimeout time.Duration // CleanupImage specifies whether or not the image should be removed after the test run. // If the image is used by multiple tests, you'll want to cleanup the image yourself. CleanupImage bool ReadyFunc func(context.Context, ContainerInfo) bool Env map[string]string Entrypoint []string Cmd []string // If you prefer to specify your port bindings as a string, use nat.ParsePortSpecs() PortBindings nat.PortMap PortRequired bool LogStdout bool LogStderr bool ShmSize int64 Volumes []string Mounts []mount.Mount Hostname string // Platform specifies the platform of the docker image that is pulled. Platform string ExposedPorts nat.PortSet }
Options contains the configurable options for running tests in the docker image
Source Files ¶
container_info.go dktest.go doc.go errors.go logger.go math.go options.go rand.go
Directories ¶
Path | Synopsis |
---|---|
mockdockerclient | Package mockdockerclient provides mocks for the Docker client github.com/docker/docker/client |
- Version
- v0.4.4 (latest)
- Published
- Jan 24, 2025
- Platform
- linux/amd64
- Imports
- 16 packages
- Last checked
- 2 weeks ago –
Tools for package owners.