Test::Net::LDAP::Mock - A mock LDAP client with simulated search in memory

Description

Overview
"Test::Net::LDAP::Mock" provides all the operations of "Net::LDAP", while they are performed in memory
with fake data that are set up just for testing.

It is 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. 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.

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.

LDAPSchema
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.

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

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".

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

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

   mock_data
       Retrieves the currently associated data tree (for the internal purpose only).

   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.

       This should be set up as part of the test fixture before any successive call to the "root_dse()" method,
       since Net::LDAP will cache the returned object.

           $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'.

   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.

       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".

   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.

       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).

           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.

   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.

   unbind
       Returns a success message.

   abandon
       Returns a success message.

perl v5.34.0                                       2022-06-28                         Test::Net::LDAP::Mock(3pm)

Name

       Test::Net::LDAP::Mock - A mock LDAP client with simulated search in memory

Synopsis

       All the LDAP operations are performed in memory, instead of connecting to the real LDAP server.

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

       "Test::Net::LDAP::Mock" is a subclass of Test::Net::LDAP, which is a subclass of Net::LDAP.

       In the actual test code, "ldap_mockify" in Test::Net::LDAP::Util should be used to mock all the
       "Net::LDAP" instances in your application code.

           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.

       Below is an example to set up some fake data for particular test cases.

           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();
           };

       "Test::Net::LDAP::Mock" maintains a shared LDAP directory tree for the same host/port, while it separates
       the directory trees for different host/port combinations.  Thus, it is important to specify a correct
       server location consistently.