About Testcontainers
Testcontainers is a popular open-source Java library that simplifies the testing of applications by providing lightweight, disposable containers for executing tests. It integrates with Docker, allowing you to run databases, message brokers, web servers, or any service your application depends on, in isolated, reproducible environments.
Here’s a breakdown of Testcontainers' key features and use cases:
### Key Features:
1. **Docker Integration**:
Testcontainers wraps Docker containers to provide ready-to-use instances of databases, message brokers, or other services that your application might interact with. It ensures these containers are managed (started and stopped) automatically during test execution.
2. **Isolation**:
Each test runs in its own containerized environment, eliminating any side effects between tests. This guarantees consistent, isolated test environments, improving reliability.
3. **Reusable Containers**:
Testcontainers can reuse containers to speed up test execution by avoiding the overhead of starting and stopping containers multiple times.
4. **Integration with Popular Frameworks**:
Testcontainers integrates well with popular testing frameworks like JUnit, Spock, and TestNG. This makes it easy to manage the lifecycle of containers within your existing test suites.
5. **Rich Set of Modules**:
Testcontainers provides pre-configured modules for popular databases (e.g., PostgreSQL, MySQL, MongoDB), message brokers (Kafka, RabbitMQ), and other technologies (Elasticsearch, Redis). You can also create custom containers for more specialized needs.
6. **Parallel Test Execution**:
Containers can be run in parallel, enabling the execution of multiple tests concurrently, which is particularly useful for speeding up integration tests.
7. **Environment Parity**:
Since containers run in Docker, they mimic the actual production environments more closely than traditional mock objects, providing higher fidelity tests.
8. **Customizable**:
You can extend or create custom containers to suit your specific requirements. This allows testing scenarios with non-standard or proprietary services.
### Common Use Cases:
1. **Integration Testing**:
Testcontainers is ideal for testing code that interacts with external systems like databases, message queues, or web services. For instance, you can spin up a PostgreSQL container and run integration tests that interact with a real database rather than relying on mock objects.
2. **End-to-End Testing**:
Full-stack applications can be tested end-to-end using containers for both the backend (databases, message queues) and frontend (HTTP servers, etc.). This ensures that the interaction between different components of the system works as expected.
3. **Testing Legacy Systems**:
For systems that rely on legacy databases or services, Testcontainers can provide a clean, isolated environment that mimics the legacy environment, enabling more realistic testing without disrupting the actual legacy system.
4. **CI/CD Pipelines**:
Testcontainers works well in CI/CD pipelines. Since it uses Docker, the same tests can run in any environment that supports Docker, ensuring that tests in development, staging, and production environments are consistent.
5. **Cloud-Native Application Testing**:
In a microservices or cloud-native application, Testcontainers can simulate the services that your application depends on, like Kubernetes pods, APIs, and distributed databases, enabling better testing of complex, distributed systems.
### Example Code Snippet:
Here’s a basic example using JUnit and Testcontainers with a PostgreSQL database:
```java
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;
import static org.junit.jupiter.api.Assertions.assertEquals;
@Testcontainers
public class PostgresTest {
@Container
public PostgreSQLContainer<?> postgresContainer = new PostgreSQLContainer<>("postgres:latest")
.withDatabaseName("testdb")
.withUsername("testuser")
.withPassword("password");
@Test
public void testDatabaseConnection() throws Exception {
String jdbcUrl = postgresContainer.getJdbcUrl();
String username = postgresContainer.getUsername();
String password = postgresContainer.getPassword();
try (Connection conn = DriverManager.getConnection(jdbcUrl, username, password);
Statement stmt = conn.createStatement()) {
stmt.execute("CREATE TABLE test (id INT PRIMARY KEY, name VARCHAR(255))");
stmt.execute("INSERT INTO test VALUES (1, 'Testcontainers')");
ResultSet rs = stmt.executeQuery("SELECT name FROM test WHERE id = 1");
rs.next ();
assertEquals("Testcontainers", rs.getString(1));
}
}
}
```
### Advantages:
- **Improves Testing Quality**: Tests with Testcontainers interact with real services, resulting in more realistic and reliable test outcomes.
- **Reduces Flakiness**: It eliminates problems related to environment mismatch or inconsistent state in testing.
- **Easy to Set Up**: Since Docker manages everything, the setup is easy and portable across different environments.
### Drawbacks:
- **Performance Overhead**: Spinning up Docker containers introduces some performance overhead, especially if the test suite is large.
- **Docker Dependency**: The library requires Docker, which might not be available in all environments, particularly on restricted systems.
### Conclusion:
Testcontainers is a powerful tool for integration and end-to-end testing. By utilizing Docker containers, it provides a reliable, reproducible, and isolated environment for testing services like databases, message brokers, and other infrastructure components.
---
###Mastering Testcontainers for Advanced Testing and CI/CD**
---
#### **Introduction to Testcontainers and the Course Structure**
- **Course Objectives**: Outline the goals, what participants will achieve, and a brief overview of Testcontainers.
- **Why Testcontainers?**: Explain the significance of using Testcontainers in modern software development, focusing on integration, reliability, and scalability.
- **Who Should Take This Course?**: Identify the target audience (developers, QA engineers, DevOps teams) and their prerequisite knowledge.
---
### **Section 1: Foundations of Testcontainers**
#### 1.1 **What is Testcontainers and Why Should You Use It?**
- **Introduction to Testcontainers**: Define Testcontainers, its architecture, and its importance in modern testing.
- **Benefits Over Mocking or In-Memory Solutions**: Explain why Testcontainers provides more reliable results than traditional testing approaches.
- **Real-World Use Cases**: Showcase scenarios where Testcontainers provides significant value (e.g., testing complex microservices, CI/CD pipelines).
#### 1.2 **Getting Started with Testcontainers**
- **Installing Testcontainers**: Step-by-step guide to setting up Testcontainers in Java, covering dependencies for Maven and Gradle.
- **Configuring Docker**: Instructions on Docker setup, ensuring participants have a working Docker environment to run Testcontainers.
- **Hello World with Testcontainers**: A basic example to demonstrate Testcontainers in action, running a simple containerized database or web service for testing.
#### 1.3 **Understanding Container Lifecycle**
- **How Testcontainers Manages Containers**: Dive into how containers are created, started, and destroyed automatically during test execution.
- **Managing Lifecycle with JUnit and TestNG**: Guide on how to hook into popular testing frameworks to automatically control container lifecycle.
- **Troubleshooting Common Setup Issues**: Tips on dealing with common Testcontainers startup or Docker-related issues.
---
### **Section 2: Leveraging Predefined Modules for Testing**
#### 2.1 **Testing with Databases**
- **Using Database Containers (Postgres, MySQL, etc.)**: Learn how to spin up database containers and configure them for integration tests.
- **Writing Tests Against Real Databases**: Practical examples showing how to test database-related functionality in your application.
- **Database Migrations in Tests**: How to use tools like Liquibase or Flyway with Testcontainers to apply migrations before running tests.
#### 2.2 **Testing with Message Brokers**
- **Kafka and RabbitMQ Containers**: Setup and use containers for testing real-world message brokers in microservices or event-driven applications.
- **Writing End-to-End Tests for Messaging**: Implement tests that verify the interaction between services through message queues or topics.
- **Ensuring Consistent Messaging Tests**: Handling the potential pitfalls of asynchronous message testing, such as timeouts or message order.
#### 2.3 **Web and REST API Testing**
- **Using Selenium with Testcontainers**: Automate browser testing by running a Selenium container alongside your application.
- **Testing REST APIs with MockServers and Wiremock**: Use containers to mimic third-party APIs and write tests for external integrations.
- **Performance and Load Testing**: Brief overview of how containers can be used to set up and run lightweight performance tests.
---
### **Section 3: Advanced Testcontainers Techniques**
#### 3.1 **Customizing Containers for Complex Scenarios**
- **Building Custom Testcontainers**: Learn how to create custom containers using Dockerfiles for services not covered by predefined modules.
- **Using Docker Compose for Multi-Container Tests**: Implement advanced setups where multiple containers interact, using Docker Compose in your tests.
- **Mounting Volumes and Custom Configurations**: Step-by-step guide on mounting configuration files, logs, and other resources into containers to mimic production environments.
#### 3.2 **Optimizing Test Speed and Resource Usage**
- **Container Reuse and Caching**: Explore techniques for speeding up test execution by reusing containers across test classes or suites.
- **Parallel Test Execution**: Running containers and tests in parallel to reduce build times and improve CI/CD efficiency.
- **Managing Resource Constraints**: Handling Docker-related system resource issues, such as memory limits and container cleanup.
#### 3.3 **Testing Distributed Systems and Microservices**
- **Simulating Microservice Environments**: Setup a test suite that spans multiple microservices using a combination of Testcontainers and Docker Compose.
- **Network and Latency Testing**: Introduce artificial network issues (latency, dropped connections) in Testcontainers to simulate real-world conditions.
- **Chaos Engineering with Testcontainers**: Brief introduction to how Testcontainers can be used for Chaos Testing, by simulating failures in different services.
---
### **Section 4: Integrating Testcontainers into CI/CD Pipelines**
#### 4.1 **Setting Up Testcontainers in CI/CD Environments**
- **Running Testcontainers in CI/CD**: Guidelines on configuring Jenkins, GitLab CI, GitHub Actions, or CircleCI to execute Testcontainers-based tests.
- **Handling Docker in Cloud CI Services**: Solutions for environments with restricted Docker access, such as using privileged runners or remote Docker hosts.
- **Optimizing Pipeline Performance**: Best practices for balancing test speed, resource usage, and reliability in containerized CI pipelines.
#### 4.2 **Best Practices for Scaling Testcontainers in CI**
- **Parallelizing and Isolating Tests in CI**: Techniques to run large-scale test suites efficiently, including handling concurrency and reducing test flakiness.
- **Container Logging and Monitoring**: How to collect, analyze, and troubleshoot logs from containers during CI runs, using tools like ELK stack or cloud logging services.
- **Ensuring Test Consistency Across Environments**: How to ensure that tests running on local development environments, CI servers, and staging environments behave consistently.
#### 4.3 **Security and Compliance Considerations**
- **Handling Sensitive Data in Testcontainers**: Best practices for securing passwords, API keys, and other sensitive data in containers.
- **Docker and Security Compliance in CI/CD**: Guidance on ensuring that your Docker containers and Testcontainers-based tests meet security standards.
- **Container Scanning and Vulnerability Checking**: Tools and strategies for scanning containers for vulnerabilities during automated builds and tests.
---
### **Section 5: Troubleshooting and Advanced Use Cases**
#### 5.1 **Common Issues and How to Resolve Them**
- **Container Startup Failures**: How to debug and fix issues related to container startup, Docker configuration, or missing dependencies.
- **Dealing with Flaky Tests**: Techniques for diagnosing and resolving intermittent test failures caused by infrastructure, networking, or service issues.
- **Debugging and Inspecting Containers**: How to log into containers and inspect their state during tests to understand failures or unexpected behavior.
#### 5.2 **Real-World Case Studies**
- **Case Study 1: Microservices Integration Testing**: Walkthrough of a real-world application where Testcontainers are used to test a complex microservices setup.
- **Case Study 2: Scaling CI with Testcontainers**: A detailed look at how a large-scale organization improved their CI pipeline with Testcontainers.
- **Case Study 3: End-to-End Testing for a Distributed Application**: Example of testing a distributed application, complete with multiple databases, message brokers, and APIs.
#### 5.3 **Future Trends and Emerging Practices**
- **Future of Testcontainers**: Discussion of the roadmap and upcoming features of Testcontainers and how they might change testing practices.
- **Expanding Beyond Java**: How Testcontainers concepts are expanding to other languages (Python, Go) and what this means for polyglot teams.
- **Testcontainers with Kubernetes**: Explore how Testcontainers might evolve to work with Kubernetes-native applications for testing in a cloud-native world.
---
### **Conclusion and Next Steps**
- **Review of Key Concepts**: Recap of the most important lessons from the course.
- **Taking Your Testcontainers Skills Further**: Additional resources for participants to continue learning, including books, communities, and advanced use cases.
- **Final Project**: A capstone project for participants to apply their Testcontainers knowledge by building and testing a real-world application, integrating multiple services and CI/CD pipelines.
---
### **Appendices**
- **Appendix A**: Testcontainers API Reference Guide
- **Appendix B**: Docker and Testcontainers Troubleshooting Cheat Sheet
- **Appendix C**: Useful Tools and Resources (links to documentation, community forums, additional learning materials)
---
This course outline provides a step-by-step progression from basic concepts to advanced techniques, ensuring that participants not only understand the theory but also have actionable content to implement in real-world scenarios.
---
### **Mastering Testcontainers for Advanced Testing and CI/CD**
---
## **Section 1: Foundations of Testcontainers**
### **1.1 What is Testcontainers and Why Should You Use It?**
Testcontainers is a library that allows developers to run external services in Docker containers during tests, such as databases, message brokers, and more. Unlike mock services, it provides realistic, reproducible test environments. It ensures your tests are not just syntactically correct, but behave correctly with the services your application will rely on in production.
- **Real-World Results**: Testcontainers provides more accurate test results by using real services instead of in-memory or mocked versions.
- **Consistency**: Run tests in isolated environments, ensuring no side effects from previous test runs.
- **Infrastructure Parity**: Testcontainers minimizes the gap between local development, testing, and production environments.
**Example: Integration Testing with Postgres**
1. Set up a PostgreSQL container during tests.
2. Run integration tests that directly interact with the database.
3. Tear down the container after the tests complete.
---
### **1.2 Getting Started with Testcontainers**
Getting started with Testcontainers is easy. First, you'll need to install it in your Java project using Maven or Gradle, and ensure you have Docker running on your machine. Testcontainers integrates seamlessly into your existing test suite, making it easy to spin up services like databases or message queues on demand.
- **Quick Setup**: Add the Testcontainers library as a dependency and you're ready to go.
- **Docker Requirement**: Ensure Docker is installed and accessible on your system.
- **First Example**: Spin up a container with just a few lines of code.
**Example: Hello World with Testcontainers**
1. Add Testcontainers to your Maven or Gradle project.
2. Set up a simple test that launches a PostgreSQL container.
3. Verify the container is running, connect to it, and perform basic operations.
---
### **1.3 Understanding Container Lifecycle**
Testcontainers automatically manages container lifecycles. When a test begins, the container starts; once the test ends, the container is stopped and removed. Understanding this lifecycle ensures you have clean, isolated environments for each test, eliminating the "it worked on my machine" problem.
- **Automatic Management**: Containers start and stop automatically with tests.
- **Isolation**: Each test runs in its own clean environment, with no residual data or side effects.
- **Integration with Test Frameworks**: Works with JUnit and TestNG for seamless integration.
**Example: JUnit Integration**
1. Annotate your test class with @Testcontainers.
2. Use the @Container annotation to define your containers.
3. Run tests to see the containers automatically managed by JUnit.
---
## **Section 2: Leveraging Predefined Modules for Testing**
### **2.1 Testing with Databases**
One of Testcontainers' most powerful features is its predefined modules for databases like PostgreSQL, MySQL, and MongoDB. These modules allow you to write integration tests that interact with real databases rather than relying on mocked or in-memory alternatives. This ensures your tests reflect real-world scenarios.
- **Real Databases for Tests**: Run actual databases in containers, ensuring reliable test results.
- **Predefined Modules**: Testcontainers provides easy-to-use modules for popular databases.
- **Consistency Across Environments**: The database version used in tests matches production versions.
**Example: PostgreSQL Container Setup**
1. Define a PostgreSQLContainer in your test class.
2. Write a test that inserts and retrieves data from the database.
3. Verify the data persistence and schema integrity.
---
### **2.2 Testing with Message Brokers**
Modern applications often rely on message brokers like Kafka and RabbitMQ for asynchronous communication between services. Testcontainers provides pre-configured modules for these brokers, allowing you to simulate real-world messaging scenarios and ensure your application handles them correctly.
- **Simulating Real Messaging**: Test actual message brokers instead of mock implementations.
- **Kafka and RabbitMQ Modules**: Easy setup for testing complex messaging flows.
- **End-to-End Messaging**: Ensure reliable communication between services in your tests.
**Example: Testing with Kafka**
1. Set up a KafkaContainer in your test.
2. Produce a message to a Kafka topic.
3. Consume the message and verify the content.
---
### **2.3 Web and REST API Testing**
Testcontainers can also be used to test web applications and REST APIs by running containers for services like Selenium (for browser automation) or MockServer (to mock external APIs). This ensures your web application functions correctly under real-world conditions.
- **Selenium for Browser Testing**: Automate browser interactions with a containerized Selenium server.
- **MockServer for API Testing**: Mock third-party services to isolate and test your API interactions.
- **End-to-End Web Testing**: Ensure your web app's frontend and backend work as expected.
**Example: Testing a REST API**
1. Spin up a MockServerContainer for mocking an external API.
2. Write a test that sends requests to your application.
3. Verify the response is correctly handled, simulating real API interactions.
---
## **Section 3: Advanced Testcontainers Techniques**
### **3.1 Customizing Containers for Complex Scenarios**
Sometimes the predefined modules aren’t enough, and you need to create custom containers. This is useful when you’re dealing with proprietary software or services not directly supported by Testcontainers. You can build and run containers from your own Dockerfiles or configure containers with specific environments and volumes.
- **Custom Containers**: Extend Testcontainers by creating custom containers using Dockerfiles.
- **Mounting Volumes**: Load custom configurations or data into your containers.
- **Advanced Scenarios**: Test legacy systems or unique services in isolated environments.
**Example: Custom Database Configuration**
1. Create a Dockerfile for a custom database image.
2. Use Testcontainers to build and run the container.
3. Test database queries with specific configurations.
---
### **3.2 Optimizing Test Speed and Resource Usage**
Running containers for each test can be resource-intensive. Testcontainers allows for container reuse, where containers are shared across test classes, improving test speed and efficiency. Additionally, parallelizing tests can greatly reduce execution time.
- **Container Reuse**: Reuse containers between test runs to minimize startup overhead.
- **Parallel Test Execution**: Run multiple containers in parallel to speed up large test suites.
- **Efficient Resource Management**: Handle Docker resource limits to avoid system slowdowns.
**Example: Reusing a Database Container**
1. Configure Testcontainers to reuse a PostgreSQL container between test runs.
2. Ensure test data is cleared between each test.
3. Observe reduced test times.
---
### **3.3 Testing Distributed Systems and Microservices**
For microservices architectures, testing interactions between services is critical. Testcontainers can spin up multiple services simultaneously, allowing you to simulate real-world interactions between microservices. Docker Compose integration enables complex setups involving multiple containers working together.
- **Testing Microservices**: Simulate interactions between services by running multiple containers.
- **Docker Compose Support**: Use Docker Compose to manage multi-container environments for tests.
- **Simulating Network Conditions**: Test service behavior under different network conditions (e.g., latency).
**Example: Multi-Container Microservices Test**
1. Use Docker Compose to define a multi-service environment (database, message broker, and API).
2. Run integration tests to verify communication between services.
3. Simulate a network failure and observe how services handle the situation.
---
## **Section 4: Integrating Testcontainers into CI/CD Pipelines**
### **4.1 Setting Up Testcontainers in CI/CD Environments**
Testcontainers fits perfectly into CI/CD pipelines, as Docker allows for consistent environments across all stages. Whether using Jenkins, GitHub Actions, or CircleCI, Testcontainers ensures your tests can run consistently on any platform with Docker support.
- **CI/CD Compatibility**: Testcontainers can be integrated into any Docker-enabled CI pipeline.
- **Consistent Test Environments**: Ensure tests behave the same in local and CI environments.
- **Platform Agnostic**: Run tests in any CI/CD system that supports Docker.
**Example: Testcontainers in GitHub Actions**
1. Set up a CI pipeline in GitHub Actions.
2. Ensure Docker is available in the pipeline.
3. Run Testcontainers-based tests as part of the pipeline.
---
### **4.2 Best Practices for Scaling Testcontainers in CI**
As your test suite grows, scaling Testcontainers in CI becomes essential. Techniques such as container reuse and parallelization ensure that your CI builds are both fast and reliable. Managing Docker system resources is also key to preventing pipeline bottlenecks.
- **Parallelization**: Run tests concurrently to reduce build time.
- **Container Reuse**: Reuse containers in CI pipelines to improve performance.
- **Resource Management**: Optimize Docker resource usage in CI to avoid failures.
**Example: Parallelizing Tests in Jenkins**
1. Configure Jenkins to run Testcontainers tests in parallel across different nodes.
2. Use container reuse to minimize Docker resource strain.
3. Verify reduced build times and consistent results.
---
领英推荐
### **4.3 Security and Compliance Considerations**
Testcontainers introduces Docker into your testing process, which means there are security and compliance concerns to address. Handle sensitive data like API keys and passwords carefully, and ensure that your Docker images meet security standards through vulnerability scanning.
- **Securing Secrets**: Ensure sensitive data like credentials are handled securely in containers.
- **Image Scanning**: Use tools to scan Docker images for vulnerabilities.
- **Compliance with CI Standards**: Ensure your CI pipeline follows security and compliance standards.
**Example: Securing Secrets in Testcontainers**
1. Use environment variables to inject credentials securely into containers.
2. Implement Docker image scanning in the CI pipeline.
3. Monitor and
update base images regularly for security patches.
---
## **Section 5: Troubleshooting and Advanced Use Cases**
### **5.1 Common Issues and How to Resolve Them**
While Testcontainers is reliable, issues can arise, such as container startup failures or flaky tests. Understanding how to troubleshoot these problems ensures your tests run smoothly and consistently.
- **Container Startup Failures**: Identify and resolve issues related to container boot failures.
- **Flaky Tests**: Address intermittent test failures caused by timing or infrastructure issues.
- **Debugging Tools**: Log into containers during tests to inspect their state.
**Example: Debugging a Failing Database Test**
1. Enable verbose logging in Testcontainers to trace container startup issues.
2. Log into the running container to inspect logs and configurations.
3. Apply fixes and rerun the test suite.
---
### **5.2 Real-World Case Studies**
Learning from real-world examples is invaluable. Case studies provide insights into how organizations have used Testcontainers to solve complex testing problems, especially in microservices and large-scale CI/CD environments.
- **Microservices Testing**: Case study showing how Testcontainers enabled reliable microservices integration testing.
- **CI/CD Scaling**: Example of a company using Testcontainers to speed up their CI pipeline.
- **Distributed System Testing**: Simulating failures and network issues in distributed systems testing.
**Example: Microservices Testing at Scale**
1. A case study of a fintech company that used Testcontainers to test their microservices architecture.
2. Set up containers for each service and run integration tests in parallel.
3. Ensure service resilience by simulating failures.
---
### **5.3 Future Trends and Emerging Practices**
As containerization continues to evolve, so too will testing practices. Emerging trends include expanded language support for Testcontainers, better Kubernetes integration, and more robust tools for testing cloud-native applications.
- **Polyglot Support**: Testcontainers is expanding to support multiple programming languages.
- **Kubernetes Integration**: Testing Kubernetes-native applications using Testcontainers.
- **Cloud-Native Testing**: Preparing for future testing requirements as cloud services evolve.
**Example: Testing with Kubernetes**
1. Set up Testcontainers to work with a Kubernetes cluster.
2. Test microservices deployed in Kubernetes using real-world scenarios.
3. Monitor resource usage and ensure scalability in cloud environments.
---
### **Conclusion and Next Steps**
This ebook course has covered Testcontainers in depth, from foundational concepts to advanced techniques. You now have the tools to apply Testcontainers effectively in your projects, ensuring robust, real-world testing environments. Continue exploring Testcontainers, integrate it into your workflows, and enhance your CI/CD pipelines for better, faster, and more reliable results.
---
This structured content offers a blend of theory, practical steps, and real-world examples, ensuring readers understand how to apply Testcontainers in their own projects.
---
Let’s walk through real-life, step-by-step examples using **Testcontainers**—starting from scratch for a total beginner. We’ll cover how to install and set up Testcontainers, work with basic containerized services like databases, and gradually move to more advanced scenarios like integrating Testcontainers into a Continuous Integration (CI) pipeline.
---
## **Example 1: Setting Up Testcontainers for the First Time**
### **Step 1: Install Testcontainers in a Java Project**
We’ll start by setting up a Java project using Maven (you can use Gradle if you prefer).
1. **Create a New Maven Project**:
- Create a new Java project (using IntelliJ IDEA, Eclipse, or any IDE).
- In the pom.xml file, add Testcontainers as a dependency:
```xml
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>testcontainers</artifactId>
<version>1.17.3</version>
<scope>test</scope>
</dependency>
```
2. **Ensure Docker is Installed**:
- Download and install Docker from [Docker's website](https://www.docker.com/products/docker-desktop ).
- Verify that Docker is running by typing docker --version in your terminal.
---
### **Step 2: Write Your First Test with Testcontainers**
Let’s create a simple test that spins up a PostgreSQL container.
1. **Create a Test Class**:
- Create a src/test/java folder in your project and inside it, create a test class called PostgresTest.java.
2. **Write the Code**:
```java
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.PostgreSQLContainer;
import static org.junit.jupiter.api.Assertions.assertEquals;
public class PostgresTest {
@Test
void testPostgresContainer() {
try (PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:13.1")) {
postgres.start();
String jdbcUrl = postgres.getJdbcUrl();
String username = postgres.getUsername();
String password = postgres.getPassword();
System.out.println("PostgreSQL running at: " + jdbcUrl);
assertEquals("jdbc:postgresql://localhost:5432/test ", jdbcUrl);
}
}
}
```
3. **Run the Test**:
- Run the test using your IDE’s test runner.
- When the test starts, it will pull the postgres:13.1 image (if not already downloaded), start a PostgreSQL container, and print the JDBC connection URL.
---
### **Step 3: Verify Test Behavior**
- You should see the test passing with a printed message like:
```
PostgreSQL running at: jdbc:postgresql://localhost:5432/test
```
- The container is automatically stopped when the test finishes. No leftover containers!
---
## **Example 2: Running Integration Tests with Testcontainers**
Next, let’s write a real-world test for a simple **Spring Boot** application that connects to a PostgreSQL database.
### **Step 1: Set Up a Simple Spring Boot Project**
1. **Create a Spring Boot Project**:
- Use [Spring Initializr](https://start.spring.io/ ) to create a new Spring Boot project with the following dependencies:
- Spring Web
- Spring Data JPA
- PostgreSQL Driver
- Spring Boot Test
2. **Add Testcontainers Dependencies**:
- Add the following to your pom.xml:
```xml
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>postgresql</artifactId>
<version>1.17.3</version>
<scope>test</scope>
</dependency>
```
---
### **Step 2: Create a JPA Entity and Repository**
1. **Create an Entity**:
- Inside your src/main/java folder, create a class User.java:
```java
import javax.persistence.Entity;
import javax.persistence.Id ;
@Entity
public class User {
@Id
private Long id;
private String name;
// Getters and Setters
}
```
2. **Create a Repository**:
- Now, create an interface UserRepository.java:
```java
import org.springframework.data .jpa.repository.JpaRepository;
public interface UserRepository extends JpaRepository<User, Long> {
}
```
---
### **Step 3: Write an Integration Test Using Testcontainers**
Let’s now use Testcontainers to write an integration test that will verify our UserRepository works correctly.
1. **Create a Test Class**:
- In the src/test/java folder, create UserRepositoryTest.java:
```java
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.testcontainers.containers.PostgreSQLContainer;
import static org.assertj.core.api.Assertions.assertThat;
@SpringBootTest
class UserRepositoryTest {
@Autowired
private UserRepository userRepository;
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:13.1");
static {
postgres.start();
System.setProperty("spring.datasource.url", postgres.getJdbcUrl());
System.setProperty("spring.datasource.username", postgres.getUsername());
System.setProperty("spring.datasource.password", postgres.getPassword());
}
@Test
void testCreateUser() {
User user = new User();
user.setId(1L);
user.setName("John Doe");
userRepository.save (user);
User savedUser = userRepository.findById(1L).get();
assertThat(savedUser.getName()).isEqualTo("John Doe");
}
}
```
2. **Run the Test**:
- When you run this test, it will:
- Start a PostgreSQL container.
- Use the container as the database for your Spring Boot application.
- Create a user and verify it was saved correctly.
---
## **Example 3: Testing Microservices with Docker Compose**
Microservices often need to communicate with other services, such as message brokers or other APIs. Testcontainers supports **Docker Compose** to run multi-container environments for more complex tests.
### **Step 1: Set Up a Docker Compose File**
We’ll create a microservice test environment with PostgreSQL and RabbitMQ.
1. **Create a docker-compose.yml**:
- Create a docker-compose.yml file in the root of your project:
```yaml
version: '3'
services:
db:
image: postgres:13.1
environment:
POSTGRES_DB: mydb
POSTGRES_USER: user
POSTGRES_PASSWORD: pass
ports:
- 5432:5432
rabbitmq:
image: rabbitmq:3-management
ports:
- 5672:5672
- 15672:15672
```
---
### **Step 2: Write a Test Using Docker Compose**
1. **Create a Test Class**:
- Now let’s create a test that uses both PostgreSQL and RabbitMQ:
```java
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
import org.testcontainers.containers.DockerComposeContainer;
import java.io .File;
@SpringBootTest
public class MicroserviceTest {
static DockerComposeContainer<?> compose =
new DockerComposeContainer<>(new File("src/test/resources/docker-compose.yml"))
.withExposedService("db", 5432)
.withExposedService("rabbitmq", 5672);
static {
compose.start();
}
@Test
void testServicesAreRunning() {
assert compose.getServiceHost("db", 5432).equals("localhost ");
assert compose.getServiceHost("rabbitmq", 5672).equals("localhost ");
}
}
```
2. **Run the Test**:
- This test uses Docker Compose to start both PostgreSQL and RabbitMQ and verifies that they are running. This is a basic setup for testing microservices.
---
## **Example 4: Integrating Testcontainers into a CI/CD Pipeline (GitHub Actions)**
Finally, let’s integrate Testcontainers into a **CI pipeline** using GitHub Actions.
### **Step 1: Create a GitHub Actions Workflow**
1. **Create a .github/workflows/test.yml** file in your project:
```yaml
name: Test with Testcontainers
on:
push:
branches:
- main
jobs:
test:
runs-on: ubuntu-latest
services:
docker:
image: docker:20.10.8
options: --privileged
ports:
- 5432:5432
- 5672:5672
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Set up JDK 11
uses: actions/setup-java@v1
with:
java-version: '11'
- name: Cache Maven packages
uses: actions/cache@v2
with:
path: ~/.m2
key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
restore-keys: ${{ runner.os }}-maven
- name: Run tests
run: mvn test
```
2. **Push the Changes**:
- Push your code to GitHub.
- GitHub Actions will automatically start your tests, running them in a Docker-enabled environment.
---
## **Summary: From Beginner to Real-World Applications**
- **Example 1**: Showed how to set up Testcontainers and run your first container-based test
.
- **Example 2**: Covered real-world integration testing with Spring Boot and PostgreSQL.
- **Example 3**: Introduced multi-container testing for microservices using Docker Compose.
- **Example 4**: Demonstrated how to integrate Testcontainers into a CI/CD pipeline using GitHub Actions.
These practical examples guide you from basic setups to advanced testing scenarios, helping you build a solid foundation in using Testcontainers for real-world applications.