يدعم الآن مُشغل اختبارات Bun تقرير تغطية الكود المدمج. هذا يسهل رؤية مقدار تغطية قاعدة الكود بالاختبارات، والعثور على المناطق التي لا يتم اختبارها جيدًا حاليًا.

تمكين التغطية

يدعم bun:test رؤية أي أسطر من الكود مغطاة بالاختبارات. لاستخدام هذه الميزة، مرر --coverage إلى سطر الأوامر. سيطبع تقرير تغطية إلى وحدة التحكم:

bun test --coverage

-------------|---------|---------|-------------------
File         | % Funcs | % Lines | Uncovered Line #s
-------------|---------|---------|-------------------
All files    |   38.89 |   42.11 |
 index-0.ts  |   33.33 |   36.84 | 10-15,19-24
 index-1.ts  |   33.33 |   36.84 | 10-15,19-24
 index-10.ts |   33.33 |   36.84 | 10-15,19-24
 index-2.ts  |   33.33 |   36.84 | 10-15,19-24
 index-3.ts  |   33.33 |   36.84 | 10-15,19-24
 index-4.ts  |   33.33 |   36.84 | 10-15,19-24
 index-5.ts  |   33.33 |   36.84 | 10-15,19-24
 index-6.ts  |   33.33 |   36.84 | 10-15,19-24
 index-7.ts  |   33.33 |   36.84 | 10-15,19-24
 index-8.ts  |   33.33 |   36.84 | 10-15,19-24
 index-9.ts  |   33.33 |   36.84 | 10-15,19-24
 index.ts    |  100.00 |  100.00 |
-------------|---------|---------|-------------------

التمكين افتراضيًا

لتمكين تقرير التغطية افتراضيًا دائمًا، أضف السطر التالي إلى bunfig.toml:

bunfig.toml

[test]
# تمكين التغطية دائمًا
coverage = true

افتراضيًا، ستتضمن تقارير التغطية ملفات الاختبار وتستبعد خرائط المصدر. هذا عادةً ما تريد، لكن يمكن تكوينه بخلاف ذلك في bunfig.toml.

bunfig.toml

[test]
coverageSkipTestFiles = true  # الافتراضي false

عتبات التغطية

من الممكن تحديد عتبة تغطية في bunfig.toml. إذا لم تلبِ مجموعة الاختبار هذه العتبة أو تتجاوزها، سيخرج bun test برمز خروج غير صفري للإشارة إلى الفشل.

عتبة بسيطة

bunfig.toml

[test]
# للمطالبة بتغطية بنسبة 90% على مستوى السطر والدالة
coverageThreshold = 0.9

عتبات مفصلة

bunfig.toml

[test]
# لتحديد عتبات مختلفة للأسطر والدوال
coverageThreshold = { lines = 0.9, functions = 0.9, statements = 0.9 }

تحديد أي من هذه العتبات يُمكّن fail_on_low_coverage، مما يتسبب في فشل تشغيل الاختبار إذا كانت التغطية أقل من العتبة.

مُبلغي التغطية

افتراضيًا، ستُطبع تقارير التغطية إلى وحدة التحكم.

لتقارير تغطية الكود المستمرة في بيئات CI وللأدوات الأخرى، يمكنك تمرير خيار سطر الأوامر --coverage-reporter=lcov أو خيار coverageReporter في bunfig.toml.

bunfig.toml

[test]
coverageReporter = ["text", "lcov"]  # الافتراضي ["text"]
coverageDir = "path/to/somewhere"    # الافتراضي "coverage"

المُبلغون المتاحون

المُبلغ	الوصف
text	يطبع ملخصًا نصيًا للتغطية إلى وحدة التحكم
lcov	يحفظ التغطية بتنسيق lcov

مُبلغ تغطية LCOV

لإنشاء تقرير lcov، يمكنك استخدام مُبلغ lcov. سينشئ هذا ملف lcov.info في دليل التغطية.

bunfig.toml

[test]
coverageReporter = "lcov"

# أو عبر سطر الأوامر
bun test --coverage --coverage-reporter=lcov

تنسيق LCOV مدعوم على نطاق واسع من قبل أدوات وخدمات مختلفة:

• محرري الكود: يمكن لإضافات VS Code عرض التغطية مضمنة
• خدمات CI/CD: GitHub Actions و GitLab CI و CircleCI
• خدمات التغطية: Codecov و Coveralls
• بيئات التطوير المتكاملة: WebStorm و IntelliJ IDEA

