Aceptadora provides the boilerplate to orchestrate the containers for an acceptance test.

aceptadora

lint acceptance Travis build status

Aceptadora provides the boilerplate to orchestrate the containers for an acceptance test.

Aceptadora is a replacement for docker-compose in acceptance tests, and it also allows running and debugging tests from your IDE.

Example

The acceptance tests of this package are an example of usage for this package. There are also CI builds running on both Github Actions and Travis CI that serve as an example.

Long story short:

  • Define your service in a YAML file inspired by docker-compose format, with an idiomatic name of aceptadora.yml
  • Define your environment variables in some config.env files
  • Load them in your test:
   aceptadora.SetEnv(
   	s.T(),
   	aceptadora.OneOfEnvConfigs(
   		aceptadora.EnvConfigWhenEnvVarPresent("../config/gitlab.env", "GITLAB_CI"),
   		aceptadora.EnvConfigAlways("../config/default.env"),
   	),
   	aceptadora.EnvConfigAlways("acceptance.env"),
   ) 
  • Fill the aceptadora.Config values, you can use github.com/colega/envconfig for that
   envconfig.MustProcess("ACCEPTANCE", &s.cfg)
  • Instantiate the aceptadora:
   aceptadora := aceptadora.New(t, cfg)
  • Start your service:
   aceptadora.Run(ctx, "redis")
  • Test stuff
  • When you're done, stop it using aceptadora.StopAll(ctx) or aceptadora.Stop(ctx, "redis")

Motivations

We've been using docker-compose for acceptance tests for a long time, and while this approach did have issues (since test subjects and dependencies were not restarted between tests, we had to have some suites depending on other ones, which made the tests flaky and slow) we lived with it until the introduction of gRPC. Once we started playing with gRPC we found an issue: the gRPC golang client tries to connect to the service when the service is started, and if it fails, it will keep returning that error for a while. Since we started our test subjects before the acceptance-tester in the former approach, our test subjects failed to call the mocked gRPC servers on the acceptance-tester.

So, we created a library that restarted our test subject interacting with docker from the acceptance test itself.

Then, we found the need to restart multiple test subjects plus the complexity of having to handle two kinds of configurations (docker-compose for dependencies and aceptadora for test subjects) so we decided to extend the functionality of aceptadora to completely replace the docker-compose and allow managing the lifecycle of all dependencies from the test.

You can read the full story on Medium.

Decisions

Everything in aceptadora accepts t *testing.T and everything does require.NoError(t, err) because in tests nobody's going to handle the errors anyway, so we apply a fail-fast strategy, removing the retured errors and keeping the API clean for clearer acceptance tests.

Running

In order to handle multiple environments there are some stages in config loading. Notice that all the configs loaded expand the env vars set by ${VAR} to their values from what's already loaded.

First, we load some very basic env-dependant config, deciding on env vars to load a local or gitlab config. This configuration mostly provides details about networking setup:

  • Where can acceptance-tester reach the services? Usually this would be localhost, but on Gitlab it's docker as we're running dind.
  • Where can services reach the acceptance-tester? This will be set to the first local non-loopback IP address in the environment variable called TESTER_ADDRESS. You can set this variable to something more specific before running the test too, in which case it won't be overwritten.

One may wonder: why don't we just decide all of that in some kind of test-loading shellscript? The answer is that deciding that from the test itself allows us running the tests from any IDE as a normal test, instead of having a proxy script. Of course loading some env vars would work, but since aceptadora can do this for you, why should we care? This way we can make sure that test running is portable and doesn't require any external dependencies.

Then we load more env configs for the test itself, usually acceptance.env, which tells the acceptance test where the aceptadora.yml file is located, and how images from different docker registries are pulled. Notice that acceptance.env can be specific to each suite you may have if their paths are different. You can load as many common configs as you want, loading an acceptance.env and then ../config/acceptance.env for example.

Here aceptadora.New() would load the aceptadora.yml file from the provided dir and filename, and it will also set ${YAMLDIR} variable for the yamls itself to be able to reference its configs and binds from where the yaml is located instead of from where the test is located: this allows us having multiple test suites in different folders using the same aceptadora.yml file.

Finally, we run services by just running aceptadora.Run(ctx, "svc-name-in-the-yaml").

Aceptadora will also take care of stopping the services, you can call aceptadora.Stop(ctx, svcName) to stop one of them, or StopAll(ctx) to stop all the (still running) services.

Unit tests

This package doesn't have unit tests. All the testing is performed by the example itself in the acceptance tests folder. The unit tests would require either defining interfaces for the functionality that docker provides and mocking them, which would overcomplicate the code without offering enough value in exchange, or testing using the docker real docker API, which is already covered by the acceptance tests. However, this is opinionated. Feel free to disagree, open us an issue with your proposal, or even better, a pull request.

Comments
  • Add StopTimeout default to 0

    Add StopTimeout default to 0

    If we provide timeout=0 to docker stop operation, it will happen earlier, and since we don't care about graceful shutdowns in tests, it should be okay.

    Configurable by Config.StopTimeout.

  • Refactored image pulling logging

    Refactored image pulling logging

    This change aims to fix the following contradictory logs:

    puller.go:86: Not pulling <image name>: disabled by config for domain <domain>
    aceptadora.go:86: Pulled image <image name> for <service name> in <time>
    
  • v0.2.1 Fix ImagePuller authentication

    v0.2.1 Fix ImagePuller authentication

    We were serializing the wrong struct, and since we're not testing the auth in the open source version, that went unnoticed.

    We really need an authenticated build / gitlab CI job for this one.

  • v0.2.0 ImagePuller as aceptadora.New() param

    v0.2.0 ImagePuller as aceptadora.New() param

    Instead of instantiating ImagePuller for each aceptadora, we now can reuse a global one (for the test suite). This will avoid pulling same image for each test where a new aceptadora is created every time.

    We need this as docker repository is now imposing rate limit and introducing latency on docker pulls, and we're seeing times of up to 2.5s to just check that we have the latest image.

    This is a breaking change.

  • Remove needless scripts/acceptance.sh

    Remove needless scripts/acceptance.sh

    Although it does generate some value as it can be shellchecked, it also causes distraction in this repo as we can just run that command from the makefile, so we'll remove it.

