{"id":2119,"library":"mirakuru","title":"Mirakuru","description":"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.","status":"active","version":"3.0.2","language":"en","source_language":"en","source_url":"https://github.com/dbfixtures/mirakuru","tags":["process","executor","orchestration","testing","subprocess","integration tests","functional tests"],"install":[{"cmd":"pip install mirakuru","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"TCPExecutor","correct":"from mirakuru import TCPExecutor"},{"symbol":"HTTPExecutor","correct":"from mirakuru import HTTPExecutor"},{"symbol":"OutputExecutor","correct":"from mirakuru import OutputExecutor"},{"note":"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.","wrong":"from mirakuru import StartCheckExecutor","symbol":"Executor","correct":"from mirakuru import Executor"},{"note":"The original `Executor` class, which only started/stopped a process without waiting for readiness, was renamed to `SimpleExecutor` in version 0.5.0.","wrong":"from mirakuru import Executor","symbol":"SimpleExecutor","correct":"from mirakuru import SimpleExecutor"}],"quickstart":{"code":"import subprocess\nimport time\nfrom mirakuru import TCPExecutor\n\n# This simulates a simple HTTP server. In a real scenario, this would be your external service.\nserver_process = None\ntry:\n    # Start a simple Python HTTP server in the background\n    server_process = subprocess.Popen(['python', '-m', 'http.server', '8000'], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)\n    \n    # Use TCPExecutor to wait for the server to be ready on port 8000\n    http_executor = TCPExecutor('echo server_started', host='localhost', port=8000)\n    \n    print(\"Waiting for HTTP server to start...\")\n    http_executor.start()\n    print(\"HTTP server is ready on port 8000.\")\n    \n    # Your application or test code that interacts with the server would go here.\n    # For demonstration, we'll just wait a bit.\n    time.sleep(2)\n    \n    print(\"Stopping HTTP server.\")\n    http_executor.stop()\n    print(\"HTTP server stopped.\")\nfinally:\n    if server_process:\n        server_process.terminate()\n        server_process.wait()\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to version 3.10 or higher.","message":"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.","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"Employ context managers (`with`) or ensure `.stop()` is called in a `try...finally` block.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}