Net::DB...nnection(3)

💅 Net::DBus::Test::MockConnection — the perl manual page (perl v5.42.0 vibes)

okay so bestie, we're reading the Net::DBus::Test::MockConnection(3) page today and honestly? it's a whole mood. it's giving "fake it till you make it" but for message buses ✨

---

🎀 NAME

Net::DBus::Test::MockConnection — literally fakes a connection to the bus so you can do unit testing 🫶

---

🌸 SYNOPSIS

use Net::DBus;

my $bus = Net::DBus->test

# Register a service, and the objec to be tested
use MyObject
my $service = $bus->export_service("org.example.MyService");
my $object = MyObject->new($service);

# Acquire the service & do tests
my $remote_service = $bus->get_service('org.example.MyService');
my $remote_object = $service->get_object("/org/example/MyObjct");

# This traverses the mock connection, eventually
# invoking 'testSomething' on the $object above.
$remote_object->testSomething()

(no, we did not fix the typos, they're iconic and they're staying 💀 copy it exactly as is, iykyk)

---

💖 DESCRIPTION

so this object is out here providing a fake implementation of Net::DBus::Binding::Connection, which lets you mock up a pure "in-memory" message bus. lowkey genius. the whole point is to make it easy to write unit tests for services that would otherwise have to call out to some other object on a live message bus — which, no cap, is a whole hassle 🙈

it's the companion to the Net::DBus::Test::MockObject module, and that module is literally how you supply the fake objects on the fake bus. bestie duo behavior fr fr 👑

---

🦋 METHODS

• my $con = Net::DBus::Test::MockConnection->new() — creates a fresh new mock connection object instance. ngl you usually don't need to make instances of this directly — instead just use the "test" method on the Net::DBus object to get yourself a handle to a test bus. slay.
• $con->send($message) — sends a message over the mock connection. here's the tea on what happens next ☕:
  • if the message is a method call, it gets dispatched straight to any corresponding mock object that's registered
  • if it's an error or a method return, it becomes available as a return value for the "send_with_reply_and_block" method
  • if it's a signal, it gets queued up for processing by the "dispatch" method
• $bus->request_name($service_name) — pretends to send a request to the bus registering the well-known name given in the $service_name parameter. in reality? it's just a no-op. it's giving "yes bestie you're registered" energy while doing absolutely nothing 💅
• my $reply = $con->send_with_reply_and_block($msg) — sends a message over the mock connection and waits for a reply. $msg should be an instance of "Net::DBus::Binding::Message::MethodCall", and the returned $reply will be an instance of "Net::DBus::Binding::Message::MethodReturn". also possible: an error gets thrown, and that thrown error is blessed into the "Net::DBus::Error" class 😭 so like, be ready for that.
• $con->dispatch; — dispatches any pending messages in the incoming queue to their message handlers. test suites should call this whenever they anticipate there are pending signals to be dealt with. it's the "go handle your business" method 🎀
• $con->add_filter($coderef); — adds a filter to the connection that gets invoked whenever a message is received. the $coderef should be a reference to a subroutine, and that sub returns a true value if the message should be filtered out, or a false value if normal message dispatch should be performed. gatekeeping, but make it code ⭐
• $bus->add_match($rule) — registers a signal match rule with the bus controller, letting matching broadcast signals be routed to this client. in reality? another no-op, just vibing and giving the impression that the match was successfully registered ✨
• $bus->remove_match($rule) — unregisters a signal match rule with the bus controller, preventing further broadcast signals from being routed to this client. in reality? you guessed it — a no-op giving the impression that the match was successfully unregistered 💀
• $con->register_object_path($path, \&handler) — registers a handler for messages whose path matches whatever's in the $path parameter. the supplied code reference gets invoked with two parameters: the connection object the message was received on, and the message to be processed (an instance of the "Net::DBus::Binding::Message" class). two parameters, no more, no less 🫶
• $con->register_fallback($path, \&handler) — same deal, but for messages whose path starts with the prefix given in $path. the code reference again gets invoked with two parameters: the connection object the message was received on, and the message to be processed (an instance of the "Net::DBus::Binding::Message" class). it's the catch-all bestie 🌈
• $con->unregister_object_path($path) — unregisters the handler associated with the object path $path. that handler would previously have been registered with the "register_object_path" or "register_fallback" methods. closure era 🦋
• my $msg = $con->make_error_message($replyto, $name, $description) — creates a new message representing an error that occurred while handling the method call object passed in as the $replyto parameter. the $name parameter is the formal name of the error condition, and $description is a short piece of text giving more specific info about the error. very "here's what went wrong, bestie" 😭
• my $call = $con->make_method_call_message( $service_name, $object_path, $interface, $method_name); — creates a message representing a call on the object located at the path $object_path within the client owning the well-known name given by $service_name. the method to be invoked has the name $method_name within the interface specified by the $interface parameter. four params, all accounted for 👑
• my $msg = $con->make_method_return_message($replyto) — creates a message representing a reply to the method call message passed in the $replyto parameter. the "ok bestie i heard you" of messages 💌
• my $msg = $con->make_signal_message($object_path, $interface, $signal_name); — creates a new message representing a signal [to be] emitted by the object located under the path given by $object_path. the name of the signal is given by $signal_name, and it's scoped to the interface given by $interface. shout it from the rooftops, but politely, within the right interface 📣

---

💀 BUGS

it doesn't completely replicate the API of Net::DBus::Binding::Connection — merely enough to make the high level bindings work in a test scenario. so like, it's not a full clone, it's a vibe match. don't come for it 🙈

---

🧚 AUTHOR

Daniel P. Berrange

---

⭐ COPYRIGHT

Copyright (C) 2005-2009 Daniel P. Berrange

---

🔥 SEE ALSO

• Net::DBus
• Net::DBus::Test::MockObject
• Net::DBus::Binding::Connection
• <http://www.mockobjects.com/Faq.html>

---

and that's the whole page bestie, no notes 💅

this has been Net::DB...nnection(3) from the User Contributed Perl Documentation, perl v5.42.0, dated 2019-12-17 — mwah, go write some tests 🎀✨