Testcontainers Desktop

1. Overview

In modern software development, automated testing has become an integral part of the development lifecycle. However, setting up and managing test environments can be a cumbersome task. Testcontainers, a popular Java library, simplifies this process by providing lightweight, disposable containers for running integration tests. it takes this concept further by offering a user-friendly desktop application.

2. Exploring Testcontainers Desktop

Testcontainers Desktop is a graphical user interface (GUI) application designed to streamline the usage of Testcontainers in your development workflow. It provides a visual interface for managing containers, executing tests, and monitoring their execution status, so developers can focus more on writing tests and less on managing infrastructure.

3. Testcontainers Desktop Execution Modes

There are two execution modes to suit different testing scenarios:

  • Local Mode: In this mode, it runs containers locally on your machine, making it suitable for testing applications that don’t require external dependencies.
  • Remote Mode: it connects to a remote Docker daemon, allowing you to run containers on a separate machine or a cloud-based environment. This mode is useful for testing applications that interact with external services or APIs.

4. Debugging with Testcontainers Desktop

Debugging test failures can be challenging, especially when dealing with containerized environments. it simplifies this process by providing built-in debugging tools. Developers can inspect container logs, view network activity, and troubleshoot issues directly from the application interface. This helps in identifying and fixing bugs faster, improving overall development efficiency.

4.1. Using fixed ports to debug development services

During Testcontainers-based testing, container ports are typically mapped to random ports on the host machine to prevent conflicts. However, for development purposes, connecting to these services for troubleshooting or data inspection can be cumbersome due to constantly changing ports.
Testcontainers Desktop simplifies this process by allowing the use of fixed ports for container services. This ensures consistent connectivity to services using configured port numbers.
For example, in a Spring Boot application utilizing PostgreSQL, Testcontainers Desktop enables connecting to the PostgreSQL database running in a Docker container using a fixed port. By configuring a postgres.toml file with the desired port mapping, developers can ensure consistent access to the database.

Click on Testcontainers Desktop → select Services → Open config location.

In the opened directory there would be a postgres.toml.example file. Rename it to postgres.toml file, and it should contain the following configuration:

ports = [
    {local-port = 5432, container-port = 5432},
selector.image-names = ["postgres"]

Once configured, connecting to the PostgreSQL database using SQL clients like psql becomes straightforward. Additionally, IDE tools like IntelliJ IDEA Ultimate Database Tools can be utilized for seamless database interaction.

$ psql -h localhost -p 5432 -U test -d test

4.2. Freezing containers to prevent their shutdown to debug

While running your tests, you may want to inspect data to debug some issue before the container is removed. You can now use the freeze containers shutdown feature that will prevent the container shutdown allowing you to debug the issue.

Let’s say we have the following Spring Data JPA Repository Test.

@DataJpaTest(properties = {
class ProductRepositoryTest {

   static PostgreSQLContainer<?> postgres =
                      new  PostgreSQLContainer<>("postgres:16-alpine");

   ProductRepository repository;

   void shouldCreateProductIfNotExist() {
       String code = UUID.randomUUID().toString();
       Product product = new Product(null, code, "test product", BigDecimal.TEN);

Let’s open the Testcontainers Desktop app and enable Freeze containers shutdown.


After activating “Freeze containers shutdown”, executing the ProductRepositoryTest from your IDE will prevent the application from shutting down, effectively prolonging the test indefinitely. Once your investigation is complete, simply uncheck the “freeze” option to resume normal test execution, including cleanup.

While debugging via a fixed port is not always necessary, combining both features can be highly beneficial. This combination allows for easy connection to a debugging tool and provides ample time for utilization. Freezing containers is compatible with both local runtime and Testcontainers Cloud.

5. Testcontainers Desktop Dashboard

One of the standout features of Testcontainers Desktop is its intuitive dashboard. The dashboard provides a comprehensive overview of all running containers, active tests, and their status. Developers can quickly identify failing tests, track resource utilization, and manage container lifecycle with ease. Additionally, the dashboard offers real-time updates, ensuring developers stay informed about test execution progress.


6. Conclusion

Testcontainers Desktop revolutionizes the way developers manage and execute integration tests using Testcontainers. By providing a user-friendly interface and powerful features like execution modes, debugging tools, and a comprehensive dashboard, it simplifies the testing process and enhances developer productivity. Whether you’re a seasoned developer or new to containerized testing, it is a valuable tool for streamlining your testing workflow. With its intuitive interface and robust functionality, it is poised to become an essential companion for modern software development teams.

Ashraf Sarhan

With over 8 years of experience in the field, I have developed and maintained large-scale distributed applications for various domains, including library, audio books, and quant trading. I am passionate about OpenSource, CNCF/DevOps, Microservices, and BigData, and I constantly seek to learn new technologies and tools. I hold two Oracle certifications in Java programming and business component development.
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button