رصد الأداء باستخدام Lighthouse CI

كيفية إضافة Lighthouse إلى نظام دمج مستمر، مثل GitHub Actions

Katie Hempenius
Katie Hempenius
X

Lighthouse CI هي مجموعة من الأدوات لاستخدام Lighthouse أثناء عملية الدمج المستمر. يمكن دمج Lighthouse CI في سير عمل المطوّرين بعدة طرق مختلفة. يتناول هذا الدليل المواضيع التالية:

  • استخدام واجهة سطر الأوامر (CLI) في Lighthouse CI
  • ضبط موفّر خدمة CI لتشغيل Lighthouse CI
  • إعداد إجراء GitHub والتحقّق من الحالة لـ Lighthouse CI سيؤدي ذلك إلى عرض نتائج Lighthouse تلقائيًا في طلبات السحب على GitHub.
  • إنشاء لوحة بيانات للأداء ومخزن بيانات لتقارير Lighthouse

نظرة عامة

‫Lighthouse CI هي مجموعة من الأدوات المجانية التي تسهّل استخدام Lighthouse لمراقبة الأداء. يقدّم تقرير Lighthouse الفردي نبذة عن أداء صفحة الويب في وقت تشغيله، بينما يعرض Lighthouse CI كيفية تغيُّر هذه النتائج بمرور الوقت. ويمكن استخدام ذلك لتحديد تأثير تغييرات معيّنة في الرموز البرمجية أو لضمان استيفاء حدود الأداء أثناء عمليات الدمج المتواصل. على الرغم من أنّ مراقبة الأداء هي حالة الاستخدام الأكثر شيوعًا لـ Lighthouse CI، يمكن استخدامها لمراقبة جوانب أخرى من تقرير Lighthouse، مثل تحسين محركات البحث أو تسهيل الاستخدام.

يتم توفير الوظيفة الأساسية لـ Lighthouse CI من خلال واجهة سطر أوامر Lighthouse CI. ملاحظة: هذه الأداة منفصلة عن Lighthouse CLI. توفّر واجهة سطر الأوامر (CLI) في Lighthouse CI مجموعة من الأوامر لاستخدام Lighthouse CI. على سبيل المثال، ينفّذ الأمر autorun عمليات تشغيل متعددة لأداة Lighthouse، ويحدّد تقرير Lighthouse المتوسط، ويحمّل التقرير للتخزين. يمكن تخصيص هذا السلوك بشكل كبير من خلال تمرير علامات إضافية أو تخصيص ملف إعداد Lighthouse CI، lighthouserc.js.

على الرغم من أنّ الوظيفة الأساسية لـ Lighthouse CI يتم تضمينها بشكل أساسي في واجهة سطر الأوامر في Lighthouse CI، يتم استخدام Lighthouse CI عادةً من خلال إحدى الطرق التالية:

  • تشغيل Lighthouse CI كجزء من التكامل المستمر
  • استخدام إجراء GitHub في Lighthouse CI الذي يتم تشغيله والتعليق على كل طلب سحب
  • تتبُّع الأداء بمرور الوقت من خلال لوحة البيانات التي يوفّرها خادم Lighthouse

تعتمد كل هذه الأساليب على واجهة سطر الأوامر في Lighthouse CI.

تشمل بدائل Lighthouse CI خدمات مراقبة الأداء التابعة لجهات خارجية أو كتابة نص برمجي خاص بك لجمع بيانات الأداء أثناء عملية CI. ننصحك باستخدام خدمة تابعة لجهة خارجية إذا كنت تفضّل السماح لشخص آخر بإدارة خادم مراقبة الأداء وأجهزة الاختبار، أو إذا كنت تريد إمكانات الإشعارات (مثل التكامل مع البريد الإلكتروني أو Slack) بدون الحاجة إلى إنشاء هذه الميزات بنفسك.

استخدام Lighthouse CI محليًا