استخدام LCOV مع GitHub Actions

.github/workflows/test.yml

name: اختبار مع التغطية
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test --coverage --coverage-reporter=lcov
      - name: رفع التغطية إلى Codecov
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info

استبعاد الملفات من التغطية

تخطي ملفات الاختبار

افتراضيًا، يتم تضمين ملفات الاختبار نفسها في تقارير التغطية. يمكنك استبعادها باستخدام:

bunfig.toml

[test]
coverageSkipTestFiles = true  # الافتراضي false

سيستبعد هذا الملفات التي تطابق أنماط الاختبار (مثل *.test.ts و *.spec.js) من تقرير التغطية.

تجاهل المسارات والأنماط المحددة

يمكنك استبعاد ملفات أو أنماط ملفات محددة من تقارير التغطية باستخدام coveragePathIgnorePatterns:

bunfig.toml

[test]
# نمط واحد
coveragePathIgnorePatterns = "**/*.spec.ts"

# أنماط متعددة
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

يقبل هذا الخيار أنماط glob ويعمل بشكل مشابه لأنماط تجاهل collectCoverageFrom في Jest. سيتم استبعاد الملفات التي تطابق أي من هذه الأنماط من حساب التغطية والإبلاغ في مخرجات text و LCOV.

حالات الاستخدام الشائعة

bunfig.toml

[test]
coveragePathIgnorePatterns = [
  # استبعاد ملفات الأدوات المساعدة
  "src/utils/**",

  # استبعاد ملفات التكوين
  "*.config.js",
  "webpack.config.ts",
  "vite.config.ts",

  # استبعاد أنماط الاختبار المحددة
  "**/*.spec.ts",
  "**/*.e2e.ts",

  # استبعاد مصنفات البناء
  "dist/**",
  "build/**",

  # استبعاد الملفات المُنشأة
  "src/generated/**",
  "**/*.generated.ts",

  # استبعاد كود البائع/الطرف الثالث
  "vendor/**",
  "third-party/**"
]

خرائط المصدر

داخليًا، تقوم Bun بترجمة جميع الملفات افتراضيًا، لذا تنشئ Bun تلقائيًا خريطة مصدر داخلية تقوم بتعيين أسطر كود المصدر الأصلي إلى التمثيل الداخلي لـ Bun. إذا كان هناك أي سبب تريد تعطيل هذا، اضبط test.coverageIgnoreSourcemaps على true؛ هذا نادرًا ما يكون مرغوبًا خارج حالات الاستخدام المتقدمة.

bunfig.toml

[test]
coverageIgnoreSourcemaps = true  # الافتراضي false

الإعدادات الافتراضية للتغطية

افتراضيًا، تقارير التغطية:

• تستبعد أدلة node_modules
• تستبعد الملفات المحملة عبر محملات غير JS/TS (مثل .css و .txt) ما لم يتم تحديد محمل JS مخصص
• تتضمن ملفات الاختبار نفسها (يمكن تعطيلها باستخدام coverageSkipTestFiles = true)
• يمكن استبعاد ملفات إضافية باستخدام coveragePathIgnorePatterns

تكوين متقدم

دليل تغطية مخصص

bunfig.toml

[test]
coverageDir = "coverage-reports"  # الافتراضي "coverage"

مُبلغون متعددون

bunfig.toml

[test]
coverageReporter = ["text", "lcov"]

التغطية مع أنماط اختبار محددة

