تشغيل الاختبارات في خطوط CI

لماذا يهم

في فريق يعمل بـCI يشغّل خط الأنابيب معظم الاختبارات، فمسار العمل هو الذي يقرر أي أدلة ستوجد. والفحص الذي يشغّل المجموعة الخطأ، أو حزمة المتصفح التي لا تعمل إلا في Chromium، يظهر أخضر مع ذلك؛ والفحص الذي يستغرق 40 دقيقة يتوقف الناس عن انتظاره.

والمختبِر هو غالباً من يقرر ما تغطيه الحزمة، لذا يحتاج إلى تعديل مسار العمل بنفسه: إضافة متصفح، أو نقل حزمة بطيئة إلى التشغيل الليلي، أو الاحتفاظ بتقرير المهمة الفاشلة.

تشريح ملف خط الأنابيب

لـYAML ثلاث لبنات. الربط (mapping) هو key: value؛ والقائمة (list) أسطر تبدأ بـ- ، أو الصيغة المختصرة [chromium, firefox]؛ والتداخل لا يظهر إلا بالإزاحة (indentation) بالمسافات. وعلامات الجدولة (tabs) غير مسموحة في الإزاحة، ومسافة واحدة زائدة أو ناقصة قد تنقل المفتاح إلى كتلة أخرى. وما بعد # تعليق، والقيمة التي تبدأ بـ* يجب وضعها بين علامتي تنصيص، كما في تعبير cron هذا: '*/30 * * * *'.

يحدد المفتاح on المحفّزات (triggers): pull_request عند فتح طلب دمج أو إعادة فتحه أو إضافة إيداعات (commits) جديدة إليه، وpush مقصوراً على main، وschedule مع تعبير cron. وحقوله الخمسة هي الدقيقة والساعة واليوم من الشهر والشهر واليوم من الأسبوع، فالتعبير '0 1 * * *' يعني الساعة ⁦01:00⁩ كل يوم؛ وتعمل الجدولة على الفرع الافتراضي، وبتوقيت UTC ما لم تُحدَّد لها منطقة زمنية بالمفتاح timezone. وكل مهمة (job) تحت jobs تعمل على مشغّل (runner)، وهو الجهاز الذي يسمّيه runs-on؛ والمشغّل الذي تستضيفه GitHub آلة افتراضية جديدة لكل مهمة، فلا يبقى شيء بين المهام إلا ما تخزّنه مؤقتاً أو ترفعه. وخطوات المهمة steps تعمل بالترتيب في مساحة عمل واحدة: uses يشغّل إجراءً منشوراً (action)، وrun ينفّذ أمر shell، ورمز الخروج غير الصفري يُفشل المهمة.

# .github/workflows/e2e.yml
name: e2e

الجزء 1:1on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: '0 1 * * *'          # every night, 01:00 UTC

jobs:
  smoke:
    الجزء 2:2if: github.event_name != 'schedule'
    الجزء 3:3runs-on: ubuntu-latest
    timeout-minutes: 15
    الجزء 4:4steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          الجزء 5:5cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test --project=chromium الجزء 6:6--grep @smoke
      - uses: actions/upload-artifact@v7
        الجزء 7:7if: always()
        with:
          name: smoke-results
          path: results/
          retention-days: 14

  nightly:
    if: github.event_name == 'schedule'
    runs-on: ubuntu-latest
    timeout-minutes: 45
    الجزء 8:8strategy:
      fail-fast: false
      matrix:
        browser: [chromium, firefox, webkit]
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps ${{ matrix.browser }}
      - run: npx playwright test --project=${{ matrix.browser }}
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          الجزء 9:9name: nightly-${{ matrix.browser }}
          path: results/
          retention-days: 14

# .github/workflows/e2e.yml
name: e2e

on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: '0 1 * * *'          # every night, 01:00 UTC

jobs:
  smoke:
    if: github.event_name != 'schedule'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test --project=chromium --grep @smoke
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: smoke-results
          path: results/
          retention-days: 14

  nightly:
    if: github.event_name == 'schedule'
    runs-on: ubuntu-latest
    timeout-minutes: 45
    strategy:
      fail-fast: false
      matrix:
        browser: [chromium, firefox, webkit]
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps ${{ matrix.browser }}
      - run: npx playwright test --project=${{ matrix.browser }}
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: nightly-${{ matrix.browser }}
          path: results/
          retention-days: 14

جرّبها: منسّق YAML جرّبها: محوّل YAML إلى JSON جرّبها: شارح تعابير cron

التخزين المؤقت للاعتماديات ومصفوفة المتصفحات

لأن كل مهمة تبدأ نظيفة، سيحمّل npm ci كل الحزم في كل تشغيل. والذاكرة المؤقتة للاعتماديات (dependency cache) تحفظ هذه التنزيلات تحت مفتاح محسوب من ملف القفل (lock file) وتستعيدها في المرة التالية؛ وحين يتغير package-lock.json يتغير المفتاح. ويخزّن cache: npm في actions/setup-node ذاكرة تنزيلات npm لا مجلد node_modules، فيبقى npm ci يثبّت بالضبط ما يقوله ملف القفل، لكن أسرع، ويجب أن يعطي النتيجة نفسها حين لا توجد الذاكرة المؤقتة. وتنصح وثائق Playwright الخاصة بـCI بعدم التخزين المؤقت لملفات المتصفحات، لأن استعادتها تستغرق تقريباً وقت تنزيلها.

