מעקב אחר ביצועים באמצעות Lighthouse CI

איך מוסיפים את Lighthouse למערכת אינטגרציה רציפה (CI), כמו GitHub Actions.

קייטי המפניוס
קייטי המפניוס
X

הכלי Lighthouse CI הוא חבילת כלים לשימוש ב-Lighthouse במהלך אינטגרציה רציפה (CI). אפשר לשלב את Lighthouse CI בתהליכי העבודה של המפתחים בדרכים רבות. מדריך זה מכסה את הנושאים הבאים:

  • באמצעות Lighthouse CI CLI.
  • הגדרת ספק ה-CI להפעלת Lighthouse CI.
  • הגדרת GitHub Action ובדיקת סטטוס עבור 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 מקובצת בעיקר ב-CLI CI של Lighthouse, ב-Lighthouse משתמשים בדרך כלל באחת מהשיטות הבאות:

  • הרצת Lighthouse CI כחלק מאינטגרציה רציפה (CI)
  • שימוש ב-Lighthouse CI GitHub Action שמריץ ותגובות על כל בקשת משיכה
  • עוקבים אחרי הביצועים לאורך זמן באמצעות לוח הבקרה של Lighthouse שרת.

כל הגישות האלה מבוססות על ה-CLI של Lighthouse.

החלופות ל-Lighthouse CI כוללות שירותי צד שלישי למעקב אחרי ביצועים, או כתיבת סקריפט משלכם לאיסוף נתוני הביצועים במהלך תהליך ה-CI. כדאי להשתמש בשירות של צד שלישי אם אתם מעדיפים לאפשר למישהו אחר לנהל את השרת למעקב ביצועים ואת מכשירי הבדיקה שלכם, או אם אתם רוצים לקבל יכולות של התראות (כמו אימייל או שילוב Slack) בלי לפתח את התכונות האלה בעצמכם.

שימוש מקומי ב-Lighthouse CI

בקטע הזה נסביר איך להריץ ולהתקין את Lighthouse CI CLI באופן מקומי ואיך להגדיר את lighthouserc.js. הדרך הקלה ביותר לוודא שהשדה lighthouserc.js מוגדר כראוי היא להפעיל את ה-CLI של Lighthouse CI באופן מקומי.

  1. מתקינים את Lighthouse CI CLI.

    npm install -g @lhci/cli

    כדי להגדיר את Lighthouse CI, מוסיפים קובץ lighthouserc.js ברמה הבסיסית (root) של מאגר הפרויקט. הקובץ הזה הוא חובה, והוא יכלול פרטי תצורה שקשורים ל-Lighthouse CI. אפשר להגדיר את Lighthouse CI לשימוש ללא מאגר git, אבל ההוראות במאמר הזה מבוססות על ההנחה שמאגר הפרויקט שלכם מוגדר לשימוש ב-Git.

  2. ברמה הבסיסית (root) של המאגר, יוצרים קובץ תצורה 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. מריצים את Lighthouse CI CLI מהטרמינל באמצעות הפקודה autorun. הפעולה הזו תפעיל את Lighthouse 3 פעמים ותעלה את הדוח החציוני של 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 Action. בהמשך מאמר זה מוסבר איך להגדיר פעולה ב-GitHub.

    לחיצה על הקישור בפלט שמתחיל ב-https://storage.googleapis.com... תעביר אתכם לדוח Lighthouse שתואם להרצה החציונית של Lighthouse.

    אפשר לשנות את ברירות המחדל שמשמשות את autorun באמצעות שורת הפקודה או lighthouserc.js. לדוגמה, לפי ההגדרה של lighthouserc.js שבהמשך צריך לאסוף 5 הפעלות של 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 כדי להיכשל בגרסאות build, אם הם לא עומדים בקריטריונים שהוגדרו מראש, כמו מעבר ביקורות מסוימות של Lighthouse או עמידה בכל תקציבי הביצועים. ההתנהגות הזו מוגדרת באמצעות המאפיין assert של הקובץ lighthouserc.js.

ב-Lighthouse CI יש תמיכה בשלוש רמות של טענות נכונות:

  • off: התעלמות מטענות נכונות
  • warn: כישלונות הדפסה ל-stderr
  • error: כשלים בהדפסה של stderr ויציאה מ-Lighthouse CI באמצעות קוד יציאה שהוא לא אפס

למטה מוצגת דוגמה להגדרה lighthouserc.js שכוללת טענות נכונות (assertions). הוא מגדיר טענות נכוֹנוּת (assertions) לציונים של קטגוריות הביצועים והנגישות של Lighthouse. כדי לנסות את זה, צריך להוסיף את טענות הנכוֹנוּת (assertions) שמוצגות למטה לקובץ lighthouserc.js, ואז להריץ מחדש את Lighthouse CI.

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

פלט המסוף שנוצר נראה כך:

צילום מסך של הודעת אזהרה שנוצרה על ידי Lighthouse CI

מידע נוסף על טענות הנכוֹנוּת (assertions) של Lighthouse CI זמין במסמכי התיעוד.