يوضّح هذا القسم كيفية تشغيل Lighthouse CI CLI وتثبيته على الجهاز وكيفية ضبط lighthouserc.js. إنّ تشغيل واجهة سطر الأوامر (CLI) في Lighthouse CI محليًا هو أسهل طريقة للتأكّد من ضبط lighthouserc.js بشكل صحيح.

  1. ثبِّت واجهة سطر الأوامر (CLI) في Lighthouse CI.

    npm install -g @lhci/cli

    يتم ضبط Lighthouse CI من خلال وضع ملف lighthouserc.js في جذر مستودع مشروعك. هذا الملف إلزامي وسيحتوي على معلومات الإعدادات ذات الصلة بـ Lighthouse CI. على الرغم من أنّه يمكن ضبط Lighthouse CI ليتم استخدامه بدون مستودع git، تفترض التعليمات الواردة في هذه المقالة أنّه تم ضبط مستودع مشروعك لاستخدام git.

  2. في جذر المستودع، أنشئ ملف إعداد lighthouserc.js.

    touch lighthouserc.js

  3. أضِف الرمز التالي إلى lighthouserc.js. هذا الرمز هو إعداد Lighthouse CI فارغ. ستضيف إلى هذا التكوين في الخطوات اللاحقة.

    module.exports = {
  ci: {
    collect: {
      /* Add configuration here */
    },
    upload: {
      /* Add configuration here */
    },
  },
};

  4. في كل مرة يتم فيها تشغيل Lighthouse CI، يتم تشغيل خادم لعرض موقعك الإلكتروني. هذا الخادم هو ما يتيح لـ Lighthouse تحميل موقعك الإلكتروني حتى في حال عدم تشغيل أي خوادم أخرى. عند انتهاء تشغيل Lighthouse CI، سيتم إيقاف الخادم تلقائيًا. لضمان عمل عرض الإعلانات بشكل صحيح، عليك ضبط إما السمة staticDistDir أو startServerCommand.

    إذا كان موقعك الإلكتروني ثابتًا، أضِف السمة staticDistDir إلى العنصر ci.collect للإشارة إلى مكان ملفاتك الثابتة. ستستخدم Lighthouse CI خادمها الخاص لعرض هذه الملفات أثناء اختبار موقعك الإلكتروني. إذا لم يكن موقعك الإلكتروني ثابتًا، أضِف السمة startServerCommand إلى العنصر ci.collect للإشارة إلى الأمر الذي يشغّل الخادم. ستبدأ Lighthouse CI عملية خادم جديدة أثناء الاختبار ثم ستوقفها بعد ذلك.

    // Static site example
collect: {
  staticDistDir: './public',
}

    // Dynamic site example
collect: {
  startServerCommand: 'npm run start',
}

  5. أضِف السمة url إلى العنصر ci.collect للإشارة إلى عناوين URL التي يجب أن تشغّل Lighthouse CI أداة Lighthouse عليها. يجب تقديم قيمة السمة url كمصفوفة من عناوين URL، ويمكن أن تحتوي هذه المصفوفة على عنوان URL واحد أو أكثر. سيشغّل Lighthouse CI تلقائيًا Lighthouse ثلاث مرات لكل عنوان URL.

    collect: {
  // ...
  url: ['http://localhost:8080']
}

  6. أضِف السمة target إلى الكائن ci.upload واضبط القيمة على 'temporary-public-storage'. سيتم تحميل تقارير Lighthouse التي تم جمعها من خلال Lighthouse CI إلى مساحة تخزين عامة مؤقتة. سيظل التقرير هناك لمدة سبعة أيام ثم يتم حذفه تلقائيًا. يستخدم دليل الإعداد هذا خيار التحميل "مساحة تخزين عامة مؤقتة" لأنّه سريع الإعداد. للحصول على معلومات حول الطرق الأخرى لتخزين تقارير Lighthouse، يُرجى الرجوع إلى المستندات.

    upload: {
  target: 'temporary-public-storage',
}

    سيكون موقع تخزين التقرير مشابهًا لما يلي:

    https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1580152437799-46441.report.html

    (لن يعمل عنوان URL هذا لأنّه سبق أن تم حذف البلاغ).

  7. شغِّل واجهة سطر الأوامر (CLI) في Lighthouse CI من الوحدة الطرفية باستخدام الأمر autorun. سيؤدي ذلك إلى تشغيل Lighthouse ثلاث مرات وتحميل تقرير Lighthouse المتوسط.

    lhci autorun

    إذا ضبطت Lighthouse CI بشكل صحيح، من المفترض أن يؤدي تشغيل هذا الأمر إلى عرض نتيجة مشابهة لما يلي:

    ✅  .lighthouseci/ directory writable
