Tomodachi Testcontainers

Build Status

Tomodachi Testcontainers is a Python library built on top of testcontainers-python. It provides Testcontainers, pytest fixtures, and test clients for convenient use of Testcontainers with pytest and testing applications built with the Python Tomodachi framework.

This library was created to explore and learn Testcontainers. Although initially intended to be used with the Tomodachi framework, it works for testing applications built with any other Python framework like Flask, FastAPI, Django, etc.

What is Testcontainers?

Testcontainers is an open-source framework for providing throwaway, lightweight instances of databases, message brokers, web browsers, or just about anything that can run in a Docker container. It facilitates the use of Docker containers for functional, integration, and end-to-end testing. — https://testcontainers.com/

To learn more about what Testcontainers are and what problems they solve, take a look at the Getting Started guide in the official Testcontainers documentation - https://testcontainers.com/getting-started/

Documentation

Find documentation at https://filipsnastins.github.io/tomodachi-testcontainers/

The official Testcontainers documentation is at https://testcontainers.com/

Installation

Install with pip:

pip install tomodachi-testcontainers

Install with uv:

uv add --dev tomodachi-testcontainers

Find a list of extras in the installation reference.

A Simple Example

The hello, world Tomodachi service:

# src/hello.py
import tomodachi
from aiohttp import web


class Service(tomodachi.Service):
    @tomodachi.http("GET", r"/hello/?")
    async def hello(self, request: web.Request) -> web.Response:
        name = request.query.get("name", "world")
        return web.json_response({"message": f"Hello, {name}!"})

testcontainer_image fixture builds a Docker image with a Dockerfile from the current working directory.
tomodachi_container fixture starts a new Docker container running the hello service on a randomly available port.
test_hello_testcontainers sends a GET /hello?name=Testcontainers request to the running container and asserts the response.

# tests/test_hello.py
from typing import Generator

import httpx
import pytest

from tomodachi_testcontainers import DockerContainer, TomodachiContainer


@pytest.fixture(scope="session")
def tomodachi_container(testcontainer_image: str) -> Generator[DockerContainer, None, None]:
    with TomodachiContainer(testcontainer_image).with_command(
        "tomodachi run readme/hello.py --production"
    ) as container:
        yield container


@pytest.mark.asyncio(loop_scope="session")
async def test_hello_testcontainers(tomodachi_container: TomodachiContainer) -> None:
    async with httpx.AsyncClient(base_url=tomodachi_container.get_external_url()) as client:
        response = await client.get("/hello", params={"name": "Testcontainers"})

    assert response.status_code == 200
    assert response.json() == {"message": "Hello, Testcontainers!"}

Metadata

Release files for tomodachi-testcontainers 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tomodachi-testcontainers 2.0.0
File	Size	Uploaded
tomodachi_testcontainers-2.0.0.tar.gz	3.4 MB	Jun 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for tomodachi-testcontainers 2.0.0
File	Interpreter	ABI	Platform	Reset
tomodachi_testcontainers-2.0.0-py3-none-any.whl 32.6 kB Jun 14, 2026	Python 3	none	any	Details

Total release size: 3.4 MB

Release files / tomodachi_testcontainers-2.0.0.tar.gz

Download URL	tomodachi_testcontainers-2.0.0.tar.gz
Size	3.4 MB
Tags	Source
SHA-256 checksum How to use checksums	`c0cd0c027e5475a00ca80a8a7cbacc70baff14dfc106a56ce10ea2ed87572994`
BLAKE2b-256 checksum How to use checksums	`ab860a118a67f938090590b745339c01ac1083ef008176343a7a18bd5abf5b4b`
Upload date	Jun 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.9`

Release files / tomodachi_testcontainers-2.0.0-py3-none-any.whl

Download URL	tomodachi_testcontainers-2.0.0-py3-none-any.whl
Size	32.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`aa4151444967056a21809f21942fd27b98cd46445ac7da3a1d7535273cfcec3a`
BLAKE2b-256 checksum How to use checksums	`a869e469999a2ac700572f4023c10e64983c4a96aa3d792bcf4df5a6c3d919e5`
Upload date	Jun 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.9`