mirakuru

What it is and what it does

Mirakuru is a process orchestration library for functional and integration tests. It solves the problem of coordinating startup of external services—databases, message queues, APIs, web servers—by starting them and blocking until they signal readiness (via TCP connection, HTTP response, output banner, Unix socket, or .pid file) before your test code runs. This eliminates race conditions where tests try to connect to a service that hasn't finished initializing.

The library provides seven executor classes for different readiness signals: SimpleExecutor (no wait), OutputExecutor (watches stdout for a marker), TCPExecutor (tries TCP connection), HTTPExecutor (checks HTTP status), UnixSocketExecutor (Unix socket readiness), PidExecutor (waits for .pid file), and a base Executor class. Each executor wraps a command string or list, starts the process, polls for readiness, and provides start() and stop() methods. Executors also work as context managers for cleaner test setup/teardown.

Use it for:

• Start a PostgreSQL container in a test and wait until it accepts connections before running integration tests.
• Launch an HTTP API server and verify it responds to requests before running end-to-end tests.
• Orchestrate multiple services (Redis, Elasticsearch, a custom daemon) in a single test fixture with guaranteed startup order.
• Monitor a process's stdout for a 'ready' message and proceed only when that marker appears.
• Manage test cleanup by stopping all spawned processes in the correct order when tests complete.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Mirakuru starts external processes (databases, services, APIs) and waits until they are ready to accept connections or produce specific output before returning control to your code.

Yes. Mirakuru is actively maintained, has no security vulnerabilities, low install friction, and solves a genuine testing problem—eliminating flaky tests caused by timing races with external services. It is well-suited for integration and functional test suites that depend on external processes.

Install

mirakuru on PyPI

pip install mirakuru

uv add mirakuru

poetry add mirakuru

Installing mirakuru

Before you install

Low friction: pure Python wheel with a single runtime dependency (psutil). Active maintenance with recent release (2026-02-11) and no known vulnerabilities.

License in practice

LGPL-3.0-or-later (copyleft): you may use this in proprietary code, but modifications to mirakuru itself must be shared under the same license.

Quickstart

from mirakuru import TCPExecutor

redis = TCPExecutor('redis-server', host='localhost', port=6379)
redis.start()
# Redis is now ready
redis.stop()

Requires Python 3.10 or later; the external process being orchestrated must be installed and on PATH.

Verify before relying

• Whether psutil is always available on all supported platforms or if there are OS-specific limitations.
• Timeout behavior and configurability when a process fails to reach readiness state.

Package facts

Evidence: mirakuru-3.0.2-py3-none-any.whl

Keywords: process, executor, tests, orchestration

Tags

More Python Modules packages