# تشغيل التغطية على ملفات اختبار محددة فقط
bun test --coverage src/components/*.test.ts

# تشغيل التغطية مع نمط الاسم
bun test --coverage --test-name-pattern="API"

تكامل CI/CD

مثال GitHub Actions

.github/workflows/coverage.yml

name: تقرير التغطية
on: [push, pull_request]

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: تثبيت التبعيات
        run: bun install

      - name: تشغيل الاختبارات مع التغطية
        run: bun test --coverage --coverage-reporter=lcov

      - name: الرفع إلى Codecov
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info
          fail_ci_if_error: true

مثال GitLab CI

.gitlab-ci.yml

test:coverage:
  stage: test
  script:
    - bun install
    - bun test --coverage --coverage-reporter=lcov
  coverage: '/Lines\s*:\s*(\d+.\d+)%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/lcov.info

تفسير تقارير التغطية

شرح إخراج النص

-------------|---------|---------|-------------------
File         | % Funcs | % Lines | Uncovered Line #s
-------------|---------|---------|-------------------
All files    |   85.71 |   90.48 |
 src/        |   85.71 |   90.48 |
  utils.ts   |  100.00 |  100.00 |
  api.ts     |   75.00 |   85.71 | 15-18,25
  main.ts    |   80.00 |   88.89 | 42,50-52
-------------|---------|---------|-------------------

• % Funcs: نسبة الدوال التي تم استدعاؤها أثناء الاختبارات
• % Lines: نسبة الأسطر القابلة للتنفيذ التي تم تشغيلها أثناء الاختبارات
• Uncovered Line #s: أرقام الأسطر المحددة التي لم يتم تنفيذها

ما يجب استهدافه

• تغطية إجمالية 80%+: تعتبر جيدة بشكل عام
• مسارات حرجة 90%+: يجب اختبار منطق الأعمال المهم جيدًا
• دوال مساعدة 100%: الدوال النقية والأدوات المساعدة سهلة الاختبار بالكامل
• تغطية أقل لمكونات واجهة المستخدم: مقبول غالبًا لأنها قد تتطلب اختبارات تكامل

أفضل الممارسات

التركيز على الجودة وليس الكمية فقط

test.ts

// جيد: اختبار الوظيفة الفعلية
test("calculateTax يجب أن يتعامل مع معدلات ضريبية مختلفة", () => {
  expect(calculateTax(100, 0.08)).toBe(8);
  expect(calculateTax(100, 0.1)).toBe(10);
  expect(calculateTax(0, 0.08)).toBe(0);
});

// تجنب: مجرد ضرب الأسطر للتغطية
test("calculateTax موجود", () => {
  calculateTax(100, 0.08); // لا توجد تأكيدات!
});

اختبار الحالات الحدية

test.ts

test("التحقق من صحة إدخال المستخدم", () => {
  // اختبار الحالة العادية
  expect(validateEmail("user@example.com")).toBe(true);

  // اختبار الحالات الحدية التي تحسن التغطية بشكل مفيد
  expect(validateEmail("")).toBe(false);
  expect(validateEmail("invalid")).toBe(false);
  expect(validateEmail(null)).toBe(false);
});

استخدام التغطية للعثور على الاختبارات المفقودة

# تشغيل التغطية لتحديد الكود غير المختبر
bun test --coverage

# انظر إلى الملفات المحددة التي تحتاج إلى اهتمام
bun test --coverage src/critical-module.ts

الجمع مع مقاييس الجودة الأخرى

التغطية مجرد مقياس واحد. ضع في اعتبارك أيضًا:

• جودة مراجعة الكود
• تغطية اختبار التكامل
• اختبارات معالجة الأخطاء
• اختبارات الأداء
• أمان النوع

استكشاف الأخطاء وإصلاحها

التغطية لا تظهر لبعض الملفات

إذا لم تظهر الملفات في تقارير التغطية، فقد لا يتم استيرادها بواسطة اختباراتك. تتتبع التغطية فقط الملفات التي يتم تحميلها فعليًا.

test.ts

// تأكد من استيراد الوحدات التي تريد اختبارها
import { myFunction } from "../src/my-module";

test("دالتي تعمل", () => {
  expect(myFunction()).toBeDefined();
});

تقارير تغطية خاطئة

إذا رأيت تقارير تغطية لا تتطابق مع توقعاتك:

1. تحقق من عمل خرائط المصدر بشكل صحيح
2. تحقق من أنماط الملفات في coveragePathIgnorePatterns
3. تأكد من أن ملفات الاختبار تستورد الكود المراد اختباره فعليًا

مشاكل الأداء مع قواعد الكود الكبيرة

بالنسبة للمشاريع الكبيرة، يمكن أن يبطئ جمع التغطية الاختبارات:

bunfig.toml

[test]
# استبعاد الأدلة الكبيرة التي لا تحتاج إلى تغطية لها
coveragePathIgnorePatterns = [
  "node_modules/**",
  "vendor/**",
  "generated/**"
]

فكر في تشغيل التغطية فقط في CI أو فروع محددة بدلاً من كل تشغيل اختبار أثناء التطوير.