غيّر إصدار 4.2.0 في Northwind سطرًا واحدًا: الـ token الخاص بـ line-height لنص المتن، من 1.5 إلى 1.45. بدا كل شيء سليمًا في كل story فحصناها. لكنه دفع أيضًا آخر صف في جدول المسارات في تطبيق الـ dispatch إلى ما تحت حافة الشاشة، على أشيع دقّة شاشة للحواسيب المحمولة، في الكثافة المضغوطة، في الوضع الداكن. لم ينظر أحد إلى تلك التركيبة. ومنذ ذلك الحين صارت القاعدة بسيطة: الآلات تنظر إلى كل تركيبة؛ والبشر ينظرون إلى الفروقات.
الـ story في Storybook تعرض مكوّنًا في حالة واحدة بـ props محدّدة. كتبت stories للتوثيق في القسم السابق؛ والـ stories نفسها هي العمود الفقري للاختبار:
\nplay تنقر وتكتب وتتحقّق، مثل «الضغط على Escape يغلق الـ Dialog ويعيد التركيز إلى الـ trigger».تستطيع إصدارات Storybook الحديثة تشغيل الـ stories كاختبارات عبر تكامل مع Vitest (@storybook/addon-vitest)، فتعمل الملفات نفسها في واجهة Storybook وفي الطرفية وفي الـ CI. وتشترط Northwind story واحدة لكل خانة في مصفوفة الحالات من درس إمكانية الوصول. هذه القاعدة تمنحك تغطية اختبارية شبه مجانية، لأن عمل تصميم الحالات أُنجز أصلًا.
اختبار الانحدار البصري يعرض story، ويلتقط صورة، ويقارنها بكسلًا بكسلًا بصورة مرجعية محفوظة. وإن اختلفتا بما يتجاوز حدًّا معيّنًا، يفشل الاختبار ويعرض الفرق. ثم يقرّر إنسان: إن كان التغيير مقصودًا، يقبله صورةً مرجعية جديدة؛ وإن لم يكن، يصلح الكود.
\nتختار الفرق عادةً أحد إعدادين. خدمة مستضافة مثل Chromatic، التي يصنعها القائمون على Storybook، تعرض الـ stories في السحابة وتعطي المراجعين واجهة ويب لقبول الفروقات. أو تلتقط الصور بنفسك باستخدام Playwright:
\nimport { test, expect } from '@playwright/test';\n\nconst stories = ['components-button--primary', 'components-button--danger', 'components-dialog--confirm'];\nconst themes = ['light', 'dark'];\nconst densities = ['comfortable', 'compact'];\n\nfor (const id of stories) {\n for (const theme of themes) {\n for (const density of densities) {\n test(`${id} ${theme} ${density}`, async ({ page }) => {\n await page.goto(`/iframe.html?id=${id}&viewMode=story`);\n await page.evaluate(([t, d]) => {\n document.documentElement.dataset.theme = t;\n document.documentElement.dataset.density = d;\n }, [theme, density]);\n await expect(page).toHaveScreenshot(`${id}-${theme}-${density}.png`);\n });\n }\n }\n}كل story تُعرض في كل تركيبة من الـ theme والكثافة، ومعهما العلامة في مجموعة Northwind الحقيقية، وهكذا كان سيُلتقط انحدار ارتفاع السطر. والدالة toHaveScreenshot في Playwright تعطّل حركات CSS افتراضيًا وتعيد المحاولة حتى تتطابق لقطتان متتاليتان، فتزيل أشيع مصادر الضجيج.
والاختبارات البصرية تحرس طبقات الـ tokens أيضًا. تضيف Northwind قاعدة Stylelint في مهمّة الـ CI نفسها ترفض أي إشارة إلى primitive token، مثل var(--nw-blue-600)، داخل أنماط المكوّنات. ثم تؤكّد المجموعة البصرية أن الـ CSS الملتزم بالقاعدة ما زال يعرض ما اعتمده المصمّمون.
الاختبار لا يحمي المستخدمين إلا إذا كان النشر عاجزًا عن تخطّيه. لخط الإصدار في Northwind نصفان.
\nعلى كل pull request: التثبيت بـ npm ci، وتشغيل فحوص الـ tokens (التسمية، والمراجع، والتباين)، وفحص الأنواع، والـ lint، واختبارات الوحدات والـ stories، وفحوص إمكانية الوصول، والاختبارات البصرية، واشتراط ملف changeset حين تتغيّر حزمة. ولا يمكن دمج الـ pull request حتى تنجح كل هذه، ويوافق عضو من النواة على الفروقات البصرية.
على main: يجمع إجراء Changesets الـ changesets المعلّقة في pull request باسم «Version Packages» يرفع الإصدارات ويحدّث CHANGELOG.md. ودمج هذا الـ pull request يشغّل خطوة النشر:
name: Release\non:\n push:\n branches: [main]\njobs:\n release:\n runs-on: ubuntu-latest\n permissions:\n contents: write # push version commits and tags\n pull-requests: write # open the Version Packages pull request\n id-token: write # npm trusted publishing\n steps:\n - uses: actions/checkout@v7\n - uses: actions/setup-node@v7\n with:\n node-version: 24\n - run: npm ci\n - run: npm run build\n - run: npm test\n - uses: changesets/action@v2\n with:\n publish-script: npm run releaseالنشر يحدث أخيرًا، ومن main وحده، وبعد البناء والاختبارات فقط. وبعد خروج الحزم، ينشر سير العمل نفسه موقع التوثيق ونسخة Storybook، ويستورد فريق النواة الـ tokens التي صدرت في الإصدار إلى مكتبة Figma.
في التمرين تراجع سير عمل للإصدار يمكنه نشر كود معطوب. وبهذا يكتمل قسم التسليم؛ وبعده توسّع النظام ليخدم أربعين فريقًا.
\n","toc":[{"id":"sec-1","text":"الـ stories حالات اختبار","level":2},{"id":"sec-2","text":"اختبار الانحدار البصري","level":2},{"id":"sec-3","text":"خط الإصدار","level":2}],"takeaways":["الـ story حالة موثّقة للمكوّن، والـ story نفسها يمكن أن تقود اختبارات التفاعل وفحوص إمكانية الوصول واللقطات البصرية.","اختبارات الانحدار البصري (visual regression) تقارن لقطات الشاشة بصور مرجعية معتمدة (baselines)، فتظهر التغييرات غير المقصودة كفروقات يقبلها إنسان أو يرفضها.","اعرض كل مكوّن في كل تركيبة من الـ themes، لأن الزوايا التي لا تنظر إليها أبدًا هي التي تنكسر.","خط الإصدار يفحص، ثم يرقّم، ثم ينشر؛ ولا يُنشر شيء من branch لم يجتز كل الفحوص."],"further":[{"title":"Visual testing (Storybook docs, official repository)","url":"https://github.com/storybookjs/storybook/blob/next/docs/writing-tests/visual-testing.mdx"},{"title":"Visual comparisons (Playwright)","url":"https://playwright.dev/docs/test-snapshots"},{"title":"Changesets GitHub Action (official repository)","url":"https://github.com/changesets/action"}],"quiz":[{"q":"فشل اختبار بصري في 46 story بعد pull request لم يغيّر إلا token الحشوة الخاص بـ Dialog. ماذا يجب أن يفعل المراجع أولًا؟
","options":[{"text":"قبول الصور المرجعية الجديدة الـ 46 كلها، لأن تغيير الـ token مقصود.","why":"بعض الـ 46 قد تكون آثارًا جانبية غير مقصودة؛ والقبول الأعمى يحوّل الاختبار إلى ختم آلي."},{"text":"النظر في المكوّنات التي تغيّرت؛ فإن تغيّر شيء غير Dialog وما يحتويه، فالـ token مستخدم على نطاق أوسع مما كان متوقّعًا.","why":"صحيح. الفروقات دليل على المدى الحقيقي للتغيير، وهو بالضبط ما يحتاجه المراجع ليحكم."},{"text":"إعادة تشغيل الاختبارات، لأن الاختبارات البصرية غير مستقرّة عادةً.","why":"إعادة تشغيل فرق ثابت في 46 story تعطي النتيجة نفسها؛ وعدم الاستقرار يظهر كإخفاقات عشوائية متغيّرة."},{"text":"حذف الـ stories الفاشلة حتى ينجح البناء.","why":"حذف التغطية يخفي المشكلة، ويخفي معها الانحدار الحقيقي التالي."}],"answer":1},{"q":"تنجح الاختبارات البصرية على حاسوب المطوّر وتفشل في الـ CI بفروقات صغيرة في حواف النص. ما السبب الأرجح والإصلاح؟
","options":[{"text":"جهاز الـ CI أبطأ؛ زِد مهلة الانتظار.","why":"السرعة لا تغيّر تنعيم الحواف (anti-aliasing)؛ والمهلة تؤثّر في الانتظار لا في البكسلات."},{"text":"اللقطات تُلتقط قبل تحميل الخطوط؛ أضف انتظارًا ثابتًا لمدة ثانية إلى كل اختبار.","why":"الانتظار الثابت يبطئ المجموعة ويُبقيها غير مستقرّة؛ وهذا العرَض يشير إلى اختلافات في الرسم بين الأجهزة."},{"text":"أنظمة التشغيل المختلفة ترسم الخطوط بشكل مختلف؛ ولّد الصور المرجعية وقارنها في بيئة واحدة ثابتة، مثل حاوية الـ CI.","why":"صحيح. الصور المرجعية لا تكون قابلة للمقارنة إلا حين يولّدها المتصفّح ونظام التشغيل والخطوط نفسها."}],"answer":2},{"q":"أين يجب أن يعمل npm publish في سير عمل الإصدار لنظام التصميم؟
سير العمل هذا في GitHub Actions يُفترض أن ينشر @northwind/ui على npm بعد دمج التغييرات واختبارها. لكنه بصيغته الحالية قد يضع كودًا غير مختبَر وغير مُراجَع أمام الفرق الأربعين كلها. اختر السطر أو الأسطر المسبّبة لذلك.
سطران خاطئان.
\npull_request، فينشر كل pull request مفتوح، قبل المراجعة أو الدمج. يجب أن يعمل سير عمل الإصدار على push إلى main.npm run build وnpm test والاختبارات البصرية. فإن فشل أيٌّ منها تكون الحزمة قد وصلت إلى npm بالفعل. يجب أن يكون النشر آخر خطوة.الإصلاح: on: push: branches: [main]، ونقل خطوة النشر (أو إجراء Changesets الذي يشغّلها) إلى ما بعد البناء والاختبارات والاختبارات البصرية.