Mirakuru

3.0.2 · active · verified Thu Apr 09

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.

Warnings

breaking Mirakuru 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.
gotcha Always 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.
gotcha When 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).
gotcha Handling 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.

Install

pip install mirakuru Install latest version

Imports

TCPExecutor
```
from mirakuru import TCPExecutor
```
HTTPExecutor
```
from mirakuru import HTTPExecutor
```
OutputExecutor
```
from mirakuru import OutputExecutor
```
Executor
```
from mirakuru import Executor
```
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
```
The original `Executor` class, which only started/stopped a process without waiting for readiness, was renamed to `SimpleExecutor` in version 0.5.0.

Quickstart

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()

view raw JSON →