pytest-docker-registry-fixtures 0.1.2

Pytest fixtures for testing with docker registries.

pytest-docker-registry-fixtures

Overview

Pytest fixtures to instantiate and populated local docker registries, using lovely-pytest-docker and docker-py, for testing.

Getting Started

Update setup.py to include:

setup(
	tests_require=["pytest-docker-registry-fixtures"]
)

All fixtures should be automatically included via the pytest11 entry point.

import pytest
from pytest_docker_registry_fixtures import DockerRegistryInsecure, DockerRegistrySecure  # Optional, for typing

@pytest.mark.push_image("busybox:1.30.1", "alpine")
def test_docker_registry_secure(docker_registry_secure: DockerRegistrySecure):
    response = requests.head(f"https://{docker_registry_secure.endpoint}/v2/",
        headers=docker_registry_secure.auth_header,
        verify=str(docker_registry_secure.cacerts),
    )
    assert response.status_code == 200

def test_docker_registry_insecure(docker_registry_insecure: DockerRegistryInsecure):
    response = requests.head(f"http://{docker_registry_insecure.endpoint}/v2/")
    assert response.status_code == 200

The push_image mark can optionally be added to stage images in the registry prior to testing. See Markers for details.

Compatibility

• Tested with python 3.8

Installation

From pypi.org

$ pip install pytest_docker_registry_fixtures

From source code

$ git clone https://github.com/crashvb/pytest-docker-registry-fixtures
$ cd pytest-docker-registry-fixtures
$ virtualenv env
$ source env/bin/activate
$ python -m pip install --editable .[dev]

Fixtures

docker_client

Creates a Docker client using configuration values from environment variables. This fixture is used to replicate images into a registry.

def test_docker_pull(docker_client: DockerClient):
    image = docker_client.image.pull("busybox:1.30.1")

docker_compose_insecure

This fixtures uses the docker_compose_files fixture to locate a user-defined docker-compose configuration file (typically tests/docker-compose.yml) that contains the pytest-docker-registry-insecure service. If one cannot be located, an embedded configuration is copied to a temporary location and returned. This fixtures is used to instantiate the insecure docker registry service.

docker_compose_secure

This fixtures uses the docker_compose_files fixture to locate a user-defined docker-compose configuration file (typically tests/docker-compose.yml) that contains the pytest-docker-registry-secure service. If one cannot be located, an embedded configuration is copied to a temporary location and returned. This fixtures is used to instantiate the secure docker registry service; however, unlike the configuration returned by the docker_compose_insecure fixture, this configuration will be treated as a template; the $PATH_CERTIFICATE, $PATH_HTPASSWD, and $PATH_KEY tokens will be populated with the absolute paths provided by the docker_registry_certs and docker_registry_htpasswd fixtures, as appropriate.

docker_registry_auth_header

Retrieves a HTTP basic authentication header that is populated with credentials that can access the secure docker registry service. The credentials are retrieved from the docker_registry_password and docker_registry_username fixtures. This fixtures is used to replicate docker images into the secure docker registry service.

docker_registry_cacerts

Locates a user-defined CA trust store (tests/cacerts) to use to verify connections to the secure docker registry service. If one cannot be located, a temporary trust store is created containing certificates from certifi and the docker_registry_certs fixture. This fixture is used to instantiate the secure docker registry service.

docker_registry_certs

Returns the path to a self-signed certificate and private key that are used by the secure docker registry service. This fixtures is used to instantiate the secure docker registry service.

docker_registry_htpasswd

Provides the path to an htpasswd file that is used by the secure docker registry service. If a user-defined htpasswd file (tests/htpasswd) can be located, it is used. Otherwise, a temporary htpasswd file is created using credentials from the docker_registry_password and docker_registry_username fixtures. This fixtures is used to instantiate the secure docker registry service.

docker_registry_insecure

Configures and instantiates a docker registry without TLS or authentication.

def test_docker_registry_insecure(docker_registry_insecure: DockerRegistryInsecure):

    for image_name in docker_registry_insecure.images:
        response = requests.head(
            f"http://{docker_registry_secure.endpoint}/v2/{image_name.image}/manifests/{image_name.tag}",
        )
        assert response.status_code == 200
        assert "Docker-Content-Digest" in response.headers

