هل ما زلنا بحاجة إلى testcontainers مع Spring Boot 3.1؟
صدر Spring Boot 3.1 للتو حاملًا وحدة جديدة كليًا هي spring-boot-docker-compose. لنرَ ما إذا كانت تستطيع أن تحل محل testcontainers في اختبارات التكامل لدينا وأثناء التطوير المحلي.
قدّم Spring Boot 3.0، الذي صدر في نوفمبر 2022، الكثير من الميزات الجديدة المثيرة، وبعد أشهر قليلة فقط يحافظ فريق spring على الوتيرة نفسها – فقد صدر Spring Boot 3.1 للتو. وهو يحمل عددًا ضخمًا من الميزات الجديدة، وتركز هذه المقالة على وحدة spring-boot-docker-compose الجديدة كليًا، التي تستطيع تشغيل الخدمات المعرَّفة في docker-compose وإيقافها تلقائيًا أثناء التطوير المحلي. ما إن لاحظتها حتى خطر ببالي سؤال: “هل يعني هذا أنني أستطيع تشغيل حاويات الاختبار بملف docker-compose.yml القديم الجيد والاستغناء عن testcontainers تمامًا؟”. حسنًا… دعوني أوضح ما أقصده.
لماذا أحتاج إلى كل هذا؟
يكتب كل منا شيفرة تعتمد على خدمات خارجية مثل قواعد البيانات أو الطوابير لحفظ بعض البيانات. وتشغيل هذه الاعتماديات الخارجية لتطبيقنا في حاويات docker قد يبسّط سير عمل التطوير كثيرًا. فيمكننا تشغيل التطبيق مقابل الإصدارات نفسها تمامًا من الاعتماديات الخارجية كما في الإنتاج، مما يمنحنا الثقة بأنه يعمل بشكل صحيح. أما بدؤها وإيقافها يدويًا ففكرة سيئة، خاصة عندما نحتاج إلى تشغيل اختبارات تكامل للتحقق، مثلًا، من أن التطبيق يعمل بشكل صحيح مع قاعدة بيانات مختارة.
لحسن الحظ توجد مكتبة ممتازة لهذا الغرض، هي testcontainers، التي تستطيع تشغيل أي حاوية نحتاجها وإيقافها وتتولى عنا دورة حياة الحاوية. وبفضل testcontainers تعمل اختبارات التكامل لدينا والتطبيق متصل باعتماديات بالإصدارات نفسها كما في الإنتاج، ويحدث كل شيء تلقائيًا. وليس هذا فحسب: بل يمكننا حتى تشغيل تطبيقنا محليًا وترك testcontainers تشغّل هذه الحاويات عنا. إنه لشعور رائع أن تكتب أمرًا واحدًا أو تنقر زرًا واحدًا في بيئة التطوير IDE وترى التطبيق يعمل! لكن هل يمكن فعل الشيء نفسه مع spring-boot-docker-compose؟ هل نستطيع استخدامها في الاختبارات وفي التطوير المحلي معًا، فنستبدل testcontainers المحبوبة بميزات spring boot وحدها؟ لنرَ.
ما الذي نهدف إليه؟
سنصف ما نريد تحقيقه باستخدام spring-boot-docker-compose عبر تطبيق مبني على testcontainers.
يعتمد التطبيق على MongoDB ويحفظ فيها مستندين بسيطين، مما يتيح لنا تشغيل اختبارين بسيطين على مجموعتين (collections) منفصلتين؛ ومع ذلك نريد حاوية واحدة فقط، وهذا أحد أهدافنا: تشغيل نسخة واحدة من حاوية معينة لكل الاختبارات للحفاظ على سرعة اختباراتنا.
هذه هي مستندات MongoDB لدينا
@Document
public record Article(@Id ArticleId articleId, Author author, Content content) {
}
public record ArticleId(String id) {
}
public record Author(String name) {
}
public record Content(String text) {
}
@Document
public record User(@Id String id, String name) {
}
سننشئ مستودعات لهذه المستندات باستخدام وحدة spring-data-mongodb.
public interface UsersRepository extends MongoRepository<User, String> {
}
وأخيرًا سنكشف نقاط نهاية HTTP بسيطة تعيد البيانات من هذه المستودعات.
@RestController
@RequestMapping("/api/users")
public class UsersController {
private final UsersRepository usersRepository;
public UsersController(UsersRepository usersRepository) {
this.usersRepository = usersRepository;
}
@GetMapping
public Users getAllUsers() {
var users = usersRepository.findAll();
return new Users(users);
}
}
public record Users(List<User> users) {
}
مستودع المقالات ومتحكم REST الخاص بها متطابقان تقريبًا، لذلك سأتخطاهما هنا.
إعداد اختبارات التكامل باستخدام testcontainers
بعد ذلك سنجهّز الاختبارات وإعدادات testcontainers بحيث تعمل اختباراتنا مقابل MongoDB في docker.
فيما يلي حالة اختبار نموذجية لمجموعة المستخدمين. نحفظ مستخدمًا في قاعدة البيانات ونتحقق من أن الـ API تعيد هذا المستخدم.
@Test
void shouldReturnSavedUser() {
// given
var user = new User(UUID.randomUUID().toString(), "username");
usersRepository.save(user);
// when
Users users = testRestTemplate.getForObject("/api/users", Users.class);
// then
assertThat(users).isEqualTo(new Users(List.of(user)));
}
وتوجد عمليًا اختبارات مماثلة للمقالات.
الآن لنعرّف حاويتنا باستخدام testcontainers.
@TestConfiguration(proxyBeanMethods = false)
public class TestContainersConfiguration {
@Bean
@ServiceConnection
public MongoDBContainer mongoDBContainer() {
return new MongoDBContainer("mongo:6.0.5");
}
}
ولمشاركة سياق spring واحد بين كل اختبارات التكامل، نحتفظ عادةً بفئة أساسية موسومة بـ @SpringBootTest ترثها فئات الاختبار لدينا؛ وبهذه الطريقة لا يُنشأ سوى سياق spring واحد عند تشغيل المجموعة كلها، مما يحافظ على سرعة اختباراتنا. وتحتاج حاوياتنا إلى المعاملة نفسها (يجب أن تبدأ مرة واحدة فقط). وكل ما يلزم هو استيراد TestContainersConfiguration هذه إلى BaseIntegrationTest لدينا
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@Import(TestContainersConfiguration.class)
@ActiveProfiles("test")
public class BaseIntegrationTest {
صه… في حال فاتك الأمر، نحن نعتمد هنا على ميزة رائعة أخرى في Spring Boot 3.1: اتصالات الخدمة (Service Connections). لم تعد مضطرًا إلى تعريف إعدادات الاتصال لحاويتنا (مثل المضيف والمنفذ) بشكل منفصل. فبمجرد وسم bean بـ @ServiceConnection، تُؤخذ إعدادات الاتصال الخاصة به تلقائيًا من الحاوية العاملة.
هذا كل الإعداد المطلوب. عندما نشغّل اختباراتنا الآن، يرفع testcontainers حاوية MongoDB جديدة، ويستخدمها تطبيقنا أثناء الاختبارات.
Container mongo:6.0.5 is starting: 89bd7f517e0eacedae7af96c04cdcf8c8a5878cc8fcec3e57560d1c9b054914c
Container mongo:6.0.5 started in PT1.040507S
استخدام testcontainers أثناء التطوير
بعد أن صارت اختباراتنا تعمل مقابل MongoDB تبدأ تلقائيًا، سنعدّ التطبيق في البيئة المحلية بحيث يشغّل testcontainers حاوية MongoDB لنا هناك أيضًا، وهذا ينقلنا إلى الهدف التالي: استخدام إعداد الحاوية نفسه لتشغيل الاختبارات والتطبيق في البيئة المحلية.
لهذا نحتاج إلى تطبيق رئيسي جديد داخل مصادر الاختبار، ليتمكن من الوصول إلى مسار الفئات الخاص بالاختبار (testcontainers وإعداد الحاويات).
public class TestApplication {
public static void main(String[] args) {
SpringApplication.from(Application::main)
.with(TestContainersConfiguration.class)
.run(args);
}
}
هنا نشغّل SpringApplication بكامل الإعدادات المحمَّلة من Application الرئيسي لدينا، ونضيف فوق ذلك إعداد MongoDB الخاص بـ testcontainers وفئة بسيطة تضع بيانات نموذجية في قاعدة بياناتنا عند البدء في البيئة المحلية.
نريد أيضًا ملء قاعدة البيانات ببيانات نموذجية في البيئة المحلية، لإظهار أن البيانات المحلية وبيانات الاختبار لا تؤثر إحداهما في الأخرى. ولهذا سنستخدم ملفات تعريف spring (profiles) والإعداد التلقائي الشرطي في spring بحيث يُفعَّل تهيئة البيانات محليًا فقط. لدينا هنا ملفا تعريف خاصان، local وtest. هكذا تبدو أداة تهيئة البيانات لدينا.
@Configuration
public class InitialDataForDevelopment {
@Bean
@ConditionalOnProperty(name = "data.initialize", havingValue = "true")
public CommandLineRunner commandLineRunner(UsersRepository usersRepository) {
return args -> usersRepository.save(new User(UUID.randomUUID().toString(), "name"));
}
}
كما ترى، لا تُهيَّأ البيانات النموذجية إلا عند ضبط الخاصية data.initialize=true، وبفضل ملفات تعريف spring يمكننا ضبط data.initialize=true في ملف التعريف المحلي وحده، فتبدأ اختباراتنا بلا أي بيانات. وهذا يقود إلى الهدف المهم التالي: إذا شغّلنا التطبيق الرئيسي أولًا فإنه يملأ قاعدة بياناتنا ببعض البيانات، وبينما هو لا يزال يعمل نريد تشغيل اختباراتنا بحيث لا ترى تلك البيانات – باختصار، نريد أن تكون الحاوية العاملة في البيئة المحلية والاختبارات معزولتين إحداهما عن الأخرى. يوفر لنا testcontainers هذا افتراضيًا. فعندما أشغّل تطبيقي محليًا يبدأ حاوية واحدة.
Creating container for image: mongo:6.0.5
Container mongo:6.0.5 is starting: cd242f72eb33b89542aeb8710c0a0b9fed12cd4fb0feffb5fa443e2b0199f3e7
ثم، وتطبيقي يعمل والبيانات الأولية موجودة، أشغّل اختباراتي، ونرى أن testcontainers بدأ حاوية MongoDB منفصلة لها.
Container mongo:6.0.5 is starting: 40aa3198e15416f98e029f43b0a7846d17161ad707dfd5ffde6246f6861302bd
إذن توجد الآن حاويتان تعملان على جهازي، ولا تتدخل اختباراتي في بيئة التطوير المحلية الخاصة بي.
~/Workspace/demo-spring-boot-testing> docker ps | grep mongo
40aa3198e154 mongo:6.0.5 "docker-entrypoint.s…" 49 seconds ago Up 48 seconds 0.0.0.0:58327->27017/tcp quirky_hawking
cd242f72eb33 mongo:6.0.5 "docker-entrypoint.s…" 29 minutes ago Up 29 minutes 0.0.0.0:57885->27017/tcp cool_jennings
رائع، أليس كذلك؟!
يوجد هدف مهم آخر لم تُظهره الأمثلة أعلاه: تشغيل أي حاوية تحتاجها. مثالنا البسيط يشغّل قاعدة بيانات MongoDB فقط، لكن البيئات الأكثر تعقيدًا تتطلب خدمات أكثر بكثير، مثل Kafka أو Mockserver أو Neo4j، ويدعمها testcontainers كلها.
وخلاصة أهدافنا:
- القدرة على تشغيل الحاويات للتطوير المحلي
- القدرة على تشغيل الحاويات للاختبارات (مع نسخة واحدة فقط من حاوية معينة)
- إبقاء حاويات الاختبارات وحاويات التطوير المحلي معزولة
- القدرة على تشغيل أي حاوية نريدها
وحدة spring-boot-docker-compose الجديدة عمليًا
لنرَ ما إذا كنا نستطيع بلوغ هدفنا الأول: القدرة على تشغيل الحاويات للتطوير المحلي.
هذا بالضبط ما صُممت الوحدة من أجله، لذا يُفترض أن يكون الأمر بسيطًا جدًا. أولًا نضيف spring-boot-docker-compose إلى اعتمادياتنا؛ ونحن نستخدم maven، فيذهب هذا إلى ملف pom.xml.
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-docker-compose</artifactId>
</dependency>
ثم نصف اعتمادياتنا الخارجية في ملف docker-compose.yml.
version: '3.9'
services:
mongodb:
restart: always
image: mongo:6.0.5
ports:
- 27017:27017
tmpfs:
- /data/db
انتهينا. عندما نبدأ تطبيقنا الآن، يلاحظ spring boot ملف docker-compose.yml ويشغّله لنا. تحقق الهدف الأول.
.s.b.d.c.l.DockerComposeLifecycleManager : Found Docker Compose file 'MY_HOME_DIRECTORY_PATH/demo-spring-boot-testing/docker-compose/docker-compose.yml'
o.s.boot.docker.compose.core.DockerCli : Network docker-compose_default Creating
o.s.boot.docker.compose.core.DockerCli : Network docker-compose_default Created
o.s.boot.docker.compose.core.DockerCli : Container docker-compose-mongodb-1 Creating
o.s.boot.docker.compose.core.DockerCli : Container docker-compose-mongodb-1 Created
o.s.boot.docker.compose.core.DockerCli : Container docker-compose-mongodb-1 Starting
o.s.boot.docker.compose.core.DockerCli : Container docker-compose-mongodb-1 Started
o.s.boot.docker.compose.core.DockerCli : Container docker-compose-mongodb-1 Waiting
o.s.boot.docker.compose.core.DockerCli : Container docker-compose-mongodb-1 Healthy
سهل جدًا، أليس كذلك؟ وبصراحة، اضطررت إلى تعديل إعداد واحد، لأن مشروعي متعدد الوحدات وكان لا بد من إخبار spring boot بمكان ملف docker-compose.yml – لكنه مجرد سطر بسيط واحد في application.properties. والسبب أنه يبحث عن ملف الإعداد في مجلد العمل الحالي، وفي مشروع متعدد الوحدات يختلف مجلد العمل بحسب ما إذا كنت أشغّل الاختبارات أو الفئة الرئيسية من بيئة التطوير؛ ولهذا ضبطته يدويًا، وبالطبع تعمل أيضًا أوامر مثل ./mnvw test. أما في مشروع وحدة واحدة فيكفي أن تضع ملف docker-compose.yml في المجلد الجذر للمشروع وينتهي الأمر.
spring.docker.compose.file=./docker-compose/docker-compose.yml
ننتقل إلى الهدف التالي: القدرة على تشغيل الحاويات للاختبارات (مع نسخة واحدة فقط من حاوية معينة لكل الاختبارات)
كان افتراضي الأول أن لا حاجة إلى أي عمل إضافي وأن الأمر سيعمل ببساطة (فملف docker-compose.yml موجود أصلًا). لكن تبيّن أن spring boot افتراضيًا لا يشغّل الحاويات المعرَّفة في docker-compose.yml أثناء الاختبارات – إذ تُتخطى هذه الخطوة. ومع ذلك يتحكم في هذا السلوك مفتاح، فلنقلبه.
spring.docker.compose.skip.in-tests=false
بهذا الإعداد الصغير يمكن لاختباراتنا استخدام حاوية MongoDB من docker compose! وفيما يلي سجلات من تشغيل اختبار تُظهر بدء الحاوية. وبالطبع نجحت كل الاختبارات، ولم تبدأ الحاوية إلا مرة واحدة للمجموعة كلها.
.s.b.d.c.l.DockerComposeLifecycleManager : Found Docker Compose file 'MY_HOME_DIRECTORY_PATH/Workspace/demo-spring-boot-testing/docker-compose/docker-compose.yml'
o.s.boot.docker.compose.core.DockerCli : Container docker-compose-mongodb-1 Created
o.s.boot.docker.compose.core.DockerCli : Container docker-compose-mongodb-1 Starting
o.s.boot.docker.compose.core.DockerCli : Container docker-compose-mongodb-1 Started
o.s.boot.docker.compose.core.DockerCli : Container docker-compose-mongodb-1 Waiting
o.s.boot.docker.compose.core.DockerCli : Container docker-compose-mongodb-1 Healthy
يمكن شطب الهدف الثاني.
الهدف الثالث: إبقاء حاويات الاختبارات وحاويات التطوير المحلي معزولة
هنا واجهتُ أول عيب. للأسف، ليس من السهل إعداد الأمور بحيث تعمل الحاويات في البيئة المحلية منفصلة عن تلك المستخدمة في الاختبارات. والسبب أن الوحدة الجديدة تقرر ما إذا كانت ستبدأ حاويات جديدة بناءً على فحص بسيط فقط لما يعيده الأمر docker compose ps. فإذا كانت أي خدمات تعمل بالفعل، لا تُنشأ حاويات جديدة، وتنتهي اختباراتنا متصلة بالحاوية التي بدأت للتطوير المحلي. يمكنك أن ترى كيف يعمل هذا داخليًا هنا وهنا. ونتيجة لذلك، فإن محاولة تشغيل هذه الحاويات مع قواعد بيانات أو شبكات docker أو حتى ملفات تعريف docker compose مختلفة ستفشل.
الحل البديل الوحيد الذي توصلت إليه هو ملف docker-compose.yml منفصل لكل بيئة (المحلية والاختبار هنا)، يوضع كل منها في مجلد خاص به. إن الاحتفاظ بعدة ملفات docker-compose.yml بإعدادات متطابقة ليس جيدًا، لكن لحسن الحظ يوفر docker compose الامتدادات (Extensions). ولتجنب التكرار يمكننا وضع إعداد الخدمة بأكمله تقريبًا في ملف docker-compose.yml مشترك واحد، ثم إعادة استخدام هذا التعريف المشترك في docker-compose-local.yml وdocker-compose-test.yml مع تعديلات صغيرة – ففي حالة MongoDB علينا أن نكشف منافذ مختلفة ليتمكن حاويتان من العمل جنبًا إلى جنب. هذه ملفات docker-compose الجديدة لدي.
./docker/docker-compose-common.yml
version: '3.9'
services:
mongodb:
restart: always
image: mongo:6.0.5
tmpfs:
- /data/db
./docker/local/docker-compose-local.yml
version: '3.9'
services:
mongodb-local:
extends:
file: ../docker-compose-common.yml
service: mongodb
ports:
- 27017:27017
./docker/test/docker-compose-test.yml
version: '3.9'
services:
mongodb-test:
extends:
file: ../docker-compose-common.yml
service: mongodb
ports:
- 27018:27017
أدرك أن هذا ليس مثاليًا وأنه تطلب بعض العبث مع docker compose، لكن بحساب كل شيء، أستطيع القول إن هذا الهدف قد تحقق.
وأخيرًا وليس آخرًا: القدرة على تشغيل أي حاوية نريدها
هنا اصطدمنا بمشكلة ثانية، وإن كانت أصغر بكثير. في الوقت الحالي لا نستطيع تشغيل أي حاوية مباشرةً – بل تُدعم حفنة منها فقط (وهذا على الأرجح كافٍ لمعظم حالات الاستخدام). فمثلًا MongoDB وRedis وPostgreSQL وCassandra وElasticsearch تعمل دون أي شيفرة إضافية، لكن إذا احتجت إلى شيء لا تغطيه الوحدة بعد، مثل Kafka أو Neo4j، فعليك كتابة تنفيذك الخاص لـ DockerComposeConnectionDetailsFactory يبني لك ConnectionDetails. وهذه قطعة شيفرة أخرى عليك صيانتها، فليس هذا مثاليًا. ومع ذلك، فالأرجح أنها مسألة وقت فقط قبل أن تكتسب spring-boot-docker-compose المزيد من تطبيقات DockerComposeConnectionDetailsFactory.
الخاتمة
كما رأينا، وحدة spring-boot-docker-compose الجديدة قوية جدًا وبسيطة الاستخدام. قد يكون عزل الحاويات صعبًا بعض الشيء في الإعداد، ويفرض بعض التكرار في ملفات ‘docker-compose.yml’ لدينا، لكنها تستطيع فعل كل ما فعلناه بـ testcontainers. كما أنها تدعم حاويات أقل جاهزة للاستخدام مقارنة بـ testcontainers (وهذا لا ينبغي أن يهم في معظم الحالات، وأنا واثق من أن المزيد سيأتي في الإصدارات القادمة). يبدو أن لاعبًا كبيرًا جديدًا قد وصل وسيهز الوضع القائم.
وفي المحصلة، أخشى أنني لا أستطيع أن أقول لك هل ينبغي أن تنتقل إلى spring-boot-docker-compose بدلًا من testcontainers. هذا خيار عليك اتخاذه بنفسك. وأعتقد أن هذه المقالة غطت معظم السيناريوهات التي قد ترغب فيها بحاويات docker في سير عمل التطوير لديك، لكن ضع في اعتبارك أن الوحدة جديدة تمامًا وتفتقر إلى بعض الميزات التي يقدمها testcontainers، مثل تشغيل الحاويات بالتوازي أو إعادة استخدامها، على سبيل المثال لا الحصر.