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

איך מוסיפים את Lighthouse למערכת שילוב רציף (CI), כמו GitHub Actions.

Katie Hempenius
Katie Hempenius
X

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

  • שימוש ב-CLI של Lighthouse CI.
  • הגדרת ספק ה-CI להפעלת Lighthouse CI.
  • הגדרת פעולת GitHub ובדיקת סטטוס ל-Lighthouse CI. כך תוצאות Lighthouse יוצגו באופן אוטומטי בבקשות משיכה ב-GitHub.
  • יצירת לוח בקרה לביצועי הענן ומאגר נתונים לדוחות Lighthouse.

סקירה כללית

‫Lighthouse CI היא חבילה של כלים חינמיים שמאפשרים להשתמש ב-Lighthouse למעקב אחרי הביצועים. דוח Lighthouse יחיד מספק תמונת מצב של ביצועי דף אינטרנט בזמן ההפעלה שלו. Lighthouse CI מראה איך הממצאים האלה השתנו לאורך זמן. אפשר להשתמש בזה כדי לזהות את ההשפעה של שינויים מסוימים בקוד, או כדי לוודא שסף הביצועים נשמר במהלך תהליכי אינטגרציה רציפה. למרות שמעקב אחר ביצועים הוא תרחיש השימוש הנפוץ ביותר ב-Lighthouse CI, אפשר להשתמש בו כדי לעקוב אחר היבטים אחרים של דוח Lighthouse – לדוגמה, SEO או נגישות.

הפונקציונליות העיקרית של Lighthouse CI מסופקת על ידי ממשק שורת הפקודה של Lighthouse CI. (הערה: זהו כלי נפרד מ-Lighthouse CLI). ממשק שורת הפקודה של Lighthouse CI מספק קבוצה של פקודות לשימוש ב-Lighthouse CI. לדוגמה, הפקודה autorun מריצה את Lighthouse כמה פעמים, מזהה את דוח Lighthouse החציוני ומעלה את הדוח לאחסון. אפשר להתאים אישית את ההתנהגות הזו במידה רבה על ידי העברת דגלים נוספים או התאמה אישית של קובץ התצורה של Lighthouse CI,‏ lighthouserc.js.

למרות שהפונקציונליות העיקרית של Lighthouse CI נמצאת בעיקר ב-CLI של Lighthouse CI, בדרך כלל משתמשים ב-Lighthouse CI באחת מהדרכים הבאות:

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

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

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

שימוש ב-Lighthouse CI באופן מקומי

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

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

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

    לחיצה על הקישור בפלט שמתחיל ב-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 המועדף עליכם. בקטע Configure Your CI Provider במסמכי התיעוד של Lighthouse CI יש דוגמאות קוד שמראות איך לשלב את Lighthouse CI בקובצי התצורה של כלי CI נפוצים. באופן ספציפי, דוגמאות הקוד האלה מראות איך להריץ את Lighthouse CI כדי לאסוף מדדי ביצועים במהלך תהליך ה-CI.

שימוש ב-Lighthouse CI לאיסוף מדידות ביצועים הוא נקודת התחלה טובה למעקב אחרי ביצועים. עם זאת, משתמשים מתקדמים יכולים להשתמש ב-Lighthouse CI כדי להכשיל גרסאות build אם הן לא עומדות בקריטריונים מוגדרים מראש, כמו מעבר של ביקורות ספציפיות של Lighthouse או עמידה בכל תקציבי הביצועים. ההתנהגות הזו מוגדרת באמצעות המאפיין assert של הקובץ lighthouserc.js.

‫Lighthouse CI תומך בשלוש רמות של טענות נכונות (assertions):

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

בהמשך מוצגת דוגמה להגדרת lighthouserc.js שכוללת טענות נכונות (assertions). הוא מגדיר טענות נכוֹנוּת (assertions) לציונים של קטגוריות הביצועים והנגישות של Lighthouse. כדי לנסות את זה, מוסיפים את ההצהרות שמוצגות למטה לקובץ 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 כדי להריץ את 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 הופעל ולראות את הדוח שנוצר, עוברים לכרטיסייה Actions בפרויקט. תהליך העבודה Build project and Run Lighthouse CI אמור להופיע מתחת ל-commit האחרון.

    צילום מסך של הכרטיסייה Settings ב-GitHub

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

    צילום מסך של הכרטיסייה Settings ב-GitHub

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

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

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

צילום מסך של הכרטיסייה Settings ב-GitHub

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

  1. נכנסים לדף של אפליקציית Lighthouse CI ב-GitHub ולוחצים על Configure.

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

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

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

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

    צילום מסך של הכרטיסייה Settings ב-GitHub

  6. מגדירים את השדה Name כ-LHCI_GITHUB_APP_TOKEN ואת השדה Value כטוקן שהעתקתם בשלב הקודם, ואז לוחצים על הכפתור Add secret.

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

הגדרת שרת Lighthouse CI

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

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

‫Lighthouse CI Server מתאים במיוחד למשתמשים שיודעים לפרוס ולנהל את התשתית שלהם.

בהוראות האלה מוסבר איך להגדיר את שרת Lighthouse CI, כולל מתכונים לשימוש ב-Heroku וב-Docker לפריסה.

מידע נוסף