This version is still in development and is not considered stable yet. For the latest stable version, please use Spring LDAP 4.2.0!

Testing

This section covers testing with Spring LDAP. It contains the following topics:

Using an Embedded Server

spring-ldap-test supplies an embedded LDAP server that is based on ApacheDS or UnboundID.

spring-ldap-test is compatible with ApacheDS 1.5.5. Newer versions of ApacheDS are not supported.

To get started, you need to include the spring-ldap-test dependency.

The following listing shows how to include the spring-ldap-test for Maven:

<dependency>
    <groupId>org.springframework.ldap</groupId>
    <artifactId>spring-ldap-test</artifactId>
    <version>4.2.1-SNAPSHOT</version>
    <scope>test</scope>
</dependency>

The following listing shows how to include the spring-ldap-test for Gradle:

testCompile "org.springframework.ldap:spring-ldap-test:4.2.1-SNAPSHOT"

ApacheDS

To use ApacheDS, you need to include a number of ApacheDS dependencies.

The following example shows how to include the ApacheDS dependencies for Maven:

<dependencies>
    <dependency>
        <groupId>org.apache.directory.server</groupId>
        <artifactId>apacheds-core</artifactId>
        <version>1.5.5</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.apache.directory.server</groupId>
        <artifactId>apacheds-core-entry</artifactId>
        <version>1.5.5</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.apache.directory.server</groupId>
        <artifactId>apacheds-protocol-shared</artifactId>
        <version>1.5.5</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.apache.directory.server</groupId>
        <artifactId>apacheds-protocol-ldap</artifactId>
        <version>1.5.5</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.apache.directory.server</groupId>
        <artifactId>apacheds-server-jndi</artifactId>
        <version>1.5.5</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.apache.directory.shared</groupId>
        <artifactId>shared-ldap</artifactId>
        <version>0.9.15</version>
        <scope>test</scope>
    </dependency>
</dependencies>

The following example shows how to include the ApacheDS dependencies for Gradle:

dependencies {
    testImplementation "org.apache.directory.server:apacheds-core:1.5.5"
    testImplementation "org.apache.directory.server:apacheds-core-entry:1.5.5"
    testImplementation "org.apache.directory.server:apacheds-protocol-shared:1.5.5"
    testImplementation "org.apache.directory.server:apacheds-protocol-ldap:1.5.5"
    testImplementation "org.apache.directory.server:apacheds-server-jndi:1.5.5"
    testImplementation "org.apache.directory.shared:shared-ldap:0.9.15"
}

The following bean definition creates an embedded LDAP server:

<bean id="embeddedLdapServer" class="org.springframework.ldap.test.EmbeddedLdapServerFactoryBean">
    <property name="partitionName" value="example"/>
    <property name="partitionSuffix" value="dc=261consulting,dc=com" />
    <property name="port" value="9321" />
</bean>

spring-ldap-test provides a mechanism to populate the LDAP server by using org.springframework.ldap.test.LdifPopulator. To use it, create a bean similar to the following:

<bean class="org.springframework.ldap.test.LdifPopulator" depends-on="embeddedLdapServer">
    <property name="contextSource" ref="contextSource" />
    <property name="resource" value="classpath:/setup_data.ldif" />
    <property name="base" value="dc=jayway,dc=se" />
    <property name="clean" value="true" />
    <property name="defaultBase" value="dc=jayway,dc=se" />
</bean>

Another way to work against an embedded LDAP server is by using org.springframework.ldap.test.TestContextSourceFactoryBean, as follows:

<bean id="contextSource" class="org.springframework.ldap.test.TestContextSourceFactoryBean">
    <property name="defaultPartitionSuffix" value="dc=jayway,dc=se" />
    <property name="defaultPartitionName" value="jayway" />
    <property name="principal" value="uid=admin,ou=system" />
    <property name="password" value="secret" />
    <property name="ldifFile" value="classpath:/setup_data.ldif" />
    <property name="port" value="1888" />
</bean>

Also, org.springframework.ldap.test.LdapTestUtils provides methods to programmatically work with an embedded LDAP server.

UnboundID

To use UnboundID, you need to include an UnboundID dependency.

The following example shows how to include the UnboundID dependency for Maven:

<dependency>
    <groupId>com.unboundid</groupId>
    <artifactId>unboundid-ldapsdk</artifactId>
    <version>7.0.6</version>
    <scope>test</scope>
