Test::...P::Mock(3pm)

🌸 Test::Net::LDAP::Mock 🌸

Hiii bestie, welcome to the mock LDAP page 💅 This one lives in the User Contributed Perl Documentation corner of your man pages, and it's genuinely so useful. Let's get into it.

---

✨ NAME ✨

Test::Net::LDAP::Mock — it's a mock LDAP client 🦋 with simulated search in memory. No server, no network, no drama. Periodt.

---

🎀 SYNOPSIS 🎀

Okay so the whole point: all the LDAP operations happen in memory, instead of connecting to the real LDAP server. Iconic behaviour honestly.

use Test::Net::LDAP::Mock;
my $ldap = Test::Net::LDAP::Mock->new();

So <cyan>Test::Net::LDAP::Mock</cyan> is a subclass of Test::Net::LDAP, which is itself a subclass of Net::LDAP. Family tree, slay 🌈

But in your actual test code, you should use ldap_mockify from Test::Net::LDAP::Util to mock all the Net::LDAP instances in your application code. That's the move:

use Test::More tests => 1;
use Test::Net::LDAP::Util qw(ldap_mockify);

ldap_mockify {
    # Anywhere in this block, all the occurrences of Net::LDAP::new are
    # replaced by Test::Net::LDAP::Mock::new
    ok my_application_routine();
};

Note: if no LDAP entries have been added to the in-memory directory, the search method will silently succeed with no entries found. Not an error. Just... nothing. 💀

Below is an example to set up some fake data for particular test cases. Look at her go 🫶

use Test::More tests => 1;
use Test::Net::LDAP::Util qw(ldap_mockify);

ldap_mockify {
    my $ldap = Net::LDAP->new('ldap.example.com');

    $ldap->add('uid=user1, ou=users, dc=example, dc=com');
    $ldap->add('uid=user2, ou=users, dc=example, dc=com');
    $ldap->add('cn=group1, ou=groups, dc=example, dc=com', attrs => [
        member => [
            'uid=user1, ou=users, dc=example, dc=com',
            'uid=user2, ou=users, dc=example, dc=com',
        ]
    ]);

    ok my_application_routine();
};

And here's a detail that lowkey matters a lot: <purple>Test::Net::LDAP::Mock</purple> maintains a shared LDAP directory tree for the same host/port, while it separates the directory trees for different host/port combinations. So bestie, it is important to specify a correct server location consistently. Don't be sloppy about it 🙈

---

💜 DESCRIPTION 💜

🌟 Overview 🌟

Test::Net::LDAP::Mock provides all the operations of Net::LDAP, except they're performed in memory with fake data that you set up just for testing. It's giving ✨full API, zero server✨.

It's most useful for developers who write testing for an application that uses LDAP search, while they do not have full control over the organizational LDAP server. Because real talk: in many cases, developers do not have write access to the LDAP data, and the organizational information changes over time, which makes it difficult to write stable test cases with LDAP. Test::Net::LDAP::Mock helps developers set up any fake LDAP directory tree in memory, so that they can test sufficient varieties of senarios for the application. Main character energy for your test suite, fr fr 👑

Without this module, an alternative way to test an application using LDAP is to run a real server locally during testing. (See how Net::LDAP is tested with a local OpenLDAP server.) However, it may not be always trivial to set up such a server with correct configurations and schemas — where this module makes testing easier. And honestly? Not the vibe to fight schemas at 2am. 💅

🦋 LDAP Schema 🦋

In the current version, the LDAP schema is ignored when entries are added or modified, although a schema can optionally be specified only for the search filter matching (based on Net::LDAP::FilterMatch).

• An advantage is that it is much easier to set up fake data with any arbitrary LDAP attributes than to care about all the restrictions with the schema.
• A disadvantage is that it cannot test schema-sensitive cases.

Balance, bestie ⚖️

🎀 Controls 🎀

LDAPv3 controls are not supported (yet). The control parameter given as an argument of a method will be ignored. Sorry babes 😭

---

👑 METHODS 👑

new

Creates a new object. It does not connect to the real LDAP server. Each object is associated with a shared LDAP data tree in memory, depending on the target (host/port/path) and scheme (ldap/ldaps/ldapi).

Test::Net::LDAP::Mock->new();
Test::Net::LDAP::Mock->new('ldap.example.com', port => 3389);

mockify

Test::Net::LDAP::Mock->mockify(sub {
    # CODE
});

Inside the code block (recursively), all the occurrences of Net::LDAP::new are replaced by Test::Net::LDAP::Mock::new. Recursively. All of them. Obsessed 🫶

Subclasses of Net::LDAP are also mockified. Test::Net::LDAP::Mock is inserted into @ISA of each subclass, only within the context of mockify. Sneaky but polite.

See also: ldap_mockify in Test::Net::LDAP::Util.

mock_data

Retrieves the currently associated data tree (for the internal purpose only). iykyk — it's an internals thing 🙈

mock_schema

Gets or sets the LDAP schema (Net::LDAP::Schema object) for the currently associated data tree.

In this version, the schema is used only for the search filter matching (based on Net::LDAP::FilterMatch internally). It has no effect for any modification operations such as add, modify, and delete.

mock_root_dse

Gets or sets the root DSE (Net::LDAP::RootDSE) for the currently associated data tree.

