Metadata-Version: 2.4
Name: container-tester
Version: 1.0.0rc1
Summary: Generate multiple docker cointainers to test projects
Author-email: David Angarita <davidangarita.sistemas@gmail.com>
Maintainer-email: Andrew Pikul <ajpikul@gmail.com>
License: MIT License
        
        Copyright (c) 2025 geopozo
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: docker>=7.1.0
Requires-Dist: platformdirs>=4.5.0
Requires-Dist: typer>=0.19.2
Dynamic: license-file

# Container-tester

<div
  align="center"
>
    <img
      height="250"
      width="250"
      alt="container_small"
      src="https://raw.githubusercontent.com/geopozo/container-tester/main/docs/media/logo.png">
</div>

## Overview

Container-Tester is a small Python utility that helps you test your project on
top of many different Linux distributions without having to run and maintain
lots of Docker tests yourself. It provides a command-line interface (CLI) that
can:

- Build that Dockerfile into a image and report its size and metadata.
- Run a container from that image, execute a command inside it and capture the
  logs.
- Optionally clean up images and containers when you are done.
- Iterate over a curated list of popular Python, Debian/Ubuntu, Fedora and
  Alpine base images defined in `docker-config.toml` and perform the above steps
  for each of them.

## Installation

You can use Container-Tester in two ways:

1. Install in your project:

   ```bash
   uv add container-tester
   uv run contest --help

   # or if you don't want to install:
   uvx --from container-tester contest --help
   ```

## Using Container-tester

```bash
Usage: contest [OPTIONS] [OS_NAME]

Generate, build, and run Docker resources from a base image or config file.

+- Options -------------------------------------------------------------------+
| --json    --no-json          Show output in json format                     |
|                              (use --json to enable) [default: no-json]      |
| --pretty  --no-pretty        Show output in pretty format                   |
|                              (use --pretty to enable) [default: no-pretty]  |
| --clean   --no-clean         Clean Docker resources after run               |
|                              (use --clean to enable) [default: no-clean]    |
| --install-completion         Install completion for the current shell.      |
| --show-completion            Show completion for the current shell, to copy |
|                              it or customize the installation.              |
| --help                       Show this message and exit.                    |
+-----------------------------------------------------------------------------+

+- Commands ------------------------------------------------------------------+
| test-config     Generate, build, and run Docker resources from a docker     |
| test-container  Generate, build, and run Docker resources from a base image.|
+-----------------------------------------------------------------------------+
```

### Example

Here is a quick example that runs a simple command across all default profiles:

```bash
uv run contest test-config
```

To test only on the Ubuntu image, you can specify its base image directly and
use a custom command:

```bash
uv run contest test-container ubuntu:latest --command "echo Hello, world!"
```

## Default profiles

By default, Container-Tester comes with a handful of profiles covering common
Python, Debian/Ubuntu and Alpine base images. Each profile defines an
`image_tag` (used as the resulting image name) and the corresponding `os_name`.
A few of them are shown below- see `src/container_tester/docker-config.toml` for
the full list:

| image_tag     | os_name                 |
| ------------- | ----------------------- |
| py312_trixie  | python:3.12-slim-trixie |
| ubuntu_latest | ubuntu:latest           |
| alpine_latest | alpine:latest           |

## Custom Docker Configuration

You can define your own `docker-config.toml` file to run custom Docker images
tailored to your needs. Use the following format to specify multiple profiles:

```toml
[py311_slim]
command = ""
os_name = "python:3.11-slim"
os_commands = []
pkg_manager = "apt"

[ubuntu_latest]
command = ""
os_name = "ubuntu:latest"
os_commands = ["apt-get update && apt-get install -y ca-certificates"]
pkg_manager = "apt"

# Add more profiles as needed...
```

### Configuration Fields

- `command`: Shell command to execute inside the containers.
- `image_tag`: A unique identifier for the Docker image profile.
- `os_name`: The name and tag of the Docker image to use.
- `os_commands`: A list of shell commands to run after container startup
  (optional).
- `pkg_manager`: The package manager used by the OS (e.g., apk, dnf, apt).

### Run with Your Custom Config

After creating your `docker-config.toml` file, launch your custom Docker setup
by running:

```bash
uv run contest test-config
```

## License

This project is licensed under the terms of the MIT license.
