Testcontainers لجافا: دليل شامل مع أمثلة عملية

1. ما هي Testcontainers ولماذا تحتاجها؟

Testcontainers هي مكتبة قوية للغة Java (ولغات JVM الأخرى) تتيح لك تشغيل حاويات Docker مباشرة داخل اختبارات التكامل الخاصة بك. بدلاً من الاعتماد على قواعد بيانات خارجية، أو وسطاء رسائل، أو خدمات أخرى قد لا تكون متاحة أو قد تكون مهيأة بشكل مختلف في بيئات مختلفة، تقوم Testcontainers تلقائياً برفع الحاويات اللازمة قبل الاختبار وتدميرها بعد الانتهاء. وهذا يضمن نقاء الاختبارات وقابليتها للتكرار.

لماذا تحتاجها؟ غالباً ما تعاني اختبارات التكامل التقليدية من "مشكلة البيئة": قد ينجح الاختبار على جهاز المطور ولكنه يفشل على خادم CI بسبب إصدار مختلف من قاعدة البيانات أو عدم وجود خدمة معينة. Testcontainers تحل هذه المشكلة نهائياً. أنت تصف البنية التحتية المطلوبة (مثلاً "PostgreSQL 15 مع تفعيل ملحق uuid-ossp") مباشرة في كود الاختبار، وتضمن المكتبة إنشاء هذه البنية التحتية في حاوية Docker معزولة. وهذا يجعل الاختبارات محمولة وموثوقة حقاً.

المكتبة مفيدة بشكل خاص لاختبار طبقات DAO، والمستودعات، والخدمات التي تتعامل مع قوائم الانتظار (RabbitMQ، Kafka)، وذاكرة التخزين المؤقت (Redis)، وحتى لاختبار عملاء HTTP باستخدام حاويات WireMock أو Nginx. توفر Testcontainers أيضاً وحدات مريحة للتقنيات الشائعة (PostgreSQL، MySQL، MongoDB، Redis، Kafka، LocalStack وغيرها الكثير)، مما يقلل من جهد الإعداد إلى الحد الأدنى.

2. التثبيت

يتم توزيع Testcontainers عبر Maven Central. لإضافتها إلى مشروع Java، أضف التبعية التالية إلى ملف pom.xml (Maven) أو build.gradle (Gradle).

Maven (pom.xml)

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <version>1.19.7</version> <!-- تحقق من أحدث إصدار على Maven Central -->
    <scope>test</scope>
</dependency>

<!-- وحدات إضافية، مثلاً لـ PostgreSQL -->
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>postgresql</artifactId>
    <version>1.19.7</version>
    <scope>test</scope>
</dependency>

Gradle (build.gradle)

testImplementation 'org.testcontainers:testcontainers:1.19.7'
testImplementation 'org.testcontainers:postgresql:1.19.7'

هام: تأكد من تثبيت Docker Engine وتشغيله على جهازك (أو وكيل CI). تتفاعل Testcontainers مع Docker عبر socket. إذا كنت تستخدم Docker Desktop على macOS أو Windows، فيجب تشغيله. على Linux، تأكد من أن المستخدم الذي يقوم بتشغيل الاختبارات لديه صلاحيات العمل مع Docker (مثلاً من خلال مجموعة docker).

3. البداية السريعة — مثال عملي بسيط

لنكتب اختباراً بسيطاً يقوم بتشغيل حاوية PostgreSQL، وإنشاء جدول، وإدراج بيانات، والتحقق منها. هذا مثال "Hello, World!" الكلاسيكي لـ Testcontainers.

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 // تفعيل الإدارة التلقائية لدورة حياة الحاويات
class QuickStartTest {

    // @Container تشير إلى أنه يجب إدارة الحاوية (تشغيلها قبل الاختبار، إيقافها بعده)
    @Container
    private PostgreSQLContainer postgres = new PostgreSQLContainer<>("postgres: