NAME

IPC::Manager::Test - Reusable protocol-agnostic test suite for IPC::Manager

DESCRIPTION

This module provides a set of standard tests that verify the correctness of an IPC::Manager protocol implementation. Each test is an ordinary method whose name begins with test_; they are discovered automatically by tests() and executed by run_all().

Protocol test files typically look like:

use Test2::V1 -ipP;
use Test2::IPC;
use IPC::Manager::Test;
IPC::Manager::Test->run_all(protocol => 'AtomicPipe');
done_testing;

METHODS

IPC::Manager::Test->run_all(protocol => $PROTOCOL)

Run every test_* method as an isolated subtest. Each test is forked into its own process so that failures and resource leaks cannot affect sibling tests. protocol is required and is set as the default protocol via ipcm_default_protocol before any test runs.

@names = IPC::Manager::Test->tests

Returns a sorted list of all test_* method names defined on the class (or a subclass). Used internally by run_all.

IPC::Manager::Test->test_generic

Tests the low-level IPC bus: spawning a store, connecting multiple clients, sending point-to-point and broadcast messages, verifying message contents and ordering, and checking that per-client statistics are accurate on disconnect.

IPC::Manager::Test->test_simple_service

Tests ipcm_service at the single-service level: starts a named service, sends a request to it from the parent process, verifies the service echoes a response back with the correct content, and confirms that both sides observed the exchange.

IPC::Manager::Test->test_nested_services

Tests the nested-service code path where ipcm_service is called from inside a running service. An outer service starts an inner service during its on_start callback, then acts as a transparent proxy: each request received from the test process is forwarded to the inner service, and the inner service's response is returned to the caller with an identifying prefix. The test verifies the full two-hop request/response chain.

IPC::Manager::Test->test_exec_service

Tests the exec code path of ipcm_service. Instead of running the service in a forked child, the child calls exec() to start a fresh Perl interpreter that loads IPC::Manager::Service::State and deserialises the service parameters from @ARGV. The test starts IPC::Manager::Service::Echo via exec, sends a request, and verifies the echoed response.

IPC::Manager::Test->test_workers

Tests the ipcm_worker facility. A service spawns two workers during on_start: a short-lived worker that writes a marker file and exits, and a long-lived worker that sleeps indefinitely. The test verifies that both workers run, that the service tracks them via workers(), and that terminate_workers() kills the long-lived worker when the service shuts down.

IPC::Manager::Test->test_suspend_and_reconnect

Tests the suspend/reconnect lifecycle. A client suspends (preserving its slot on the bus), messages are sent to it while it is away, and then it reconnects and verifies that both the pre-suspend and during-suspend messages are received. Skipped for protocols that do not support reconnect (e.g. AtomicPipe).

IPC::Manager::Test->test_sync_request

Tests synchronous (blocking) request/response via $handle->sync_request. Sends a single request and verifies the returned response without using callbacks.

IPC::Manager::Test->test_multiple_requests

Sends five concurrent requests to a service using callback-based send_request, awaits all responses with await_all_responses, and verifies that every response arrived with the correct content.

IPC::Manager::Test->test_handle_messages_buffer

Tests the Handle's non-response message buffer. A service sends both a response and a plain (non-response) notification for the same request. The test verifies the response is delivered via the callback and the notification lands in $handle->messages.

IPC::Manager::Test->test_service_callbacks

Exercises the on_interval, on_peer_delta, on_cleanup, and should_end service callbacks in a single service. Verifies that on_interval fires periodically, on_peer_delta fires when a new peer connects, should_end terminates the service when its condition becomes true, and on_cleanup runs during shutdown.

IPC::Manager::Test->test_service_signal_handling

Tests the on_sig callback by starting a service that intercepts SIGUSR1, sending the signal from the test process, and verifying the handler ran.

IPC::Manager::Test->test_peer_active

Tests $client->peer_active by connecting two clients and verifying each sees the other as active. Also verifies that a nonexistent peer name returns false.

IPC::Manager::Test->test_disconnect_with_handler

Tests the disconnect handler callback. Sends messages to a client then disconnects it with a handler; verifies the handler receives the pending messages instead of producing a warning.

IPC::Manager::Test->test_try_message

Tests try_message in both scalar and list context for both the success path (message delivered) and the failure path (nonexistent peer).

IPC::Manager::Test->test_general_messages_to_service

Sends a plain (non-request, non-response) message to a service and verifies that on_general_message is invoked with the correct content.

IPC::Manager::Test->test_intercept_errors

Starts a service with intercept_errors => 1, sends a request that triggers an exception in the handler, then sends a second request to verify the service survived and continued processing.

IPC::Manager::Test->test_watch_pids

Tests the watch_pids mechanism. A child process starts a service that watches the child's own PID. The child exits, and the test verifies that the service detected the death and ran its cleanup callback.

IPC::Manager::Test->test_spawn_terminate_with_signal

Tests that Spawn::terminate sends a signal to service processes when the spawn has a signal configured. Verifies the service's on_sig handler fires for the delivered signal.

IPC::Manager::Test->test_cleave

Tests Spawn::cleave by double-forking ownership of the IPC bus away from the current process. Verifies the parent receives the new owner's PID, spawn ownership transfers, and the bus remains functional.

IPC::Manager::Test->test_request_error_generic

Tests that an exception in handle_request sends an error response with ipcm_error set to a generic message ("Internal service error") and response set to undef. Verifies the service continues operating after the error. This is the default behaviour (expose_error_details off).

IPC::Manager::Test->test_request_error_detailed

Tests that with expose_error_details => 1 an exception in handle_request sends an error response whose ipcm_error contains the actual exception text. Verifies the service continues operating.

SOURCE

The source code repository for IPC::Manager can be found at https://github.com/exodist/IPC-Manager.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See https://dev.perl.org/licenses/