المصفوفة (matrix) تحوّل تعريف مهمة واحداً إلى مهمة لكل تركيبة من القيم. فالسطر browser: [chromium, firefox, webkit] ينشئ ثلاث مهام متوازية، تمرّر كل منها قيمتها إلى --project، ويجب أن تطابق القيمة اسم مشروع في إعدادات Playwright. وإضافة shard: [1, 2] تجعلها ست مهام، فلا تضف بُعداً إلا لخطر حقيقي، مثل اختلاف العرض بين المحرّكات. ويترك fail-fast: false كل متصفح يكمل، فيظهر هل الإخفاق خاص بمحرّك واحد أم عام.

مثال تطبيقي: طلب الدمج أم التشغيل الليلي

لدى فريق متجر إلكتروني ⁦1,240⁩ اختبار وحدة و310 اختبارات API و180 اختبار متصفح، منها 25 موسومة @smoke لتسجيل الدخول والبحث والسلة والدفع. وتستغرق حزمة المتصفح نحو 35 دقيقة لكل متصفح، وميزانية طلب الدمج 15 دقيقة. يفرز الفريق كل حزمة حسب سرعتها وثباتها والخطر الذي تغطيه ومن يتصرف حين تفشل. ومسار العمل أعلاه ينفّذ صفوف المتصفح.

• طلبات الدمج تحصل على فحوص سريعة وثابتة لأهم الرحلات؛ ينتظرها صاحب التغيير، لذا فهي بوابة (gate) تحجب الدمج حتى تنجح.
• الدفع إلى main يكرر المجموعة نفسها: طلبا دمج نجح كل منهما وحده قد ينكسران معاً.
• التشغيل الليلي يحمل الحزم البطيئة والواسعة؛ ويقرؤه مالك محدد كل صباح ويفحص الإيداعات منذ آخر ليلة خضراء.
• الاختبارات المتذبذبة المحجورة تخرج من مجموعة طلب الدمج وتعمل ليلاً فقط، فتُبلغ دون أن تعطّل أحداً. ففي المهمة الليلية تضيف خطوة الاختبار الرئيسية الخيار --grep-invert @quarantine فتتخطى الاختبارات الموسومة به، وتشغّل خطوة ثانية الاختبارات المحجورة بـ--grep @quarantine مع continue-on-error: true، فلا يُفشل فشلُها المهمة، ومع if: always()، فتعمل حتى بعد فشل الخطوة الرئيسية.

Suite                 Tests    Time*   Pull request  Push to main  Nightly 01:00 UTC
Lint + unit           1,240    3 min   gate          run           run
API tests             310      6 min   gate          run           run
E2E @smoke, Chromium  25       4 min   gate          run           -
E2E full, 3 browsers  3 x 180  35 min  -             -             run, 3 parallel jobs

gate: must pass before the merge
*  wall-clock time per job; illustrative figures

جرّبها: مولّد تعابير cron

تقارير الاختبار والمخرجات والمهام المتوازية

اضبط مشغّل الاختبار ليكتب نتائج للآلات والناس، ثم اجعل المهمة تحتفظ بها. المقتطف أدناه يكتب JUnit XML لخادم CI، وتقرير HTML للناس، والتتبعات ولقطات الشاشة للاختبارات الفاشلة. يقرأ GitLab ملف XML عبر artifacts:reports:junit، ويقرؤه Jenkins عبر الخطوة junit من إضافة JUnit؛ وفي غيرهما راجع وثائق المنصة.

المخرجات (artifacts) ملفات ترفعها المهمة لتبقى بعد زوال مشغّلها. ارفعها مع if: always(): فالخطوة التي تلي خطوة فاشلة تُتخطى افتراضياً، وأنت تحتاج إليها في التشغيلات الفاشلة تحديداً. ويشترط GitHub Actions أسماء مخرجات فريدة داخل التشغيل الواحد، ومن هنا nightly-${{ matrix.browser }}؛ ويحدد retention-days مدة بقائها. وأبقِ البيانات الشخصية والأسرار خارجها.

المهام التي ليس فيها needs تعمل بالتوازي، وكذلك مهام المصفوفة، بقدر ما تسمح المشغّلات؛ ويضع max-parallel حداً للمصفوفة. وداخل المهمة تفضّل إرشادات Playwright الخاصة بـCI عاملاً (worker) واحداً لتشغيل ثابت، والتوسع بالأجزاء (shards) بدلاً من ذلك. وادمج تقارير المهام، مثلاً بتقارير blob من Playwright والأمر npx playwright merge-reports، لترى البوابة نتيجة واحدة.

// playwright.config.ts (excerpt)
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  workers: process.env.CI ? 1 : undefined,
  outputDir: 'results/artifacts',                       // traces, screenshots
  reporter: [
    ['junit', { outputFile: 'results/junit.xml' }],                // for the CI server
    ['html', { outputFolder: 'results/html', open: 'never' }],     // for people
  ],
  use: { trace: 'retain-on-failure', screenshot: 'only-on-failure' },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

جرّبها: منسّق XML

أسئلة شائعة

المراجع

• GitHub Actions documentationGitHubكيف تُعرَّف مسارات العمل والمهام والمشغّلات والمخرجات في GitHub Actions — حيث تعمل الاختبارات الآلية عند كل دفع أو طلب دمج.
• Playwright DocumentationMicrosoft (Playwright)التوثيق الرسمي لـ Playwright، إطار الاختبار الشامل الذي يشغّل Chromium وWebKit وFirefox.
• YAML Ain't Markup Language (YAML™) version 1.2.2YAML.org · 2021نموذج بيانات YAML 1.2 وصياغته وعلاقته بـ JSON (كل مستند JSON هو YAML 1.2 صالح).
• Unit test reports — GitLab CI/CDGitLabنشر نتائج JUnit XML كمخرجات لخط الأنابيب لتظهر الاختبارات الفاشلة في طلب الدمج ويمكن مقارنتها بين التشغيلات.