.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Test::Net::LDAP::Mock 3pm"
.TH Test::Net::LDAP::Mock 3pm "2015-03-24" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::Net::LDAP::Mock \- A mock LDAP client with simulated search in memory
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
All the \s-1LDAP\s0 operations are performed in memory, instead of connecting to the
real \s-1LDAP\s0 server.
.PP
.Vb 2
\&    use Test::Net::LDAP::Mock;
\&    my $ldap = Test::Net::LDAP::Mock\->new();
.Ve
.PP
\&\f(CW\*(C`Test::Net::LDAP::Mock\*(C'\fR is a subclass of Test::Net::LDAP, which is
a subclass of Net::LDAP.
.PP
In the actual test code, \*(L"ldap_mockify\*(R" in Test::Net::LDAP::Util should be used to mock
all the \f(CW\*(C`Net::LDAP\*(C'\fR instances in your application code.
.PP
.Vb 2
\&    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();
\&    };
.Ve
.PP
Note: if no \s-1LDAP\s0 entries have been added to the in-memory directory, the
\&\f(CW\*(C`search\*(C'\fR method will silently succeed with no entries found.
.PP
Below is an example to set up some fake data for particular test cases.
.PP
.Vb 2
\&    use Test::More tests => 1;
\&    use Test::Net::LDAP::Util qw(ldap_mockify);
\&    
\&    ldap_mockify {
\&        my $ldap = Net::LDAP\->new(\*(Aqldap.example.com\*(Aq);
\&        
\&        $ldap\->add(\*(Aquid=user1, ou=users, dc=example, dc=com\*(Aq);
\&        $ldap\->add(\*(Aquid=user2, ou=users, dc=example, dc=com\*(Aq);
\&        $ldap\->add(\*(Aqcn=group1, ou=groups, dc=example, dc=com\*(Aq, attrs => [
\&            member => [
\&                \*(Aquid=user1, ou=users, dc=example, dc=com\*(Aq,
\&                \*(Aquid=user2, ou=users, dc=example, dc=com\*(Aq,
\&            ]
\&        ]);
\&        
\&        ok my_application_routine();
\&    };
.Ve
.PP
\&\f(CW\*(C`Test::Net::LDAP::Mock\*(C'\fR maintains a shared \s-1LDAP\s0 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.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Overview"
.IX Subsection "Overview"
\&\f(CW\*(C`Test::Net::LDAP::Mock\*(C'\fR provides all the operations of \f(CW\*(C`Net::LDAP\*(C'\fR, while
they are performed in memory with fake data that are set up just for testing.
.PP
It is most useful for developers who write testing for an application that
uses \s-1LDAP\s0 search, while they do not have full control over the organizational
\&\s-1LDAP\s0 server.
In many cases, developers do not have write access to the \s-1LDAP\s0 data, and the
organizational information changes over time, which makes it difficult to write
stable test cases with \s-1LDAP.
\&\s0\f(CW\*(C`Test::Net::LDAP::Mock\*(C'\fR helps developers set up any fake \s-1LDAP\s0 directory tree
in memory, so that they can test sufficient varieties of senarios for the
application.
.PP
Without this module, an alternative way to test an application using \s-1LDAP\s0 is to
run a real server locally during testing. (See how \f(CW\*(C`Net::LDAP\*(C'\fR 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.
.SS "\s-1LDAP\s0 Schema"
.IX Subsection "LDAP Schema"
In the current version, the \s-1LDAP\s0 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).
.PP
An advantage is that it is much easier to set up fake data with any arbitrary
\&\s-1LDAP\s0 attributes than to care about all the restrictions with the schema.
A disadvantage is that it cannot test schema-sensitive cases.
.SS "Controls"
.IX Subsection "Controls"
LDAPv3 controls are not supported (yet).
The \f(CW\*(C`control\*(C'\fR parameter given as an argument of a method will be ignored.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Creates a new object. It does not connect to the real \s-1LDAP\s0 server.
Each object is associated with a shared \s-1LDAP\s0 data tree in memory, depending on
the target (host/port/path) and scheme (ldap/ldaps/ldapi).
.PP
.Vb 2
\&    Test::Net::LDAP::Mock\->new();
\&    Test::Net::LDAP::Mock\->new(\*(Aqldap.example.com\*(Aq, port => 3389);
.Ve
.SS "mockify"
.IX Subsection "mockify"
.Vb 3
\&    Test::Net::LDAP::Mock\->mockify(sub {
\&        # CODE
\&    });
.Ve
.PP
Inside the code block (recursively), all the occurrences of \f(CW\*(C`Net::LDAP::new\*(C'\fR
are replaced by \f(CW\*(C`Test::Net::LDAP::Mock::new\*(C'\fR.
.PP
Subclasses of \f(CW\*(C`Net::LDAP\*(C'\fR are also mockified. \f(CW\*(C`Test::Net::LDAP::Mock\*(C'\fR is inserted
into \f(CW@ISA\fR of each subclass, only within the context of \f(CW\*(C`mockify\*(C'\fR.
.PP
See also: \*(L"ldap_mockify\*(R" in Test::Net::LDAP::Util.
.SS "mock_data"
.IX Subsection "mock_data"
Retrieves the currently associated data tree (for the internal purpose only).
.SS "mock_schema"
.IX Subsection "mock_schema"
Gets or sets the \s-1LDAP\s0 schema (Net::LDAP::Schema object) for the currently
associated data tree.
.PP
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 \f(CW\*(C`add\*(C'\fR, \f(CW\*(C`modify\*(C'\fR, and
\&\f(CW\*(C`delete\*(C'\fR.
.SS "mock_root_dse"
.IX Subsection "mock_root_dse"
Gets or sets the root \s-1DSE \s0(Net::LDAP::RootDSE) for the currently associated
data tree.
.PP
This should be set up as part of the test fixture before any successive call to
the \f(CW\*(C`root_dse()\*(C'\fR method, since Net::LDAP will cache the returned object.
.PP
.Vb 3
\&    $ldap\->mock_root_dse(
\&        namingContexts => \*(Aqdc=example,dc=com\*(Aq
\&    );
.Ve
.PP
Note: the namingContexts value has no effect on the restriction with the
topmost \s-1DN.\s0 In other words, even if namingContexts is set to
\&'dc=example,dc=com', the \f(CW\*(C`add()\*(C'\fR method still allows you to add an entry to
\&'dc=somewhere\-else'.
.SS "mock_bind"
.IX Subsection "mock_bind"
Gets or sets a \s-1LDAP\s0 result code (and optionally a message) that will be used as a message
returned by a later \f(CW\*(C`bind()\*(C'\fR call.
.PP
.Vb 6
\&    use Net::LDAP::Constant qw(LDAP_INVALID_CREDENTIALS);
\&    $ldap\->mock_bind(LDAP_INVALID_CREDENTIALS);
\&    $ldap\->mock_bind(LDAP_INVALID_CREDENTIALS, \*(AqLogin failed\*(Aq);
\&    # ...
\&    my $mesg = $ldap\->bind(...);
\&    $mesg\->code && die $mesg\->error; #=> die(\*(AqLogin failed\*(Aq)
.Ve
.PP
In the list context, it returns an array of the code and message. In the scalar
context, it returns the code only.
.PP
Alternatively, this method can take a callback subroutine:
.PP
.Vb 7
\&    $ldap\->mock_bind(sub {
\&        my $arg = shift;
\&        # Validate $arg\->{dn} and $arg\->{password}, etc.
\&        if (...invalid credentials...) {
\&            return LDAP_INVALID_CREDENTIALS;
\&        }
\&    });
.Ve
.PP
The callback can return a single value as the \s-1LDAP\s0 result code or an array in the form
\&\f(CW\*(C`($code, $message)\*(C'\fR. If the callback returns nothing (or \f(CW\*(C`undef\*(C'\fR), it is regarded as
\&\f(CW\*(C`LDAP_SUCCESS\*(C'\fR.
.SS "mock_password"
.IX Subsection "mock_password"
Gets or sets the password for the simple password authentication with \f(CW\*(C`bind()\*(C'\fR.
.PP
.Vb 3
\&    $ldap\->mock_password(\*(Aquid=test, dc=example, dc=com\*(Aq => \*(Aqtest_password\*(Aq);
\&    # Caution: Passwords should usually *not* be hard\-coded like this. Consider to load
\&    # passwords from a config file, etc.
.Ve
.PP
The passwords are stored with the entry node in the data tree.
.PP
Once this method is used, the \f(CW\*(C`bind()\*(C'\fR call will check the credentials whenever the
\&\f(CW\*(C`password\*(C'\fR parameter is passed. Anonymous binding and all the other authentication
methods are not affected.
.SS "mock_target"
.IX Subsection "mock_target"
Gets or sets the target scheme://host:port to normalize the way for successive
\&\f(CW\*(C`Test::Net::LDAP::Mock\*(C'\fR objects to resolve the associated data tree.
.PP
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).
.PP
.Vb 4
\&    Test::Net::LDAP::Mock\->mock_target(\*(Aqldap.example.com\*(Aq);
\&    Test::Net::LDAP::Mock\->mock_target(\*(Aqldap.example.com\*(Aq, port => 3389);
\&    Test::Net::LDAP::Mock\->mock_target([\*(Aqldap.example.com\*(Aq, {port => 3389}]);
\&    Test::Net::LDAP::Mock\->mock_target({scheme => \*(Aqldaps\*(Aq, port => 3389});
.Ve
.PP
Since this will affect all the successive calls to instantiate \f(CW\*(C`Test::Net::LDAP::Mock\*(C'\fR,
it may not be ideal when your application uses connections to multiple \s-1LDAP\s0
servers.  In that case, you can specify a callback that will be invoked each
time a \f(CW\*(C`Test::Net::LDAP::Mock\*(C'\fR object is instantiated.
.PP
.Vb 7
\&    Test::Net::LDAP::Mock\->mock_target(sub {
\&        my ($host, $arg) = @_;
\&        # Normalize $host, $arg\->{port}, and $arg\->{scheme}
\&        $host = \*(Aqldap.example1.com\*(Aq if $host =~ /\e.example1\e.com$/;
\&        $host = \*(Aqldap.example2.com\*(Aq if $host =~ /\e.example2\e.com$/;
\&        return ($host, $arg);
\&    });
.Ve
.SS "search"
.IX Subsection "search"
Searches for entries in the currently associated data tree.
.PP
.Vb 4
\&    $ldap\->search(
\&        base => \*(Aqdc=example, dc=com\*(Aq, scope => \*(Aqsub\*(Aq,
\&        filter => \*(Aq(cn=*)\*(Aq, attrs => [\*(Aquid\*(Aq, \*(Aqcn\*(Aq]
\&    );
.Ve
.PP
See \*(L"search\*(R" in Net::LDAP for more parameter usage.
.SS "compare"
.IX Subsection "compare"
Compares an attribute/value pair with an entry in the currently associated data
tree.
.PP
.Vb 4
\&    $ldap\->compare(\*(Aquid=test, dc=example, dc=com\*(Aq,
\&        attr => \*(Aqcn\*(Aq,
\&        value => \*(AqTest\*(Aq
\&    );
.Ve
.PP
See \*(L"compare\*(R" in Net::LDAP for more parameter usage.
.SS "add"
.IX Subsection "add"
Adds an entry to the currently associated data tree.
.PP
.Vb 3
\&    $ldap\->add(\*(Aquid=test, dc=example, dc=com\*(Aq, attrs => [
\&        cn => \*(AqTest\*(Aq
\&    ]);
.Ve
.PP
See \*(L"add\*(R" in Net::LDAP for more parameter usage.
.SS "modify"
.IX Subsection "modify"
Modifies an entry in the currently associated data tree.
.PP
.Vb 3
\&    $ldap\->modify(\*(Aquid=test, dc=example, dc=com\*(Aq, add => [
\&        cn => \*(AqTest2\*(Aq
\&    ]);
.Ve
.PP
See \*(L"modify\*(R" in Net::LDAP for more parameter usage.
.SS "delete"
.IX Subsection "delete"
Deletes an entry from the currently associated data tree.
.PP
.Vb 1
\&    $ldap\->delete(\*(Aquid=test, dc=example, dc=com\*(Aq);
.Ve
.PP
See \*(L"delete\*(R" in Net::LDAP for more parameter usage.
.SS "moddn"
.IX Subsection "moddn"
Modifies \s-1DN\s0 of an entry in the currently associated data tree.
.PP
.Vb 3
\&    $ldap\->moddn(\*(Aquid=test, dc=example, dc=com\*(Aq,
\&        newrdn => \*(Aquid=test2\*(Aq
\&    );
.Ve
.PP
See \*(L"moddn\*(R" in Net::LDAP for more parameter usage.
.SS "bind"
.IX Subsection "bind"
Returns an expected result message if the bind result has previously been setup by the
\&\f(CW\*(C`mock_bind()\*(C'\fR method. Otherwise, a success message is returned.
.SS "unbind"
.IX Subsection "unbind"
Returns a success message.
.SS "abandon"
.IX Subsection "abandon"
Returns a success message.