كيفية اختبار نشرات معاينة Vercel تلقائيًا في 2026

الإجابة المختصرة

لا تحتاج إلى إضافة ملف سير عمل، ولا إلى كتابة نص برمجي يستخرج رابط المعاينة من سجلات البناء. يُثبَّت TestSprite كتطبيق GitHub، ويستمع لحدث النشر الذي ينتجه خط الأنابيب لديك بالفعل، ويستنتج رابط المعاينة من نمط تحدده مرة واحدة، ويشغّل اختباراتك عليه، وينشر النتيجة كتعليق على طلب السحب.

يستغرق الإعداد نحو عشر دقائق، ويتطلب صلاحيات المسؤول لتثبيت تطبيق GitHub، ولا يتطلب أي تغييرات على مستودعك.

شرط مسبق: تأكد من أن طلب السحب ينتج نشرًا

يُشغَّل TestSprite بواسطة حدث نشر، لذا يجب أن يكون هذا الحدث موجودًا قبل أن يعمل أي شيء آخر. افتح أي طلب سحب موجود وتأكد من ظهور نشر برابط قابل للنقر، ثم افتح ذلك الرابط وتحقق من أن بيئة المعاينة تُحمَّل بالفعل.

في Vercel، يظهر هذا كتعليق من بوت على طلب السحب يسرد المشروع، وحالة Ready، ورابطًا للمعاينة. تُنتج AWS Amplify وNetlify وخطوط الأنابيب المستضافة ذاتيًا التي تُنشئ نشرات GitHub نفس الإشارة بتنسيقها الخاص — المهم هو أن يكون النشر موجودًا وأن يكون رابطه قابلاً للوصول.

الخطوة 1 — اربط GitHub بمساحة عملك

هذا إعداد يتم مرة واحدة لكل مساحة عمل. في TestSprite، انتقل إلى Workspace Settings → Integrations، وابحث عن صف GitHub، وانقر على Connect. ستتم إعادة توجيهك إلى GitHub لاختيار المؤسسة أو الحساب الشخصي المالك للمستودع، ثم اختر All repositories أو Only select repositories وانقر على Install & Authorize.

من المفيد معرفة الأذونات المطلوبة قبل الموافقة عليها:

يُستخدم إذن الكتابة لنشر نتائج الاختبار على طلبات السحب والالتزامات الخاصة بك. لا يقوم TestSprite بدفع التزامات (commits) أو تعديل ملفات سير العمل لديك. إذا لم تظهر مؤسستك أثناء التثبيت، فأنت لا تملك إذن تثبيت تطبيقات GitHub لها — يحتاج مالك المؤسسة إلى الموافقة عليه.

الخطوة 2 — اربط المستودع بمشروع

افتح مشروع TestSprite الذي تريد ربطه، وانتقل إلى تبويب GitHub Action، وانقر على Connect GitHub Action. ثم اختر الطريقة التي ستُشغَّل بها الاختبارات:

يكفي مُشغِّل واحد للبدء. يمكنك إنشاء كليهما — إذ يعملان بشكل مستقل عن بعضهما.

الخطوة 3 — اختر الحدث الذي يعني "اكتمال النشر"

اختر تبويب Pull Request، والصق رابط طلب سحب موجود لديه نشرة معاينة تعمل، وانقر على Detect Events. يسرد TestSprite أحداث CI/CD التي وجدها على ذلك الطلب — فحوصات GitHub Actions، وتعليقات البوت من Vercel أو Amplify، وتشغيلات سير العمل — وتختار أنت أيها يبدأ التشغيل.

اختر الحدث الذي يُطلَق بعد أن يصبح النشر فعليًا ويكون الرابط قابلاً للوصول. هذا هو الخطأ الأكثر شيوعًا في الإعداد: فالحدث الذي يُطلَق عند بدء البناء سيشغّل اختباراتك على رابط لم يصبح متاحًا بعد، وستفشل كل الاختبارات.

الخطوة 4 — أدخل نمط رابط الهدف

يُسمّي كل مزود استضافة روابط المعاينة بطريقة مختلفة، لذا تُخبر TestSprite بكيفية بناء الرابط لأي طلب سحب معيّن. تتوفر خمسة عناصر نائبة (placeholders):

طابق النمط مع رابط معاينة حقيقي، حرفًا بحرف:

تُبنى أسماء مضيفي المعاينة الافتراضية في Vercel من اسم الفرع، ولهذا يكون {branch-slug} عادة العنصر النائب الصحيح هناك بدلًا من {pr}. إذا كان مضيفك يُنشئ نطاقات فرعية عشوائية لا يمكن التنبؤ بها، فاضبط رابط اسم مستعار (alias) ثابتًا لبيئة المعاينة واستخدمه بدلًا من ذلك.

لا يحتاج مُشغِّل الدفع (push trigger) إلى أي نمط على الإطلاق — فهو يعمل على الرابط المضبوط لأي بيئة TestSprite تحددها، لذا اختر Dev لـ dev أو Production لـ main.

الخطوة 5 — أرسل حدث اختبار قبل الحفظ