הגדרת פעולה ב-GitHub כדי להפעיל את Lighthouse CI

אפשר להשתמש ב-GitHub Action כדי להריץ Lighthouse CI. הפעולה הזו תיצור דוח Lighthouse חדש בכל פעם ששינוי קוד מועבר לכל הסתעפות של מאגר ב-GitHub. אפשר להשתמש בו יחד עם בדיקת סטטוס כדי להציג את התוצאות האלה בכל בקשת משיכה.

צילום מסך של בדיקת סטטוס ב-GitHub

  1. יוצרים ברמה הבסיסית (root) של המאגר ספרייה בשם .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
    • התקנה והגדרה של הצומת
    • התקנה של חבילות NPM הנדרשות
    • צריך להריץ את Lighthouse CI ולהעלות את התוצאות לאחסון ציבורי זמני.

  4. שומרים את השינויים האלה ומעבירים אותם ל-GitHub. אם ביצעתם את הפעולות שלמעלה בצורה נכונה, דחיפת הקוד ל-GitHub תפעיל את תהליך העבודה שהוספתם.

  5. כדי לוודא ש-Lighthouse CI הופעל ולהציג את הדוח שנוצר, עוברים לכרטיסייה Actions (פעולות) בפרויקט. תהליך העבודה Build פרויקט ו-Run Lighthouse CI אמור להופיע ברשימה של ההתחייבות האחרונה.

    צילום מסך של הכרטיסייה 'הגדרות' ב-GitHub

    בכרטיסייה Actions תוכלו לעבור לדוח Lighthouse שתואם להתחייבות מסוימת. לוחצים על השמירה, לוחצים על שלב תהליך העבודה Lighthouse CI ואז מרחיבים את התוצאות של השלב הפעלת Lighthouse CI.

    צילום מסך של הכרטיסייה 'הגדרות' ב-GitHub

    סיימת להגדיר פעולת GitHub כדי להריץ את Lighthouse CI. כדאי להשתמש באפשרות הזו בשילוב עם בדיקת סטטוס של GitHub.

הגדרה של בדיקת סטטוס ב-GitHub

בדיקת סטטוס, אם היא מוגדרת, היא הודעה שמופיעה בכל PR, ובדרך כלל כוללת מידע כמו תוצאות הבדיקה או ההצלחה של build.

צילום מסך של הכרטיסייה 'הגדרות' ב-GitHub

בשלבים הבאים מוסבר איך להגדיר בדיקת סטטוס עבור Lighthouse CI.

  1. נכנסים לדף Lighthouse CI GitHub App ולוחצים על Configure.

  2. (אופציונלי) אם אתם חברים במספר ארגונים ב-GitHub, תוכלו לבחור את הארגון שהוא הבעלים של המאגר שעבורו אתם רוצים להשתמש ב-Lighthouse CI.

  3. אם רוצים להפעיל את Lighthouse CI בכל המאגרים, צריך לבחור באפשרות All repositories. אם רוצים להשתמש בהם רק במאגרים ספציפיים, צריך לבחור באפשרות Only select repositories. ואז לוחצים על Install & Authorize.

  4. מעתיקים את האסימון שמוצג. תשתמשו בה בשלב הבא.

  5. על מנת להוסיף את האסימון, נכנסים לדף Settings של מאגר GitHub, לוחצים על Secrets ואז על Add a new secret.

    צילום מסך של הכרטיסייה 'הגדרות' ב-GitHub

  6. בשדה Name בוחרים באפשרות LHCI_GITHUB_APP_TOKEN, בשדה Value מגדירים את האסימון שהעתקתם בשלב הקודם, ואז לוחצים על Addsecret.

  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. בדיקת הסטטוס מוכנה לשימוש. כדי לבדוק אותה, צריך ליצור בקשת משיכה חדשה או ללחוץ על התחייבות לבקשת משיכה קיימת.

הגדרת שרת CI של Lighthouse

שרת Lighthouse CI מספק מרכז בקרה כדי לבחון את הדיווחים ההיסטוריים של Lighthouse. הוא יכול לשמש גם כמאגר נתונים פרטי לטווח ארוך לדוחות של Lighthouse.

צילום מסך של מרכז הבקרה של שרת ה-CI של Lighthouse
צילום מסך של השוואה בין שני דוחות Lighthouse בשרת CI של Lighthouse
  1. בחירת ההתחייבויות להשוואה.
  2. מידת השינוי בציון של Lighthouse בין שתי ההגדרות.
  3. בקטע הזה מוצגים רק מדדים שהשתנו בין שתי ההתחייבויות.
  4. רגרסיות מודגשות בוורוד.
  5. השיפורים מודגשים בכחול.

שרת ה-CI של Lighthouse מתאים במיוחד למשתמשים שמרגישים בנוח לפרוס את התשתית שלהם ולנהל אותה.

למידע על הגדרת שרת Lighthouse CI, כולל מתכונים לשימוש ב-Heroco וב-Docker לפריסה, קראו את instructions האלה.

למידע נוסף