Testing Hibernate 7: Mocking JNDI DataSources Without the Container

Testing enterprise applications can be a nightmare when your code relies on a JNDI (Java Naming and Directory Interface) DataSource. You shouldn’t need a full-blown JBoss or WildFly server just to run a single unit test.

If you are upgrading to Hibernate 7, you might notice that the way we handle container-managed resources has evolved. In this guide, we will explore how to mock an in-memory JNDI DataSource so your tests remain fast, isolated, and reliable without the overhead of an application server.

The Problem: The “NamingException” Wall

You’ve written a perfect Data Access Object (DAO) or Service layer. It works beautifully in production because the application server (like GlassFish, Payara, or WildFly) provides the JNDI lookup.

However, the moment you run a JUnit 5 test in your IDE, you hit the dreaded javax.naming.NoInitialContextException or NamingException. The environment outside the container doesn’t have a JNDI provider. The InitialContext is empty, and Hibernate fails to boot because it cannot find the resource it needs. You’re stuck between two bad choices: either skip database testing entirely or install a heavy container locally.

The Agitation: Why “Real” JNDI is a Testing Antipattern

Relying on a real JNDI provider for local development or CI/CD pipelines creates several bottlenecks:

Feedback Loop Latency: Starting an application server adds minutes to your build time. For a developer, a 10-second test suite is a productivity booster; a 10-minute suite is a distraction.
Environmental Drift: If the server configuration changes in the dev environment but not in the test environment, your tests break—not because of your code, but because of the infrastructure.
The Jakarta EE 10/11 Shift: Hibernate 7 introduces tighter integration with Jakarta EE 10 and 11. Older mocking hacks—like manually overriding the InitialContextFactory with custom inner classes—often fail due to stricter class-loading mechanisms and the updated jakarta.resource and jakarta.transaction APIs.

The Solution: Simple-JNDI and Hibernate 7

The most robust way to solve this is by using Simple-JNDI, a library that provides a file-based or memory-based JNDI implementation specifically designed for testing environments. By combining this with the H2 database, we can simulate a production-grade DataSource in milliseconds.

1. Prerequisites (Detailed Dependencies)

First, ensure your pom.xml includes Hibernate 7, H2, and the Simple-JNDI library.

A Note on Versioning: This guide utilizes 7.3.2.Final. As Hibernate 7 is currently in its preview phase, enterprise teams should pin to a Final or CR (Candidate Release) version once available for production stability. Hibernate 7 is the primary target for modern apps due to its full alignment with the Jakarta EE 11 namespace and significant internal optimizations in the Service Registry and bytecode enhancement.

<dependencies>
    <!-- Hibernate 7 Core: The backbone of our ORM -->
    <dependency>
        <groupId>org.hibernate.orm</groupId>
        <artifactId>hibernate-core</artifactId>
        <version>7.3.2.Final</version> 
    </dependency>

    <!-- H2 Database: Perfect for lightning-fast in-memory testing -->
    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <version>2.2.224</version>
        <scope>test</scope>
    </dependency>

    <!-- Simple JNDI: The magic bridge to mock our context -->
    <dependency>
        <groupId>simple-jndi</groupId>
        <artifactId>simple-jndi</artifactId>
        <version>0.11.4.1</version>
        <scope>test</scope>
    </dependency>

    <!-- Logback for seeing what Hibernate is doing -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.4.11</version>
        <scope>test</scope>
    </dependency>
</dependencies>

2. Configuring the Mock JNDI Environment

Simple-JNDI looks for a jndi.properties file in your classpath. Create this file in src/test/resources/jndi.properties.

# Set the factory to Simple-JNDI
java.naming.factory.initial=org.osjava.sj.SimpleContextFactory

# Define where the context roots are
org.osjava.sj.root=src/test/resources/jndi

# Use the memory-based factory for speed
java.naming.provider.url=org.osjava.sj.memory.MemoryContextFactory

# Use standard slashes as delimiters
org.osjava.sj.delimiter=/

3. Creating the DataSource Programmatically

In Hibernate 7, the SessionFactory initialization is sensitive to the availability of resources. We must bind the DataSource to the context before we call buildSessionFactory().

import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.cfg.Configuration;
import org.h2.jdbcx.JdbcDataSource;
import javax.naming.Context;
import javax.naming.InitialContext;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;

/**
 * Example test demonstrating JNDI mocking for Hibernate 7
 * Uses H2 as the underlying data store.
 */
public class JndiMockTest {

    private static SessionFactory sessionFactory;
    private static final String JNDI_NAME = "java:comp/env/jdbc/MyTestDS";

    @BeforeAll
    public static void setup() throws Exception {
        // 1. Initialize the Mock JNDI DataSource
        // JdbcDataSource is H2's implementation of javax.sql.DataSource
        JdbcDataSource ds = new JdbcDataSource();
        ds.setURL("jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;MODE=PostgreSQL");
        ds.setUser("sa");
        ds.setPassword("");

        // 2. Bind the DataSource to the JNDI Name manually
        Context ctx = new InitialContext();
        
        // Ensure sub-contexts exist (Simple-JNDI allows creating them recursively)
        ctx.createSubcontext("java:");
        ctx.createSubcontext("java:comp");
        ctx.createSubcontext("java:comp/env");
        ctx.createSubcontext("java:comp/env/jdbc");
        
        // Perform the bind
        ctx.bind(JNDI_NAME, ds);

        // 3. Configure Hibernate 7
        Configuration cfg = new Configuration();
        cfg.setProperty("hibernate.connection.datasource", JNDI_NAME);
        cfg.setProperty("hibernate.dialect", "org.hibernate.dialect.H2Dialect");
        
        // Modern best practice: Use create-drop for clean test states
        cfg.setProperty("hibernate.hbm2ddl.auto", "create-drop");
        cfg.setProperty("hibernate.show_sql", "true");
        cfg.setProperty("hibernate.format_sql", "true");

        sessionFactory = cfg.buildSessionFactory();
    }