✅  Configuration file found
✅  Chrome installation found
⚠️   GitHub token not set
Healthcheck passed!

Started a web server on port 65324...
Running Lighthouse 3 time(s) on http://localhost:65324/index.html
Run #1...done.
Run #2...done.
Run #3...done.
Done running Lighthouse!

Uploading median LHR of http://localhost:65324/index.html...success!
Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591720514021-82403.report.html
No GitHub token set, skipping GitHub status check.

Done running autorun.

    يمكنك تجاهل رسالة GitHub token not set في مخرجات وحدة التحكّم. لا يلزم استخدام رمز GitHub المميّز إلا إذا كنت تريد استخدام Lighthouse CI مع إجراء GitHub. يتم شرح كيفية إعداد GitHub Action لاحقًا في هذه المقالة.

    سيؤدي النقر على الرابط في الناتج الذي يبدأ بـ https://storage.googleapis.com... إلى نقلك إلى تقرير Lighthouse المقابل لمتوسط تشغيل Lighthouse.

    يمكن إلغاء الإعدادات التلقائية التي يستخدمها autorun من خلال سطر الأوامر أو lighthouserc.js. على سبيل المثال، يشير الإعداد lighthouserc.js أدناه إلى أنّه يجب جمع خمس عمليات تشغيل لأداة Lighthouse في كل مرة يتم فيها تنفيذ autorun.

  8. عدِّل lighthouserc.js لاستخدام السمة numberOfRuns:

    module.exports = {
    // ...
    collect: {
      numberOfRuns: 5
    },
  // ...
  },
};

  9. أعِد تنفيذ الأمر autorun:

    lhci autorun

    من المفترض أن يعرض ناتج الوحدة الطرفية أنّ Lighthouse قد تم تشغيله خمس مرات بدلاً من ثلاث مرات كخيار تلقائي:

    ✅  .lighthouseci/ directory writable
✅  Configuration file found
✅  Chrome installation found
⚠️   GitHub token not set
Healthcheck passed!

Automatically determined ./dist as `staticDistDir`.
Set it explicitly in lighthouserc.json if incorrect.

Started a web server on port 64444...
Running Lighthouse 5 time(s) on http://localhost:64444/index.html
Run #1...done.
Run #2...done.
Run #3...done.
Run #4...done.
Run #5...done.
Done running Lighthouse!

Uploading median LHR of http://localhost:64444/index.html...success!
Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591716944028-6048.report.html
No GitHub token set, skipping GitHub status check.

Done running autorun.

    للتعرّف على خيارات الضبط الأخرى، يُرجى الرجوع إلى مستندات ضبط Lighthouse CI.

إعداد عملية CI لتشغيل Lighthouse CI

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

يُعدّ استخدام Lighthouse CI لجمع قياسات الأداء بداية جيدة لمراقبة الأداء. ومع ذلك، قد يرغب المستخدمون المتقدّمون في اتخاذ خطوة أخرى واستخدام Lighthouse CI لإيقاف عمليات الإنشاء إذا لم تستوفِ معايير محدّدة مسبقًا، مثل اجتياز عمليات تدقيق معيّنة في Lighthouse أو استيفاء جميع الميزانيات القائمة على الأداء. يتم ضبط هذا السلوك من خلال السمة assert في ملف lighthouserc.js.

تتيح Lighthouse CI ثلاثة مستويات من التأكيدات:

  • ‫off: تجاهُل التأكيدات
  • ‫warn: طباعة حالات تعذُّر الإرسال إلى stderr
  • error: طباعة حالات الإخفاق في stderr والخروج من Lighthouse CI برمز خروج غير صفري

