Description

.. image:: https://raw.githubusercontent.com/dbfixtures/mirakuru/master/logo.png :height: 100px mirakuru ======== Mirakuru is a process orchestration tool designed for functional and integration tests. When your application or tests rely on external processes (like databases, APIs, or other services), ensuring these processes are started and ready *before* your main code executes can be challenging. **Mirakuru** solves this by orchestrating the startup of these processes and waiting until they are fully operational (e.g., accepting connections, producing specific output) before allowing your program or tests to continue. .. image:: https://img.shields.io/pypi/v/mirakuru.svg :target: https://pypi.python.org/pypi/mirakuru/ :alt: Latest PyPI version .. image:: https://img.shields.io/pypi/wheel/mirakuru.svg :target: https://pypi.python.org/pypi/mirakuru/ :alt: Wheel Status .. image:: https://img.shields.io/pypi/pyversions/mirakuru.svg :target: https://pypi.python.org/pypi/mirakuru/ :alt: Supported Python Versions .. image:: https://img.shields.io/pypi/l/mirakuru.svg :target: https://pypi.python.org/pypi/mirakuru/ :alt: License Installation ------------ Install mirakuru using pip: .. code-block:: bash pip install mirakuru Quick Start ----------- Here's a simple example showing how mirakuru ensures a Redis server is ready before your code runs: .. code-block:: python from mirakuru import TCPExecutor # Start Redis server and wait until it accepts connections on port 6379 redis_executor = TCPExecutor('redis-server', host='localhost', port=6379) redis_executor.start() # Redis is now running and ready to accept connections # ... your code that uses Redis here ... # Clean up - stop the Redis server redis_executor.stop() The key benefit: ``start()`` blocks until Redis is actually ready, so you never try to connect too early. Usage ----- In projects that rely on multiple processes, there might be a need to guard code with tests that verify interprocess communication. You need to set up all the required databases, auxiliary and application services to verify their cooperation. Synchronizing (or orchestrating) test procedures with tested processes can be challenging. If so, then **mirakuru** is what you need. ``Mirakuru`` starts your process and waits for a clear indication that it's running. The library provides seven executors to fit different cases: .. list-table:: :header-rows: 1 :widths: 25 75 * - Executor - Use When * - **SimpleExecutor** - You just need to start/stop a process without waiting for readiness. Base class for all other executors. * - **Executor** - Base class for executors that verify process startup. * - **OutputExecutor** - Your process prints a specific message when ready (e.g., "Server started on port 8080") * - **TCPExecutor** - Your process opens a TCP port when ready (e.g., Redis, PostgreSQL, Memcached) * - **UnixSocketExecutor** - Your process opens a Unix socket when ready (e.g., Docker daemon, some databases) * - **HTTPExecutor** - Your process serves HTTP requests when ready (e.g., web servers, REST APIs) * - **PidExecutor** - Your process creates a .pid file when ready (e.g., traditional Unix daemons) SimpleExecutor ++++++++++++++ The simplest executor implementation. It simply starts the process passed to constructor, and reports it as running. .. code-block:: python from mirakuru import SimpleExecutor process = SimpleExecutor('my_special_process') process.start() # Here you can do your stuff, e.g. communicate with the started process process.stop() OutputExecutor ++++++++++++++ OutputExecutor starts a process and monitors its output for a specific text marker (banner). The process is not reported as started until this marker appears in the output. .. code-block:: python from mirakuru import OutputExecutor process = OutputExecutor('my_special_process', banner='processed!') process.start() # Here you can do your stuff, e.g. communicate with the started process process.stop() What happens during start here, is that the executor constantly checks output produced by started process, and looks for the banner part occurring within the output. Once the output is identified, as in example `processed!` is found in output. It is considered as started, and executor releases your script from wait to work. TCPExecutor +++++++++++ TCPExecutor should be used to start processes that communicate over TCP connections. This executor tries to connect to the process on the specified host and port to check if it started accepting connections. Once it successfully connects, the process is reported as started and control returns to your code. .. code-block:: python from mirakuru import TCPExecutor process = TCPExecutor('my_special_process', host='localhost', port=1234) proce