</dependency>

The following example shows how to include the UnboundID dependency for Gradle:

testCompile "com.unboundid:unboundid-ldapsdk:7.0.6"

The following bean definition creates an embedded LDAP server:

@Bean
EmbeddedLdapServer embeddedLdapServer() {
    return EmbeddedLdapServer.withPartitionSuffix("dc=jayway,dc=se")
        .partitionName("jayway")
        .port(18881)
        .configurationCustomizer((config) -> config.setCodeLogDetails(tempLogFile, true))
        .build();
}

Alternatively, you can use the org.springframework.ldap.test.unboundid.LdifPopulator to create and populate the LDAP server. To use it, create a bean similar to the following:

<bean class="org.springframework.ldap.test.unboundid.LdifPopulator" depends-on="embeddedLdapServer">
    <property name="contextSource" ref="contextSource" />
    <property name="resource" value="classpath:/setup_data.ldif" />
    <property name="base" value="dc=jayway,dc=se" />
    <property name="clean" value="true" />
    <property name="defaultBase" value="dc=jayway,dc=se" />
</bean>

Another way to work against an embedded LDAP server is by using org.springframework.ldap.test.unboundid.TestContextSourceFactoryBean. To use it, create a bean similar to the following:

<bean id="contextSource" class="org.springframework.ldap.test.unboundid.TestContextSourceFactoryBean">
    <property name="defaultPartitionSuffix" value="dc=jayway,dc=se" />
    <property name="defaultPartitionName" value="jayway" />
    <property name="principal" value="uid=admin,ou=system" />
    <property name="password" value="secret" />
    <property name="ldifFile" value="classpath:/setup_data.ldif" />
    <property name="port" value="1888" />
</bean>

Also, org.springframework.ldap.test.unboundid.LdapTestUtils provide methods to programmatically work with an embedded LDAP server.

Using a Real Server with Testcontainers

An embedded server is convenient, but some behavior depends on a real LDAP server, such as paged results, STARTTLS, or server-specific controls. For those cases, run the server of your choice in a container with Testcontainers and point an LdapContextSource at it. Spring LDAP does not require any particular module for this; it only needs the container’s host and mapped port.

The following example starts an OpenLDAP container and builds a ContextSource for it:

@Testcontainers
class OpenLdapTests {

    @Container
    static GenericContainer<?> openldap = new GenericContainer<>(DockerImageName.parse("ghcr.io/rroemhild/docker-test-openldap:master"))
            .withExposedPorts(10389)
            .waitingFor(Wait.forListeningPort());

    static LdapContextSource contextSource() {
        LdapContextSource contextSource = new LdapContextSource();
        contextSource.setUrl("ldap://" + openldap.getHost() + ":" + openldap.getMappedPort(10389));
        contextSource.setBase("dc=planetexpress,dc=com");
        contextSource.setUserDn("cn=admin,dc=planetexpress,dc=com");
        contextSource.setPassword("GoodNewsEveryone");
        contextSource.afterPropertiesSet();
        return contextSource;
    }
}
Pin the image by digest in your own builds so that the test does not change underneath you.

If your application uses Spring Boot, you can skip building the LdapContextSource yourself. Spring Boot can start a supported LDAP container, with either Testcontainers or Docker Compose, and configure the application’s LDAP connection from it. See Testcontainers Support and Development-time Services in the Spring Boot reference for the supported containers and how to enable them.

Migrating from the EC2 Factory Beans

ContextSourceEc2InstanceLaunchingFactoryBean and AbstractEc2InstanceLaunchingFactoryBean launched an Amazon EC2 instance from a prepared AMI and exposed it as a ContextSource. They are deprecated and will be removed, because they depend on unmaintained tooling and Testcontainers covers the same need without an AWS account.

To migrate:

  1. Replace the AMI with a Docker image that runs the same LDAP server.

  2. Replace the factory bean’s imageName, awsKey, awsSecretKey, keypairName, and groupName properties with a Testcontainers container, as shown in Using a Real Server with Testcontainers.

  3. Build the LdapContextSource from the container’s host and mapped port, using the same userDn, password, and base you passed to the factory bean.

The container is started and stopped by Testcontainers, so you no longer need to manage the instance’s lifecycle or wait for it to start. Because the connection is to a local container, you also avoid sending the bind credentials over a public network, which the EC2 factory bean did over plain ldap://.