import Test from "/snippets/cli/test.mdx";

تأتي Bun مع أداة اختبار سريعة ومدمجة ومتوافقة مع Jest. يتم تنفيذ الاختبارات مع وقت تشغيل Bun، وتدعم الميزات التالية.

• TypeScript و JSX
• خطافات دورة الحياة
• اختبار اللقطات
• اختبار واجهة المستخدم و DOM
• وضع المراقبة مع --watch
• تحميل النص البرمجي المسبق مع --preload

NOTE

تهدف Bun إلى التوافق مع Jest، لكن لم يتم تنفيذ كل شيء. لتتبع التوافق، راجع [مشكلة التتبع هذه](https://github.com/oven-sh/bun/issues/1825).

تشغيل الاختبارات

bun test

تُكتب الاختبارات بلغة JavaScript أو TypeScript مع واجهة برمجة تطبيقات شبيهة بـ Jest. راجع كتابة الاختبارات للحصول على الوثائق الكاملة.

import { expect, test } from "bun:test";

test("2 + 2", () => {
  expect(2 + 2).toBe(4);
});

تبحث أداة التشغيل بشكل متكرر في دليل العمل عن الملفات التي تطابق الأنماط التالية:

• *.test.{js|jsx|ts|tsx}
• *_test.{js|jsx|ts|tsx}
• *.spec.{js|jsx|ts|tsx}
• *_spec.{js|jsx|ts|tsx}

يمكنك تصفية مجموعة ملفات الاختبار المراد تشغيلها عن طريق تمرير وسيطات موضعية إضافية إلى bun test. سيتم تشغيل أي ملف اختبار يتطابق مساره مع أحد المرشحات. عادةً، ستكون هذه المرشحات أسماء ملفات أو أدلة؛ أنماط glob غير مدعومة بعد.

bun test <filter> <filter> ...

لتصفية حسب اسم الاختبار، استخدم العلم -t/--test-name-pattern.

# تشغيل جميع الاختبارات أو مجموعات الاختبارات التي تحتوي على "addition" في الاسم
bun test --test-name-pattern addition

لتشغيل ملف معين في أداة الاختبار، تأكد من أن المسار يبدأ بـ ./ أو / لتمييزه عن اسم المرشح.

bun test ./test/specific-file.test.ts

تشغل أداة الاختبار جميع الاختبارات في عملية واحدة. تقوم بتحميل جميع نصوص --preload البرمجية (راجع دورة الحياة للحصول على التفاصيل)، ثم تشغل جميع الاختبارات. إذا فشل اختبار، ستخرج أداة الاختبار برمز خروج غير صفري.

تكامل CI/CD

يدعم bun test مجموعة متنوعة من تكاملات CI/CD.

GitHub Actions

يكتشف bun test تلقائيًا ما إذا كان يعمل داخل GitHub Actions وسيصدر تعليقات توضيحية لـ GitHub Actions إلى وحدة التحكم مباشرة.

لا يلزم أي تكوين، بخلاف تثبيت bun في سير العمل وتشغيل bun test.

كيفية تثبيت bun في سير عمل GitHub Actions

لاستخدام bun test في سير عمل GitHub Actions، أضف الخطوة التالية:

.github/workflows/test.yml

jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies # (بافتراض أن مشروعك لديه تبعيات)
        run: bun install # يمكنك استخدام npm/yarn/pnpm بدلاً من ذلك إذا كنت تفضل
      - name: Run tests
        run: bun test

من هناك، ستحصل على تعليقات توضيحية لـ GitHub Actions.

تقارير JUnit XML (GitLab، إلخ)

لاستخدام bun test مع مُبلغ JUnit XML، يمكنك استخدام --reporter=junit مع --reporter-outfile.

bun test --reporter=junit --reporter-outfile=./bun.xml

سيستمر هذا في الإخراج إلى stdout/stderr كالمعتاد، وأيضًا كتابة تقرير JUnit XML إلى المسار المحدد في نهاية تشغيل الاختبار.

JUnit XML هو تنسيق شائع للإبلاغ عن نتائج الاختبار في خطوط أنابيب CI/CD.

المهلات

استخدم العلم --timeout لتحديد مهلة لكل اختبار بالمللي ثانية. إذا انتهت مهلة الاختبار، سيتم اعتباره فاشلًا. القيمة الافتراضية هي 5000.

# القيمة الافتراضية هي 5000
bun test --timeout 20

تنفيذ الاختبار المتزامن

بشكل افتراضي، تشغل Bun جميع الاختبارات بشكل متسلسل داخل كل ملف اختبار. يمكنك تمكين التنفيذ المتزامن لتشغيل الاختبارات غير المتزامنة بشكل متوازٍ، مما يسرع بشكل كبير مجموعات الاختبار التي تحتوي على اختبارات مستقلة.

العلم --concurrent

استخدم العلم --concurrent لتشغيل جميع الاختبارات بشكل متزامن داخل ملفاتها الخاصة:

bun test --concurrent

عند تمكين هذا العلم، سيتم تشغيل جميع الاختبارات بشكل متوازٍ ما لم يتم تحديدها صراحةً بـ test.serial.

العلم --max-concurrency

تحكم في الحد الأقصى لعدد الاختبارات التي تعمل في وقت واحد مع العلم --max-concurrency:

# الحد إلى 4 اختبارات متزامنة
bun test --concurrent --max-concurrency 4

# الافتراضي: 20
bun test --concurrent

هذا يساعد على منع استنفاد الموارد عند تشغيل العديد من الاختبارات المتزامنة. القيمة الافتراضية هي 20.

test.concurrent

حدد اختبارات فردية لتشغيلها بشكل متزامن، حتى عندما لا يتم استخدام العلم --concurrent:

math.test.ts

import { test, expect } from "bun:test";

// هذه الاختبارات تعمل بشكل متوازٍ مع بعضها البعض
test.concurrent("concurrent test 1", async () => {
  await fetch("/api/endpoint1");
  expect(true).toBe(true);
});

test.concurrent("concurrent test 2", async () => {
  await fetch("/api/endpoint2");
  expect(true).toBe(true);
});

// هذا الاختبار يعمل بشكل متسلسل
test("sequential test", () => {
  expect(1 + 1).toBe(2);
});

test.serial

فرض تشغيل الاختبارات بشكل متسلسل، حتى عند تمكين العلم --concurrent:

math.test.ts

import { test, expect } from "bun:test";

let sharedState = 0;

// يجب تشغيل هذه الاختبارات بالترتيب
test.serial("first serial test", () => {
  sharedState = 1;
  expect(sharedState).toBe(1);
});

test.serial("second serial test", () => {
  // يعتمد على الاختبار السابق
  expect(sharedState).toBe(1);
  sharedState = 2;
});

// يمكن تشغيل هذا الاختبار بشكل متزامن إذا تم تمكين --concurrent
test("independent test", () => {
  expect(true).toBe(true);
});

// سلسلة مؤهلات الاختبار
test.failing.each([1, 2, 3])("chained qualifiers %d", input => {
  expect(input).toBe(0); // من المتوقع أن يفشل هذا الاختبار لكل إدخال
});

إعادة تشغيل الاختبارات

استخدم العلم --rerun-each لتشغيل كل اختبار عدة مرات. هذا مفيد للكشف عن الاختبارات المتقلبة أو الفشل غير الحتمي.

bun test --rerun-each 100

عشوائية ترتيب تنفيذ الاختبار

استخدم العلم --randomize لتشغيل الاختبارات بترتيب عشوائي. هذا يساعد على اكتشاف الاختبارات التي تعتمد على الحالة المشتركة أو ترتيب التنفيذ.

bun test --randomize

عند استخدام --randomize، سيتم عرض البذرة المستخدمة للعشوائية في ملخص الاختبار:

bun test --randomize

# ... إخراج الاختبار ...
 --seed=12345
 2 pass
 8 fail
Ran 10 tests across 2 files. [50.00ms]

ترتيب عشوائي قابل للتكرار مع --seed

استخدم العلم --seed لتحديد بذرة للعشوائية. هذا يسمح لك بإعادة إنتاج نفس ترتيب الاختبار عند تصحيح حالات الفشل المعتمدة على الترتيب.

# إعادة إنتاج تشغيل عشوائي سابق
bun test --seed 123456

يشير العلم --seed إلى --randomize، لذا لا تحتاج إلى تحديد كليهما. استخدام نفس قيمة البذرة سيُنتج دائمًا نفس ترتيب تنفيذ الاختبار، مما يسهل تصحيح حالات الفشل المتقطعة الناجمة عن الترابط بين الاختبارات.

الإنهاء المبكر مع --bail

استخدم العلم --bail لإنهاء تشغيل الاختبار مبكرًا بعد عدد محدد مسبقًا من حالات فشل الاختبار. بشكل افتراضي، ستشغل Bun جميع الاختبارات وتبلغ عن جميع حالات الفشل، لكن في بعض الأحيان في بيئات CI يُفضل الإنهاء مبكرًا لتقليل استخدام وحدة المعالجة المركزية.

# الإنهاء بعد فشل واحد
bun test --bail

# الإنهاء بعد 10 فشل
bun test --bail=10

وضع المراقبة

على غرار bun run، يمكنك تمرير العلم --watch إلى bun test لمراقبة التغييرات وإعادة تشغيل الاختبارات.

bun test --watch

خطافات دورة الحياة

تدعم Bun خطافات دورة الحياة التالية:

Hook	الوصف
beforeAll	يعمل مرة واحدة قبل جميع الاختبارات.
beforeEach	يعمل قبل كل اختبار.
afterEach	يعمل بعد كل اختبار.
afterAll	يعمل مرة واحدة بعد جميع الاختبارات.

يمكن تعريف هذه الخطافات داخل ملفات الاختبار، أو في ملف منفصل يتم تحميله مسبقًا مع العلم --preload.

bun test --preload ./setup.ts

راجع اختبار > دورة الحياة للحصول على الوثائق الكاملة.

المحاكاة

أنشئ دوال محاكاة مع دالة mock.

math.test.ts

import { test, expect, mock } from "bun:test";
const random = mock(() => Math.random());

test("random", () => {
  const val = random();
  expect(val).toBeGreaterThan(0);
  expect(random).toHaveBeenCalled();
  expect(random).toHaveBeenCalledTimes(1);
});

بدلاً من ذلك، يمكنك استخدام jest.fn()، فهي تتصرف بشكل متطابق.

math.test.ts

import { test, expect, mock } from "bun:test"; 
import { test, expect, jest } from "bun:test"; 

const random = mock(() => Math.random()); 
const random = jest.fn(() => Math.random()); 

راجع اختبار > المحاكاة للحصول على الوثائق الكاملة.

اختبار اللقطات

اللقطات مدعومة من bun test.

math.test.ts

// مثال على استخدام toMatchSnapshot
import { test, expect } from "bun:test";

test("snapshot", () => {
  expect({ a: 1 }).toMatchSnapshot();
});

لتحديث اللقطات، استخدم العلم --update-snapshots.

bun test --update-snapshots

راجع اختبار > اللقطات للحصول على الوثائق الكاملة.

اختبار واجهة المستخدم و DOM

Bun متوافق مع مكتبات اختبار واجهة المستخدم الشائعة:

• HappyDOM
• DOM Testing Library
• React Testing Library

راجع اختبار > اختبار DOM للحصول على الوثائق الكاملة.

الأداء

أداة اختبار Bun سريعة.

تكامل وكيل AI

عند استخدام أداة اختبار Bun مع مساعدي الترميز AI، يمكنك تمكين إخراج أكثر هدوءًا لتحسين إمكانية القراءة وتقليل ضوضاء السياق. هذه الميزة تقلل من إسهاب إخراج الاختبار مع الحفاظ على معلومات الفشل الأساسية.

متغيرات البيئة

اضبط أيًا من متغيرات البيئة التالية لتمكين الإخراج الصديق لـ AI:

• CLAUDECODE=1 - لـ Claude Code
• REPL_ID=1 - لـ Replit
• AGENT=1 - علم وكيل AI عام

السلوك

عند اكتشاف بيئة وكيل AI:

• يتم عرض حالات فشل الاختبار فقط بالتفصيل
• يتم إخفاء مؤشرات الاختبار الناجحة والمُتروكة و todo
• تظل إحصائيات الملخص سليمة

# مثال: تمكين الإخراج الهادئ لـ Claude Code
CLAUDECODE=1 bun test

# لا يزال يعرض حالات الفشل والملخص، لكن يخفي إخراج الاختبار الناجح المفصل

هذه الميزة مفيدة بشكل خاص في سير عمل التطوير بمساعدة AI حيث يحسن تقليل إسهاب الإخراج كفاءة السياق مع الحفاظ على الرؤية في حالات فشل الاختبار.

---