    @AfterAll
    public static void tearDown() throws Exception {
        if (sessionFactory != null) {
            sessionFactory.close();
        }
        // CRITICAL: Cleanup JNDI to prevent interference with other tests.
        new InitialContext().unbind(JNDI_NAME);
    }

    @Test
    public void testConnection() {
        try (Session session = sessionFactory.openSession()) {
            assertTrue(session.isOpen(), "Session should be open and connected to JNDI!");
            
            // Execute a simple native query to verify the H2 link
            Integer result = (Integer) session.createNativeQuery("SELECT 1").getSingleResult();
            assertTrue(result == 1);
            
            System.out.println("LOG: Successfully connected to JNDI DataSource and verified H2!");
        }
    }
}

Deep Dive: How it Works Under the Hood

When Hibernate 7 initializes, its DatasourceConnectionProviderImpl kicks in. Here is the sequence:

Property Detection: Hibernate detects the hibernate.connection.datasource property and ignores standard JDBC URL/User/Password settings.
JNDI Lookup: It calls JndiService to perform a lookup, effectively triggering new InitialContext().lookup("java:comp/env/jdbc/MyTestDS").
Factory Interception: Because our jndi.properties is on the classpath, the standard Java Naming manager uses SimpleContextFactory.
Resource Retrieval: The lookup returns the JdbcDataSource object we bound in our @BeforeAll block.
Connection Management: Hibernate treats this object as a “black box” that provides connections. Whether it’s a real container pool or our H2 mock, Hibernate just asks for a Connection.

Potential Pitfalls & Edge Cases

Transaction Management: If your application uses JTA (Java Transaction API), mocking JNDI isn’t enough. You would also need a mock Transaction Manager (like Bitronix or Atomikos). For most unit tests, switching Hibernate to RESOURCE_LOCAL transaction type is simpler.
Static Context Persistence: Simple-JNDI’s memory context lives as long as the JVM process. If you have a large test suite, ensure you unbind your names in @AfterAll to avoid “Name already bound” errors.
Jakarta Namespace: Remember that Hibernate 7 is strictly Jakarta-based. Ensure your persistence context uses jakarta.persistence.
Context Pollution: In large suites, if Test A binds a DataSource but Test B expects a different one, you get “Context Pollution.” Always unbind or use unique naming conventions.

Modern Alternative: Testcontainers

While JNDI mocking is fast and lightweight, Testcontainers is the industry standard for 2024. It spins up a real Docker container for your database. Use JNDI mocking for unit tests and Testcontainers for integration tests where you need 100% database parity.

Frequently Asked Questions

Q1: Why do I get NoInitialContextException when running Hibernate tests outside the container?

This exception is thrown because the JVM has no JNDI provider configured — outside a Jakarta EE server, there is no default InitialContextFactory. The fix is to place a jndi.properties file on your test classpath that points to a lightweight provider like Simple-JNDI, so that new InitialContext() resolves to an in-memory implementation rather than expecting a container.

Q2: What is Simple-JNDI and how does it differ from a real JNDI provider?

Simple-JNDI is a lightweight, file-based or memory-based JNDI implementation designed specifically for testing. Unlike a real container’s JNDI provider (which manages connection pools, security, and lifecycle), Simple-JNDI simply stores objects in a map and retrieves them by name. It is fast, has no external dependencies, and works within a plain JVM — making it ideal for unit and integration tests where you need JNDI lookups without a full application server.

Q3: Should I use JTA transactions or RESOURCE_LOCAL in JNDI mock tests?

Use RESOURCE_LOCAL for most JNDI mock tests. JTA requires a full transaction manager (like Bitronix or Atomikos) to be present and registered in JNDI as well — adding significant complexity to your test setup. By setting hibernate.transaction.coordinator_class=jdbc and using session.beginTransaction() directly, you get full transaction control without the JTA overhead. Only switch to JTA mocking if you are specifically testing XA transaction behaviour.

Q4: How do I avoid “Name already bound” errors across multiple test classes?

Always unbind JNDI names in @AfterAll: new InitialContext().unbind(JNDI_NAME). Since Simple-JNDI’s memory context persists for the JVM lifetime, bindings from one test class survive into the next if not cleaned up. Alternatively, use a unique JNDI name per test class (e.g., include the test class name in the path) to prevent collisions when tests run in parallel.

Q5: When should I use JNDI mock tests vs Testcontainers?

Use JNDI mock tests (with H2) when you need millisecond-fast feedback on ORM mappings, entity validation, and DAO logic — these run in every commit cycle. Use Testcontainers when you need dialect-accurate SQL (e.g., PostgreSQL JSONB, MySQL-specific functions) or when you are testing database-level constraints and migration scripts. A mature project typically uses both: H2/JNDI for fast unit-level persistence tests in the default build phase, and Testcontainers in a separate integration-test phase before release.

Conclusion

Mocking a JNDI DataSource for Hibernate 7 tests eliminates the dependency on a full application server without sacrificing the accuracy of your ORM validation. By combining Simple-JNDI with H2, you get a production-like JNDI lookup flow in milliseconds — verifying Hibernate configuration, entity mapping, and DAO logic with zero infrastructure overhead. Always clean up your bindings in @AfterAll, use RESOURCE_LOCAL to avoid JTA complexity, and complement these fast tests with Testcontainers for dialect-specific integration coverage. Together, these strategies give you a complete, layered testing strategy for any Hibernate 7 persistence layer.

@ankurm