في ما يلي مثال على إعدادات lighthouserc.js التي تتضمّن تأكيدات. ويحدّد تأكيدات لنتائج فئات الأداء وتسهيل الاستخدام في Lighthouse. لتجربة ذلك، أضِف التأكيدات الموضّحة أدناه إلى ملف lighthouserc.js، ثم أعِد تشغيل Lighthouse CI.

module.exports = {
  ci: {
    collect: {
      // ...
    },
    assert: {
      assertions: {
        'categories:performance': ['warn', {minScore: 1}],
        'categories:accessibility': ['error', {minScore: 1}]
      }
    },
    upload: {
      // ...
    },
  },
};

تبدو مخرجات وحدة التحكّم التي تنشئها على النحو التالي:

لقطة شاشة لرسالة تحذير تم إنشاؤها بواسطة Lighthouse CI

لمزيد من المعلومات حول تأكيدات Lighthouse CI، يُرجى الرجوع إلى المستندات.

إعداد إجراء GitHub لتشغيل Lighthouse CI

يمكن استخدام GitHub Action لتشغيل Lighthouse CI. سيؤدي ذلك إلى إنشاء تقرير Lighthouse جديد في كل مرة يتم فيها دفع تغيير في الرمز إلى أي فرع من فروع مستودع GitHub. يمكنك استخدام هذه الميزة مع التحقّق من الحالة لعرض هذه النتائج في كل طلب سحب.

لقطة شاشة لعملية التحقّق من حالة GitHub

  1. في جذر المستودع، أنشئ دليلاً باسم .github/workflows. سيتم حفظ مهام سير العمل الخاصة بمشروعك في هذا الدليل. سير العمل هو عملية يتم تنفيذها في وقت محدّد مسبقًا (على سبيل المثال، عند إرسال الرمز البرمجي) وتتألف من إجراء واحد أو أكثر.

    mkdir .github
mkdir .github/workflows

  2. في .github/workflows، أنشئ ملفًا باسم lighthouse-ci.yaml. سيحتوي هذا الملف على إعدادات سير عمل جديد.

    touch lighthouse-ci.yaml

  3. أضِف النص التالي إلى lighthouse-ci.yaml.

    name: Build project and run Lighthouse CI
on: [push]
jobs:
  lhci:
    name: Lighthouse CI
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: Use Node.js 10.x
        uses: actions/setup-node@v1
        with:
          node-version: 10.x
      - name: npm install
        run: |
          npm install
      - name: run Lighthouse CI
        run: |
          npm install -g @lhci/cli@0.3.x
          lhci autorun --upload.target=temporary-public-storage || echo "LHCI failed!"

    يؤدي هذا الإعداد إلى إنشاء سير عمل يتألف من مهمة واحدة سيتم تشغيلها عندما يتم دفع رمز جديد إلى المستودع. تتضمّن هذه المهمة أربع خطوات:

    • تحقَّق من المستودع الذي سيتم تشغيل Lighthouse CI عليه
    • تثبيت Node وضبطه
    • تثبيت حِزم npm المطلوبة
    • شغِّل Lighthouse CI وحمِّل النتائج إلى مساحة تخزين عامة مؤقتة.

  4. احفظ هذه التغييرات وأرسِلها إلى GitHub. إذا اتّبعت الخطوات أعلاه بشكل صحيح، سيؤدي إرسال الرمز إلى GitHub إلى تشغيل سير العمل الذي أضفته للتو.

  5. للتأكّد من أنّ Lighthouse CI قد تم تشغيله ولعرض التقرير الذي تم إنشاؤه، انتقِل إلى علامة التبويب الإجراءات في مشروعك. من المفترض أن يظهر لك سير العمل إنشاء المشروع وتشغيل Lighthouse CI مدرجًا ضمن أحدث عملية إرسال.

    لقطة شاشة لعلامة التبويب "الإعدادات" في GitHub

    يمكنك الانتقال إلى تقرير Lighthouse المقابل لعملية تنفيذ معيّنة من علامة التبويب الإجراءات. انقر على عملية الإرسال، ثم انقر على خطوة سير عمل Lighthouse CI، ثم وسِّع نتائج خطوة تشغيل Lighthouse CI.

    لقطة شاشة لعلامة التبويب "الإعدادات" في GitHub

    لقد أعددت للتو إجراء GitHub لتشغيل Lighthouse CI. سيكون هذا مفيدًا للغاية عند استخدامه مع التحقّق من الحالة في GitHub.