NamedTuple Fields

The following fields are defined in the tuple provided by this fixture:

• docker_client - from docker_client
• docker_compose - Path to the fully instantiated docker-compose configuration.
• endpoint - Endpoint of the insecure docker registry service.
• images - List of images that were replicated into the insecure docker registry service.
• service_name - Name of the service within the docker-compose configuration.

Typing is provided by pytest_docker_registry_fixtures.DockerRegistryInsecure.

docker_registry_password

Provides a generated password to use for authentication to the secure docker registry service. This fixtures is used to replicate docker images into the secure docker registry service.

docker_registry_secure

Configures and instantiates a TLS enabled docker registry with HTTP basic authorization.

def test_docker_registry_secure(docker_registry_secure: DockerRegistrySecure):

    for image_name in docker_registry_secure.images:
        response = requests.head(
            f"https://{docker_registry_secure.endpoint}/v2/{image_name.image}/manifests/{image_name.tag}",
            headers=docker_registry_secure.auth_header,
            verify=str(docker_registry_secure.cacerts),
        )
        assert response.status_code == 200
        assert "Docker-Content-Digest" in response.headers

NamedTuple Fields

The following fields are defined in the tuple provided by this fixture:

• auth_header - from docker_registry_auth_header.
• cacerts - from docker_registry_cacerts.
• certs - from docker_registry_certs.
• docker_client - Docker client, from docker_client, with injected authentication credentials for the secure docker registry service.
• docker_compose - Path to the fully instantiated docker-compose configuration.
• endpoint - Endpoint of the secure docker registry service.
• htpasswd - from docker_registry_htpasswd
• images - List of images that were replicated into the secure docker registry service.
• password - from docker_registry_password.
• service_name - Name of the service within the docker-compose configuration.
• ssl_context - from docker_registry_ssl_context.
• username - from docker_registry_username.

Typing is provided by pytest_docker_registry_fixtures.DockerRegistrySecure.

docker_registry_ssl_context

Provides an SSL context containing the CA trust store from the docker_registry_cacerts fixture. This fixture is used to instantiate the secure docker registry service.

docker_registry_username

Provides a generated username to use for authentication to the secure docker registry service. This fixtures is used to replicate docker images into the secure docker registry service.

Markers

pytest.mark.push_image

This marker specifies the docker image name(s) that should be replicated to the docker registry service(s) prior to testing. It can ...

... decorate individual tests:

@pytest.mark.push_image("busybox:1.30.1", "alpine", "python,mysql:latest")
def test_docker_registry_secure(docker_registry_secure: DockerRegistrySecure):
	...

... be specified in the pytestmark list at the module level:

#!/usr/bin/env python

import pytest

pytestmark = [pytest.mark.push_image("busybox:1.30.1", "alpine", "python,mysql:latest")]

...

... or be provided via the corresponding --push-image command-line argument:

python -m pytest --push-image busybox:1.30.1 --push-image alpine --push-image python,mysql:latest ...

This marker supports being specified multiple times, and removes duplicate image names (see Limitations below).

A helper function, get_pushed_images, is included for test scenarios that wish to inspect the maker directly:

from pytest_docker_registry_fixtures import get_pushed_images, ImageName

@pytest.mark.push_image("busybox:1.30.1")
def test_docker_registry_secure(docker_registry_secure: DockerRegistrySecure, request):
    image_name = ImageName.parse(get_pushed_images(request)[0])

Limitations

1. All of the fixtures provided by this package are session scoped; and will only be executed once per test execution. This allows for a maximum of two docker registry services: one insecure instance and one secure instance.
2. The push_image marker is processed as part of the docker_registry_insecure and docker_registry_secure fixtures. As such:

• all markers will be aggregated during initialization of the session, and processed prior test execution.
• Pushed images will be replicated to both the insecure and secure docker registries, if both are instantiated.

3. A working docker client is required to push images.

Changelog

0.1.1 (2020-08-13)

• Better testing of manifest lists.
• Minor refactoring.
• Cleanup lint.

0.1.0 (2020-08-06)

• Initial release.

Development

Source Control