انقر على Send Test Event. يشغّل هذا اختباراتك على طلب السحب النموذجي تمامًا كما يفعل المُشغِّل الحقيقي، بحيث يمكنك معاينة سير العمل بأكمله قبل الالتزام به. انتظر نحو 30 ثانية، ثم عد إلى طلب السحب على GitHub — سيظهر تعليق من TestSprite.

افتح الرابط الموجود في ذلك التعليق قبل المتابعة. تأكد من أنه قابل للوصول ويشير إلى البيئة التي تتوقعها. إذا كان خاطئًا، فصحّح النمط وأرسل حدث اختبار آخر بدلًا من الانتظار حتى طلب السحب التالي لاكتشاف ذلك. بمجرد اكتمال التشغيل، يُحدّث TestSprite التعليق نفسه بالنتيجة.

عندما يبدو حدث الاختبار صحيحًا، انقر على Create Trigger. سيظهر في قائمة Triggers بعلامة Active، ويعمل تلقائيًا على كل طلب سحب مستقبلي. هناك مفتاحان اختياريان يستحقان الضبط بعناية:

إذا كانت معاينتك تقع خلف Deployment Protection

هذا هو نمط الفشل الذي يبدو وكأنه إعداد ناجح. عند تفعيل Deployment Protection في Vercel، يقع كل رابط معاينة خلف جدار مصادقة، ويتلقى المُختبِر الخارجي صفحة تسجيل الدخول بدلًا من تطبيقك. لا تُخفق الاختبارات — بل تصف صفحة لم يتوقعها أحد.

يكتشف الفحص في الخطوة 5 ذلك: افتح الرابط من تعليق TestSprite في نافذة خاصة. إذا رأيت شاشة تسجيل دخول Vercel، فالحماية مفعّلة. الطريقتان للمضي قدمًا هما تعطيل الحماية عن بيئة المعاينة، أو استخدام Protection Bypass for Automation من Vercel، الذي يُنشئ سرًا تقبله Vercel كمعامل استعلام x-vercel-protection-bypass وكذلك كترويسة (header). ولأن نمط رابط الهدف هو مجرد رابط، يمكن إلحاق صيغة معامل الاستعلام به:

https://app-git-{branch-slug}-team.vercel.app?x-vercel-protection-bypass=YOUR_SECRET

أنشئ السر ضمن Project Settings → Deployment Protection → Protection Bypass for Automation. كن حذرًا بشأن هذا الخيار — فهو يخزّن سر تجاوز في حقل إعدادات، لذا يكون تعطيل الحماية عن بيئات المعاينة الخيار الأنظف عندما لا تحتوي معايناتك على أي شيء حساس.

قراءة النتيجة

عند اكتمال التشغيل، يُحدّث TestSprite تعليق طلب السحب — أو فحص الالتزام — بالنتيجة. التعليق منظّم، والصف الأخير هو الأهم إذا كان وكيل ذكاء اصطناعي هو من كتب الشيفرة:

ترتبط كل نتيجة بالتقرير الكامل في TestSprite.

تحقق من إعدادك

قبل الاعتماد على هذا التكامل، تأكد من النقاط الخمس التالية:

1. يظهر تكامل GitHub كـConnected في مساحة عملك

2. يظهر المستودع داخل تبويب GitHub Action الخاص بالمشروع

3. يوجد مُشغِّل مُدرَج ومُفعَّل

4. أنتج حدث اختبار تعليقًا من TestSprite (طلب سحب) أو فحصًا (دفع)

5. يفتح الرابط في ذلك التعليق أو الفحص البيئة المنشورة الصحيحة

استكشاف الأخطاء وإصلاحها

البديل عبر سطر الأوامر

تطبيق GitHub هو الحل الصحيح عندما ينتج خط الأنابيب لديك نشرات بالفعل. إذا كنت تفضّل تشغيل الاختبار من سير عملك الخاص — أو لست على GitHub أصلًا — فإن أداة سطر الأوامر مفتوحة المصدر TestSprite CLI تؤدي المهمة نفسها من أي نظام CI. وهي مجانية التثبيت ومرخّصة بموجب Apache-2.0:

npm install -g @testsprite/testsprite-cli
testsprite setup

وجّه مشروعًا إلى رابط قمت بحله بالفعل، وشغّل المجموعة للوصول إلى نتيجة:

testsprite project update prj_abc123 --url "$PREVIEW_URL"
testsprite test run --all --project prj_abc123 --wait --output json
#   exit 0 = everything passed, exit 1 = something is broken

testsprite ci init github ينشئ هيكل سير عمل لهذا المسار، ولا تحتاج أداة سطر الأوامر إلا إلى TESTSPRITE_API_KEY في البيئة، لذا يمكن إدراجها بنفس السهولة في CircleCI أو GitLab أو Jenkins أو Azure Pipelines. استخدم --report junit --report-file <path> للحصول على تقرير جانبي تستوعبه هذه الأنظمة بشكل أصلي.

إذا كانت التدفقات التي تهمك تقع خلف تسجيل الدخول الخاص بتطبيقك، فخزّن حساب اختبار على المشروع حتى تتمكن عمليات التشغيل من المصادقة. كلا العلامتين (flags) مطلوبتان معًا:

testsprite project update prj_abc123 \
  --username qa@example.com \
  --password-file ./.secrets/qa-password

الأسئلة الشائعة