Overview

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

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

new

    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

mock_schema

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

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

    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

    $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

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

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

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

compare

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

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

add

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

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

modify

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

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

delete

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

See "delete" in Net::LDAP for more parameter usage.

moddn

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

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

bind

unbind

abandon