DepCharge is a tool designed to help orchestrate the execution of commands across many directories at once.

DepCharge DepCharge is a tool that helps orchestrate the execution of commands across the many dependencies and directories in larger projects. It als

Sep 27, 2022
Open Source runtime scanner for Linux containers (LXD), It performs security audit checks based on CIS Linux containers Benchmark specification
Open Source runtime scanner for Linux containers (LXD), It performs security audit checks based on CIS Linux containers  Benchmark specification

lxd-probe Scan your Linux container runtime !! Lxd-Probe is an open source audit scanner who perform audit check on a linux container manager and outp

Dec 26, 2022
Provides an interactive prompt to connect to ECS Containers using the ECS ExecuteCommand API.
Provides an interactive prompt to connect to ECS Containers using the ECS ExecuteCommand API.

ecsgo Heavily inspired by incredibly useful gossm, this tool makes use of the new ECS ExecuteCommand API to connect to running ECS tasks. It provides

Dec 12, 2022
A best practices Go source project with unit-test and integration test, also use skaffold & helm to automate CI & CD at local to optimize development cycle

Dependencies Docker Go 1.17 MySQL 8.0.25 Bootstrap Run chmod +x start.sh if start.sh script does not have privileged to run Run ./start.sh --bootstrap

Apr 4, 2022
Test-at-scale - TAS - An intelligent test execution platform for engineering teams to achieve high development velocity
Test-at-scale - TAS - An intelligent test execution platform for engineering teams to achieve high development velocity

Test At Scale Test Smarter, Release Faster with test-at-scale. Status Table of c

Dec 22, 2022
Learning about containers and how they work by creating them the hard way
Learning about containers and how they work by creating them the hard way

Containers the hard way: Gocker: A mini Docker written in Go It is a set of Linux's operating system primitives that provide the illusion of a contain

Jan 7, 2023
A tool to build, deploy, and release any environment using System Containers.
A tool to build, deploy, and release any environment using System Containers.

Bravetools Bravetools is an end-to-end System Container management utility. Bravetools makes it easy to configure, build, and deploy reproducible envi

Dec 14, 2022
Vulnerability Static Analysis for Containers
Vulnerability Static Analysis for Containers

Clair Note: The main branch may be in an unstable or even broken state during development. Please use releases instead of the main branch in order to

Jan 4, 2023
Binary program to restart unhealthy Docker containers

DeUnhealth Restart your unhealthy containers safely Features Restart unhealthy containers marked with deunhealth.restart.on.unhealthy=true label Recei

Dec 22, 2022
Simple docker tui to list, start and stop your containers
Simple docker tui to list, start and stop your containers

docker-tui Simple docker tui that lets you list, start and stop your containers. Current status Rough, initial prototype. Build with This tool relies

Dec 2, 2022
A super simple demo to document my journey to reasonably sized docker containers.

hello-docker A super simple demo to document my journey to reasonably sized docker containers. Task at Hand Build a docker container as small as possi

Nov 30, 2021
Viewnode displays Kubernetes cluster nodes with their pods and containers.

viewnode The viewnode shows Kubernetes cluster nodes with their pods and containers. It is very useful when you need to monitor multiple resources suc

Nov 23, 2022
Truly Minimal Linux Distribution for Containers

Statesman Statesman is a minimal Linux distribution, running from memory, that has just enough functionality to run OCI-compatible containers. Rationa

Nov 12, 2021
This repository is where I'm learning to write a CLI using Go, while learning Go, and experimenting with Docker containers and APIs.

CLI Project This repository contains a CLI project that I've been working on for a while. It's a simple project that I've been utilizing to learn Go,

Dec 12, 2021
Build and run Docker containers leveraging NVIDIA GPUs
Build and run Docker containers leveraging NVIDIA GPUs

NVIDIA Container Toolkit Introduction The NVIDIA Container Toolkit allows users to build and run GPU accelerated Docker containers. The toolkit includ

Jan 7, 2023
Docker-NodeJS - Creating a CI/CD Environment for Serverless Containers on Google Cloud Run
Docker-NodeJS - Creating a CI/CD Environment for Serverless Containers on Google Cloud Run

Creating a CI/CD Environment for Serverless Containers on Google Cloud Run Archi

Jan 8, 2022
Fadvisor(FinOps Advisor) is a collection of exporters which collect cloud resource pricing and billing data guided by FinOps, insight cost allocation for containers and kubernetes resource
Fadvisor(FinOps Advisor) is a collection of exporters which collect cloud resource pricing and billing data guided by FinOps, insight cost allocation for containers and kubernetes resource

[TOC] Fadvisor: FinOps Advisor fadvisor(finops advisor) is used to solve the FinOps Observalibility, it can be integrated with Crane to help users to

Jan 3, 2023
My Homemade ci-cd service made for docker containers

Docker-CI-CD What Is This? The Docker-CI-CD is a tool that helps you to make every commit and push to your github repositories happen seamlessly and a

Jan 24, 2022
Show dependency graph of docker images/containers
Show dependency graph of docker images/containers

docker-graph Show dependency graph of docker images/containers like this: Orange is images and green is containers. Features Collect docker images, co

Feb 7, 2022