Set this up as part of the test fixture before any successive call to the root_dse() method, since Net::LDAP will cache the returned object. Caching, bestie. It will not forget. 💀

$ldap->mock_root_dse(
    namingContexts => 'dc=example,dc=com'
);

Note: the namingContexts value has no effect on the restriction with the topmost DN. In other words, even if namingContexts is set to 'dc=example,dc=com', the add() method still allows you to add an entry to 'dc=somewhere-else'. Yes, really. Not me exposing this 🙈

mock_bind

Gets or sets a LDAP result code (and optionally a message) that will be used as a message returned by a later bind() call.

use Net::LDAP::Constant qw(LDAP_INVALID_CREDENTIALS);
$ldap->mock_bind(LDAP_INVALID_CREDENTIALS);
$ldap->mock_bind(LDAP_INVALID_CREDENTIALS, 'Login failed');
# ...
my $mesg = $ldap->bind(...);
$mesg->code && die $mesg->error; #=> die('Login failed')

In the list context, it returns an array of the code and message. In the scalar context, it returns the code only. Context is everything, periodt.

Alternatively, this method can take a callback subroutine:

$ldap->mock_bind(sub {
    my $arg = shift;
    # Validate $arg->{dn} and $arg->{password}, etc.
    if (...invalid credentials...) {
        return LDAP_INVALID_CREDENTIALS;
    }
});

The callback can return a single value as the LDAP result code or an array in the form ($code, $message). If the callback returns nothing (or undef), it is regarded as LDAP_SUCCESS. Generous queen 🌈

mock_password

Gets or sets the password for the simple password authentication with bind().

$ldap->mock_password('uid=test, dc=example, dc=com' => 'test_password');
# Caution: Passwords should usually *not* be hard-coded like this. Consider to load
# passwords from a config file, etc.

Caution: passwords should usually not be hard-coded like this. Consider to load passwords from a config file, etc. Bestie, please 😭🔐

The passwords are stored with the entry node in the data tree.

Once this method is used, the bind() call will check the credentials whenever the password parameter is passed. Anonymous binding and all the other authentication methods are not affected.

mock_target

Gets or sets the target scheme://host:port to normalize the way for successive Test::Net::LDAP::Mock objects to resolve the associated data tree.

It is useful when normalizing the target scheme://host:port for different combinations. For example, if there are sub-domains (such as ldap1.example.com and ldap2.example.com) that share the same data tree, the target host should be normalized to be the single master server (such as ldap.example.com). One tree to rule them all 👑

Test::Net::LDAP::Mock->mock_target('ldap.example.com');
Test::Net::LDAP::Mock->mock_target('ldap.example.com', port => 3389);
Test::Net::LDAP::Mock->mock_target(['ldap.example.com', {port => 3389}]);
Test::Net::LDAP::Mock->mock_target({scheme => 'ldaps', port => 3389});

Since this will affect all the successive calls to instantiate Test::Net::LDAP::Mock, it may not be ideal when your application uses connections to multiple LDAP servers. In that case, you can specify a callback that will be invoked each time a Test::Net::LDAP::Mock object is instantiated.

Test::Net::LDAP::Mock->mock_target(sub {
    my ($host, $arg) = @_;
    # Normalize $host, $arg->{port}, and $arg->{scheme}
    $host = 'ldap.example1.com' if $host =~ /\.example1\.com$/;
    $host = 'ldap.example2.com' if $host =~ /\.example2\.com$/;
    return ($host, $arg);
});

search

Searches for entries in the currently associated data tree.

$ldap->search(
    base => 'dc=example, dc=com', scope => 'sub',
    filter => '(cn=*)', attrs => ['uid', 'cn']
);

See search in Net::LDAP for more parameter usage. 🔍

compare

Compares an attribute/value pair with an entry in the currently associated data tree.

$ldap->compare('uid=test, dc=example, dc=com',
    attr => 'cn',
    value => 'Test'
);

See compare in Net::LDAP for more parameter usage.

add

Adds an entry to the currently associated data tree.

$ldap->add('uid=test, dc=example, dc=com', attrs => [
    cn => 'Test'
]);

See add in Net::LDAP for more parameter usage.

modify

Modifies an entry in the currently associated data tree.

$ldap->modify('uid=test, dc=example, dc=com', add => [
    cn => 'Test2'
]);

See modify in Net::LDAP for more parameter usage.

delete

Deletes an entry from the currently associated data tree.

$ldap->delete('uid=test, dc=example, dc=com');

See delete in Net::LDAP for more parameter usage. Gone. Poof. 🦋

moddn

Modifies DN of an entry in the currently associated data tree.

$ldap->moddn('uid=test, dc=example, dc=com',
    newrdn => 'uid=test2'
);

See moddn in Net::LDAP for more parameter usage.

bind

Returns an expected result message if the bind result has previously been setup by the mock_bind() method. Otherwise, a success message is returned. Either way you get something, bestie 🫶

unbind

Returns a success message. That's it, that's the whole method ✨

abandon

Returns a success message. Also the whole method. Living the dream 💅

---

And that's the page, babe! 🎀 This was from the User Contributed Perl Documentation collection, and the footer says perl v5.34.0, dated 2022-06-28. Go mock some LDAP, you absolute icon 👑💖