mirakuru

library3.0.2pypypi✓ verified 24d ago

Mirakuru is a Python library designed for process orchestration, primarily used in functional and integration tests. It facilitates starting and stopping external processes (such as databases, APIs, or other services) and waiting for a clear indication that they are ready before allowing the main application or test suite to proceed. The library is currently at version 3.0.2 and is actively maintained, with releases typically addressing bug fixes, enhancements, and compatibility updates.

testing devops workflow

pip install mirakuru

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · MIRAKURU

mirakuru

testingpythonv3.0.2

Install

1.7s avg

Import

145ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.154s · 18.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.136s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TCPExecutor

✓ from mirakuru import TCPExecutor

HTTPExecutor

✓ from mirakuru import HTTPExecutor

OutputExecutor

✓ from mirakuru import OutputExecutor

Executor

✓ from mirakuru import Executor

✗ from mirakuru import StartCheckExecutor

The `StartCheckExecutor` class was renamed to `Executor` in version 0.5.0. New code should use `Executor` as the base class for executors that verify process startup.

SimpleExecutor

✓ from mirakuru import SimpleExecutor

✗ from mirakuru import Executor

The original `Executor` class, which only started/stopped a process without waiting for readiness, was renamed to `SimpleExecutor` in version 0.5.0.

This quickstart demonstrates how to use `TCPExecutor` to ensure a local HTTP server (simulated here with Python's built-in `http.server`) is ready to accept connections on a specific port before proceeding. It also shows proper cleanup. Mirakuru's executors can also be used as context managers for automatic startup and shutdown.

import subprocess import time from mirakuru import TCPExecutor # This simulates a simple HTTP server. In a real scenario, this would be your external service. server_process = None try: # Start a simple Python HTTP server in the background server_process = subprocess.Popen(['python', '-m', 'http.server', '8000'], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) # Use TCPExecutor to wait for the server to be ready on port 8000 http_executor = TCPExecutor('echo server_started', host='localhost', port=8000) print("Waiting for HTTP server to start...") http_executor.start() print("HTTP server is ready on port 8000.") # Your application or test code that interacts with the server would go here. # For demonstration, we'll just wait a bit. time.sleep(2) print("Stopping HTTP server.") http_executor.stop() print("HTTP server stopped.") finally: if server_process: server_process.terminate() server_process.wait()

Debug

Known issues

breakingMirakuru 3.x requires Python >=3.10. Older Python versions (e.g., Python 2.x, 3.6-3.9) are not supported. Users migrating from older Mirakuru versions or older Python environments will need to upgrade their Python interpreter.

fix

Upgrade Python to version 3.10 or higher.

affects: <3.0.0

gotchaAlways ensure processes started by Mirakuru are properly stopped to prevent orphaned processes. This is best achieved by using executors as context managers (`with TCPExecutor(...) as executor:`) or by explicitly calling the `.stop()` method in a `finally` block.

fix

Employ context managers (`with`) or ensure `.stop()` is called in a `try...finally` block.

affects: All

gotchaWhen using `TCPExecutor` or `HTTPExecutor`, an `AlreadyRunning` exception will be raised if the target port is already in use by another process before Mirakuru attempts to start its own. This indicates a conflict or a lingering process.

fix

Ensure the target port is free before starting the executor, or handle the `AlreadyRunning` exception appropriately (e.g., by checking if the existing process is the intended one).

affects: All

gotchaHandling subprocesses, especially when `shell=True` is used, requires careful attention to ensure all child processes are terminated. While Mirakuru includes mechanisms for cleanup, complex shell commands or external processes that spawn their own children might require additional manual cleanup or OS-level process management.

fix

Prefer passing commands as a list of arguments rather than a single string with `shell=True` where possible. Verify process tree termination in integration tests for complex scenarios.

affects: All

Errors

Common errors & fixes

mirakuru.exception.AlreadyRunning: Port 1234 is already in use.

This error occurs when a `TCPExecutor` or `HTTPExecutor` attempts to start a process, but the specified `host` and `port` are already in use by another process on the system.

fix

Ensure that the port is free before starting the `mirakuru` executor, or configure your process to use a different available port. You can check port availability using tools like `lsof -i :PORT` (Linux/macOS) or `netstat -ano | findstr :PORT` (Windows).

TimeoutError: Process did not become ready in X seconds.

This error indicates that the process started by `mirakuru` did not meet its readiness criteria (e.g., producing a specific output, opening a TCP port, or responding to an HTTP request) within the allotted timeout period.

fix

Increase the `timeout` parameter when initializing the `Executor` (e.g., `executor = OutputExecutor('my_command', timeout=60)`), or investigate why your subprocess is taking longer to start or become ready. Ensure the readiness check parameters (e.g., `banner` for `OutputExecutor`, `port` for `TCPExecutor`, `url` for `HTTPExecutor`) are correctly configured.

FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_command'

This error occurs when `mirakuru` tries to execute the command string or list you provided, but the executable specified in the `command` argument cannot be found in the system's PATH or at the specified absolute/relative path.

fix

Verify that the command string points to a valid executable, including its full path if it's not in the system's PATH. For example, if 'my_server' is in your current directory, use `'./my_server'` or the absolute path.

OSError: [Errno 13] Permission denied: './my_script.sh'

This error occurs when `mirakuru` attempts to execute a command, but the user running the Python script does not have sufficient permissions to execute the specified file or script.

fix

Ensure that the executable file or script passed to `mirakuru.Executor` has execute permissions for the user running the Python script. On Linux/macOS, you can grant execute permissions using `chmod +x ./my_script.sh`.

Upgrade

Version history

3.0.2latest on PyPI · released Feb 11, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dbfixtures/mirakuru ↗

packagehttps://pypi.org/project/mirakuru/ ↗

changeloghttps://github.com/dbfixtures/mirakuru/blob/v3.0.2/CHANGES.rst ↗