From 7fa2797c8ef843fd9c01f4d15ab15fb6a006b025 Mon Sep 17 00:00:00 2001 From: Joshua Powers Date: Thu, 2 Jun 2022 11:33:51 -0600 Subject: [PATCH] docs: update test-container docs (#11244) --- docs/INTEGRATION_TESTS.md | 119 +++++++++++++++++++++++++++++++++----- 1 file changed, 103 insertions(+), 16 deletions(-) diff --git a/docs/INTEGRATION_TESTS.md b/docs/INTEGRATION_TESTS.md index 734d596aecab8..4d5e60347c4fb 100644 --- a/docs/INTEGRATION_TESTS.md +++ b/docs/INTEGRATION_TESTS.md @@ -47,27 +47,114 @@ defer func() { }() ``` -The `servicePort` is the port the service is running on and Telegraf will -connect to. When the port is specified as a single value (e.g. `11211`) then -testcontainers will generate a random port for the service to start on. This -way multiple tests can be run and prevent ports from conflicting. +User's should start the container and then defer termination of the container. -The `test.Container` type requires at least the following three items: +The `test.Container` type requires at least an image, ports to expose, and a +wait stanza. See the following to learn more: + +### Images + +Images are pulled from [DockerHub][2] by default. When looking for and +selecting an image from DockerHub, please use the following priority order: + +1. [Official Images][3]: these images are generally produced by the publisher + themselves and are fully supported with great documentation. These images are + easy to spot as they do not have an author in the name (e.g. "mysql") +2. Publisher produced: not all software has an entry in the above Official + Images. This may be due to the project being smaller or moving faster. In + this case, pull directly from the publisher's DockerHub whenever possible. +3. [Bitnami][4]: If neither of the above images exist, look at the images + produced and maintained by Bitnami. They go to great efforts to create images + for the most popular software, produce great documentation, and ensure that + images are maintained. +4. Other images: If, and only if, none of the above images will work for a + particular use-case, then another image can be used. Be prepared to justify, + the use of these types of images. + +### Ports + +When the port is specified as a single value (e.g. `11211`) then testcontainers +will generate a random port for the service to start on. This way multiple +tests can be run and prevent ports from conflicting. + +The test container will expect an array of ports to expose for testing. For +most tests only a single port is used, but a user can specify more than one +to allow for testing if another port is open for example. + +On each container's DockerHub page, the README will usually specify what ports +are used by the container by default. For many containers this port can be +changed or specified with an environment variable. + +If no ports are specified, a user can view the image tag and view the various +image layers. Find an image layer with the `EXPOSE` keyword to determine what +ports are used by the container. + +### Wait Stanza + +The wait stanza lays out what test containers will wait for to determine that +the container has started and is ready for use by the test. It is best to +provide not only a port, but also a log message. Ports can come up very early +in the container, and the service may not be ready. + +To find a good log message, it is suggested to launch the container manually +and see what the final message is printed. Usually this is something to the +effect of "ready for connections" or "setup complete". Also ensure that this +message only shows up once, or the use of the + +### Other Parameters + +There are other optional parameters that user can make use of for additional +configuration of the test containers: + +- `BindMounts`: used to mount local test data into the container. The order is + location in the container as the key and the local file as the value. +- `Entrypoint`: if a user wishes to override the entrypoint with a custom + command +- `Env`: to pass environmental variables to the container similar to Docker + CLI's `--env` option +- `Name`: if a container needs a hostname set or expects a certain name use + this option to set the containers hostname +- `Networks`: if the user creates a custom network -1. An image name from [DockerHub][2], which can include a specific tag or not -2. An array of port(s) to expose to the test to connect to -3. A wait stanza. This lays out what testcontainers will wait for to determine - that the container has started and is ready for use by the test. It is best - to provide not only a port, but also a log message. Ports can come up very - early in the container, and the service may not be ready. +[1]: "testcontainers-go" +[2]: "DockerHub" +[3]: "DockerHub Official Images" +[4]: "Bitnami Images" -There are other optional parameters like `Env` to pass environmental variables -to the container or `BindMounts` to pass test data into the container as well. +## Network -User's should start the container and then defer termination of the container. +By default the containers will use the bridge network where other containers +cannot talk to each other. -[1]: "testcontainers-go" -[2]: "DockerHub" +If a custom network is required for running tests, for example if containers +do need to communicate, then users can set that up with the following code: + +```go +networkName := "test-network" +net, err := testcontainers.GenericNetwork(ctx, testcontainers.GenericNetworkRequest{ + NetworkRequest: testcontainers.NetworkRequest{ + Name: networkName, + Attachable: true, + CheckDuplicate: true, + }, +}) +require.NoError(t, err) +defer func() { + require.NoError(t, net.Remove(ctx), "terminating network failed") +}() +``` + +Then specify the network name in the container startup: + +```go +zookeeper := testutil.Container{ + Image: "wurstmeister/zookeeper", + ExposedPorts: []string{"2181:2181"}, + Networks: []string{networkName}, + WaitingFor: wait.ForLog("binding to port"), + Name: "telegraf-test-zookeeper", +} +``` ## Contributing