إعداد عملية تحقّق من الحالة في GitHub

التحقق من الحالة، إذا تم تكوينه، هو رسالة تظهر في كل طلب سحب وعادة ما تتضمن معلومات مثل نتائج الاختبار أو نجاح البناء.

لقطة شاشة لعلامة التبويب "الإعدادات" في GitHub

توضّح الخطوات التالية كيفية إعداد عملية التحقّق من الحالة في Lighthouse CI.

  1. انتقِل إلى صفحة تطبيق Lighthouse CI GitHub وانقر على ضبط.

  2. (اختياري) إذا كنت جزءًا من مؤسسات متعددة على GitHub، اختَر المؤسسة التي تملك المستودع الذي تريد استخدام Lighthouse CI فيه.

  3. انقر على كل المستودعات إذا أردت تفعيل Lighthouse CI في كل المستودعات أو انقر على اختيار مستودعات معيّنة فقط إذا أردت استخدامه في مستودعات معيّنة فقط، ثم اختَر المستودعات. بعد ذلك، انقر على تثبيت وتفويض.

  4. انسخ الرمز المميّز المعروض. ستستخدمه في الخطوة التالية.

  5. لإضافة الرمز المميّز، انتقِل إلى صفحة الإعدادات في مستودع GitHub، وانقر على الرموز السرية، ثم انقر على إضافة رمز سري جديد.

    لقطة شاشة لعلامة التبويب "الإعدادات" في GitHub

  6. اضبط حقل الاسم على LHCI_GITHUB_APP_TOKEN واضبط حقل القيمة على الرمز المميّز الذي نسخته في الخطوة الأخيرة، ثم انقر على الزر إضافة رمز سرّي.

  7. انتقِل إلى ملف lighthouse-ci.yaml وأضِف مفتاح الأمان الجديد للبيئة إلى الأمر "run Lighthouse CI".

-           name: run Lighthouse CI
            run: |
              npm install -g @lhci/cli@0.3.x
              lhci autorun --upload.target=temporary-public-storage || echo "LHCI failed!"
+            env:
+              LHCI_GITHUB_APP_TOKEN: $
  1. أصبح التحقّق من الحالة جاهزًا للاستخدام. لاختبارها، أنشئ طلب سحب جديدًا أو أرسِل عملية دمج إلى طلب سحب حالي.

إعداد خادم Lighthouse CI

يوفّر خادم Lighthouse CI لوحة بيانات لاستكشاف تقارير Lighthouse السابقة. ويمكن أن تعمل أيضًا كمخزن بيانات خاص طويل الأجل لتقارير Lighthouse.

لقطة شاشة للوحة بيانات Lighthouse CI Server
لقطة شاشة لمقارنة تقريرَي Lighthouse في Lighthouse CI Server
  1. اختَر عمليات الإرسال التي تريد مقارنتها.
  2. مقدار التغيير في نتيجة Lighthouse بين عمليتَي الإرسال
  3. يعرض هذا القسم فقط المقاييس التي تغيّرت بين عمليتَي الحفظ.
  4. يتم تمييز حالات التراجع باللون الوردي.
  5. يتم تمييز التحسينات باللون الأزرق.

يُعدّ Lighthouse CI Server الأنسب للمستخدمين الذين يتقنون نشر وإدارة البنية الأساسية الخاصة بهم.

للحصول على معلومات حول إعداد خادم Lighthouse CI، بما في ذلك وصفات استخدام Heroku وDocker للنشر، يُرجى الرجوع إلى هذه التعليمات.

مزيد من المعلومات