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