المدونة والأدلة
فحوص السيناريوهات: اختبارات وحدة لتغييرات الأعلام
السيناريو تأكيد محفوظ عن علم: هذا السياق يحصل على هذه القيمة. كيف تقيّم NanoFlags السيناريوهات على المسودة، ولماذا يرتبط التشغيل الناجح ببصمة المسودة الدقيقة، ومن يحق له إنتاج تشغيل يُعتدّ به، وكيف تشغّلها في CI.
فريق هندسة NanoFlagsنُشر في 3 دقائق قراءة
في هذه الصفحة
أغلب حوادث الأعلام لا يسبّبها الكود الذي خلف العلم، بل يسبّبها تغيير في الإعداد: قاعدة نُقلت فوق أخرى، أو شريحة عُدّلت لحملة واحدة بينما يستخدمها علم آخر، أو نسبة طرح كُتبت في البيئة الخطأ. التغيير صغير، ويبدو سليمًا في المراجعة، ولم يُشغّل أحد عليه شيئًا. فحوص السيناريوهات هي خطوة الاختبار الناقصة.
ما هو السيناريو
السيناريو فحص محفوظ من ثلاثة أجزاء: علم، وسياق تقييم، والقيمة التي تتوقعها. مثلًا: «المستخدم المسجَّل في الولايات المتحدة يحصل على true للعلم checkout-v2»، أو «الحساب على خطة enterprise يحصل على ترتيب relevance-v2». تكتبه مرة واحدة في لوحة التحكم بجانب العلم.
تقيّم NanoFlags السيناريوهات بمحرك التقييم نفسه الذي تستخدمه حِزم SDK، إمّا على مسودة البيئة (ما توشك على نشره) أو على نسختها المنشورة (ما يعمل الآن).
ما معنى «نجح»
- القيمة الفعلية تساوي القيمة المتوقعة مساواةً عميقة: ترتيب مفاتيح الكائن لا يهم، وترتيب المصفوفة يهم، ولا تحويل للأنواع (
"1"ليست1). - السيناريو الذي لا يوجد علمه (
flag_not_found) أو يفشل تقييمه لا ينجح أبدًا، حتى لو كان يتوقعnull. فالعلم المحذوف لا يمكنه أن يجتاز اختباراته بصمت. - يسجّل كل تشغيل، لكل سيناريو، القيمة الفعلية والسبب الذي أعطاه المحرك (
rule_matchأو طرح تدريجي أو القيمة الافتراضية)، فيخبرك الفشل بالقاعدة التي أجابت.
السيناريوهات بوابةً للنشر
يمكن للبيئة أن تشترط السيناريوهات. عندها لا يُقبل النشر إلا إذا نجح كل سيناريو ضمن النطاق على المسودة الدقيقة التي تُنشر: يسجّل التشغيلُ بصمة المسودة، وتقارنها قاعدة البيانات لحظة النشر. عدّل المسودة بعد التشغيل ولو بحرف واحد، فلا يعود التشغيل محتسبًا. والنطاق هو سيناريوهات أعلام التغيير، أو كل سيناريو موسوم «ضمن CI» عند النشر دون تغيير.
قاعدتان تحفظان نزاهة الدليل:
- بالنسبة للتغيير، تُحتسب التشغيلات التي تتم بمفتاح CI، وكذلك تشغيلات لوحة التحكم التي يجريها شخص غير كاتب التغيير وغير من عدّلوا مسودته. أمّا تشغيلات الكاتب نفسه من لوحة التحكم فتُحفظ دليلًا لكنها لا تستوفي الشرط.
- تعديل علم السيناريو أو سياقه أو قيمته المتوقعة ينشئ نسخة جديدة من السيناريو، فلا تعود تشغيلات التعريف السابق محتسبة؛ ولا يمكن إضعاف اختبار بعد نجاحه.
اشتراط السيناريوهات وتسجيل تشغيلات CI جزء من خطة Team فما فوق؛ وفي خطة Explore يمكنك كتابة السيناريوهات وتشغيلها من لوحة التحكم. وتبدأ بيئات Production الجديدة في Team وScale وهذا الشرط مفعّل.
تشغيل السيناريوهات في CI
تشغّل أداة سطر الأوامر كل سيناريو موسوم «ضمن CI» وتنتهي برمز خروج غير صفري عند فشل أحدها:
$ NANOFLAGS_KEY=nf_ci_… nanoflags scenarios run --source draft
RESULT SCENARIO FLAG EXPECTED ACTUAL REASON
pass US signed-in gets v2 checkout-v2 true true rule_match
FAIL EU stays on v1 checkout-v2 false true rule_match
1 passed, 1 failed · source draft · checksum 3f2a… · published r12وفي GitHub Actions، يغلّف إجراء NanoFlags الأمر نفسه، ويسجّل التشغيل مقابل الـ commit، ويكتب الجدول في ملخص المهمة. استخدم مفتاح CI: فهو يشغّل السيناريوهات ويقرأ الإعداد لكنه لا يستطيع النشر، فلا يستطيع مفتاح CI مسرَّب تغيير ما يحصل عليه مستخدموك.
name: Flags
on:
pull_request: # NOT pull_request_target
push:
branches: [main]
permissions:
contents: read
jobs:
scenarios:
runs-on: ubuntu-latest
if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- uses: motazalmaroai/nanoflags-sdk/integrations/github-action@main # pin to a commit SHA in production
with:
key: ${{ secrets.NANOFLAGS_CI_KEY }}
source: draftاستخدم source: draft لفحص ما توشك على نشره، أو source: revision لفحص ما يعمل الآن. ويمكن لأي نظام CI آخر استدعاء الأداة مباشرة:
export NANOFLAGS_KEY="$NANOFLAGS_CI_KEY" # from your CI secret store
nanoflags scenarios run --source draft --commit "$COMMIT_SHA" --run-url "$BUILD_URL"
# exit 0: all passed · 1: a scenario failed · 2: key or usage problem · 3: NanoFlags unreachableكتابة سيناريوهات تلتقط الأخطاء الحقيقية
- ثبّت الحواف لا المنتصف. سيناريو لكل حدّ قاعدة: أول سياق يجب أن يطابق القاعدة، وأقرب سياق يجب ألّا يطابقها (المستخدم الأوروبي بجانب قاعدة الولايات المتحدة).
- أكّد القيمة الافتراضية. سياق لا يطابق أي قاعدة ويتوقع القيمة الافتراضية يلتقط قاعدة جديدة أوسع مما أُريد لها.
- غطِّ الشرائح المشتركة من كل علم يستخدمها. تعديل الشريحة هو المثال الكلاسيكي لـ«تغيير صغير وأثر كبير»؛ والسيناريوهات على كل علم معتمد عليها تحوّله إلى فشل ظاهر.
- اختبر حالة الإيقاف. إن كان العلم موقوفًا في بيئة، فسيناريو يتوقع قيمة الإيقاف يوثّق أن ذلك مقصود.
- استخدم مفتاح استهداف ثابتًا للطرح التدريجي. التوزيع على الشرائح حتمي (MurmurHash3 لبذرة الطرح والمفتاح)، فالسيناريو بمفتاح ثابت يقع دائمًا في الشريحة نفسها ويبقى قابلًا للتكرار.
المرجع: المفاهيم ← السيناريوهات وCI وGitHub Actions. وتعرض صفحة أمان الإصدارات كيف تعمل السيناريوهات مع التغييرات المراجَعة والموافقات.
- scenarios
- testing
- ci
- release safety