# الاختبار

يشغّل الأمر `elide test` ملفات `node:test` المكتوبة بلغتي JavaScript و TypeScript واختبارات JUnit.

```bash
elide test
```

يجعل الاختبار الفاشل رمز الخروج غير صفري.

<img src="/assets/demos/test.gif" alt="اكتشاف اختبارات JavaScript وتشغيلها باستخدام Elide" width="1591" height="764" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## JavaScript و TypeScript

تستخدم الاختبارات واجهة `node:test` ولا تحتاج إلى ملف بيان. يُعدّ الملف اختبارًا إذا طابق `*.test.*` أو `*.spec.*`
أو `*_test.*` أو `*_spec.*`، أو كان داخل `test` أو `tests` أو `__tests__`. الامتدادات: `.js` و `.mjs` و `.cjs`
و `.ts` و `.mts` و `.cts`.

يتخطى الاكتشاف المجلدات المخفية ومجلدات التبعيات ومخرجات البناء. ويتوقف عند أي مشروع متداخل (مجلد يحتوي على
`elide.pkl` أو `package.json` أو `pom.xml` أو `requirements.txt`)، لذا لا يجد جذر مساحة العمل اختبارات الأعضاء.
حدّد مسارًا لتشغيلها.

```js
import test from "node:test";
import assert from "node:assert";

test("adds two values", () => {
  assert.equal(1 + 1, 2);
});
```

## اختبارات JVM

تعمل اختبارات JVM على JUnit Platform وتحتاج إلى `elide.pkl`. المجلد `src/test` هو مجموعة مصادر الاختبار الافتراضية؛
وتحلّ محله أي مجموعة مصادر مصرّح بها من النوع `test` ([مجموعات المصادر](/docs/toolchain/source-sets)).

- تحصل مجموعات الاختبار على `testPackages` إضافة إلى تبعيات المجموعة الرئيسية.
- تُضاف مكتبات JUnit المضمّنة افتراضيًا. يزيل `jvm.features.testing = false` واجهات JUnit البرمجية اللازمة للتصريف
  وبيئة التشغيل المضمّنة معًا؛ وعندها يحتاج تشغيل اختبارات JVM إلى مشغّل JUnit لسطر الأوامر
  (`junit-platform-console`) في `testPackages`، وإلا فشل بخطأ. ولا تتأثر عمليات التشغيل التي لا تتضمن اختبارات JVM.
- تعمل `processors` على مصادر الاختبار.
- تحصل JVM الاختبار على `jvm.flags` و `jvm.defs` (بصيغة `-D`).
- توضع تبعيات `modules` لمجموعتي الاختبار والرئيسية على `--module-path` مع `--add-modules=ALL-MODULE-PATH`.
- تتقدم إعدادات التوازي في ملف `junit-platform.properties` الموجود على مسار أصناف الاختبار على `--concurrency`.

## اختيار الاختبارات

تحصر المسارات أو المجلدات أو أنماط glob اختبارات JavaScript و ⁦TypeScript:⁩

```bash
elide test src/api
elide test src/api/client.test.ts
```

مع وسائط المسارات تُتخطى اختبارات JVM ويُطبع `Path filtering unsupported for JVM tests: <paths>`. ويطابق `-t` أسماء
الاختبارات في كلا المشغّلين:

```bash
elide test -t 'parses .+ headers'
```

تقبل اختبارات JVM محدِّدات JUnit وتعبيرات الوسوم:

```bash
elide test --select=class:com.example.ParserTest
elide test --select=method:com.example.ParserTest#parsesHeaders
elide test --select=package:com.example.parser   # the package and its subpackages
elide test com.example.parser                     # a dotted bare token is a package selector
elide test --include-tag=fast --include-tag=unit  # fast OR unit
elide test --exclude-tag=slow --exclude-tag=flaky # neither slow nor flaky
elide build test --select=class:com.example.ParserTest
```

<img src="/assets/demos/jvm-test.gif" alt="elide test — محدِّدات JUnit في مشروع Kotlin" width="1591" height="873" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

التعبير `--include-tag='slow & !flaky'` تعبير واحد. وتُطبَّق مرشحات الوسوم بعد المحدِّدات.

## المخرجات والتقارير

يذهب التقدم إلى stderr، والحصيلة النهائية إلى ⁦stdout:⁩

```bash
elide test > summary.txt
elide test 2> progress.txt
```

تُكتب التقارير في `.dev/reports/tests/<language>/<source-set>/`. ويفعّلها `testing.reports` في `elide.pkl` دون
خيار:

```pkl
import "elide:Testing.pkl" as Testing

testing {
  reports { Testing.xmlReport() }
}
```

### مخرجات TAP

يجعل `--reporter=tap` مخرجات stdout تدفق TAP 13 خالصًا:

```text
TAP version 13
# start 1: suite A > t1
# out 1: printed from inside a test
ok 1 - suite A > t1
# start 2: broken
not ok 2 - broken
  ---
  message: "expected 1 to equal 2"
  severity: "ERR_ASSERTION"
  ...
1..2
```

- يفتح `# start <id>` اختبارًا؛ وأسطر مخرجاته بالصيغة `# out <id>: <text>`. أما `# out: <text>` فلا ينتمي إلى أي
  اختبار.
- تُرقَّم نقاط الاختبار `1..N` بترتيب انتهائها. اربط النقاط بالاختبارات عبر سطر `# start`، لا عبر الرقم.
- لا تظهر كتلة YAML إلا مع حالات الفشل التي تحمل تفاصيل؛ و `severity` هو رمز خطأ المشغّل إن وُجد.
- لا يُغلَّف ⁦stderr:⁩ الأمر `elide test --reporter=tap 2>&1` لا ينتج TAP صالحًا.
- في ⁦JVM:⁩ لا تُنسب المخرجات إلى اختبارها إلا ما دام اختبار واحد بالضبط قيد التشغيل. ومع `--concurrency` أكبر من 1
  أو ملف `junit-platform.properties` في المشروع، تبقى غير منسوبة.
- في ⁦JavaScript:⁩ يُغلَّف `console.log` داخل اختبار، أو في المستوى الأعلى بعد استيراد `node:test`. أما المخرجات قبل
  ذلك الاستيراد فتُطبع كما هي. وتنتمي مخرجات الخطّاف إلى الاختبار الذي يحيط به؛ ويُغلَّف `t.diagnostic` بصيغة
  `# out`.

اضبط `ELIDE_TEST_METADATA=1` مع `--reporter=tap` لتضمين تعليقات JSON مُرقَّمة الإصدار `# elide-test:` قبل
النتائج. تحمل هذه التعليقات رقم النتيجة، ومعرّف البدء، والمحرّك، والملف المصدري، والمجموعة، والحالة، والمدة المقيسة
بالمللي ثانية. يربط معرّف البدء الاختبارات المتزامنة بمخرجاتها الملتقطة، حتى عند تكرار الأسماء واختلاف ترتيب
الانتهاء. يتجاهل مستهلكو TAP العاديون هذه التعليقات؛ وتبقى المخرجات الافتراضية والتقارير الخاصة بكل مجموعة كما هي.

## التغطية

```bash
elide test --coverage
elide run --coverage
```

في مساحة عمل مشروع في Tern، اختر **Test**، ثم **Run with coverage**. يظهر تبويب **Coverage** بعد قياس التشغيل:
فيعرض الملفات المقيسة مع أسطرها المغطّاة والمغطّاة جزئيًا وغير المغطّاة، ويعرض المصدر الحالي للملف المحدد مع تلوين كل
سطر مقيس بحسب تغطيته. أما الأسطر التي لا تقيسها بيئة التشغيل أبدًا (الأقواس الختامية، والأسطر الفارغة، والتعليقات)
فتأخذ لونًا أفتح إذا نُفِّذت الكتلة التي تنتمي إليها: أي إذا كان أقرب سطر مقيس فوقها في تلك الكتلة مغطّى ولم يفصل
بينهما سطر غير مغطّى. ولا تُحسب هذه الأسطر في النسب المئوية. ينتقل **Next uncovered** و **Previous uncovered**
(`n` و `p`) بين الفجوات، ويفتح **Open line N in Elide source** الملف عند السطر المحدد؛ احفظ تغييراتك واختر
**Run again** لقياس الشيفرة المحدّثة. ويُبقي سجل التشغيلات القياسات السابقة متاحة، وتُعرض بيانات الفروع غير المتاحة
منفصلة عن التغطية الصفرية.

لا تستجيب أزرار الفتح في عرض Tests (**Open in Elide source**، و **Open** على بطاقة الاختبار) إلا للنقر. فبرنامج
الطرفية الذي يرسم عرضًا في Tern لا يستطيع أن يطلب من Tern فتح رابط عبر مفتاح، لذا لا يفتح Enter التحديد؛ انقر الزر، أو
انقر مع ⌘ على اسم ملف مرتبط. راجع [التغطية في Tern](/docs/tern-coverage).

يمكن لتكاملات الاختبار ضبط `ELIDE_COVERAGE_REPORT` على مسار ملف خاص بالتشغيل عند طلب التغطية. يكتب Elide بشكل
ذرّي مُخرَج JSON مُرقَّم الإصدار يضم الملفات المصدرية المقيسة، وتغطية الأسطر القابلة للتنفيذ، وعدّادات الفروع حيثما
توفرت. هذا المُخرَج مستقل عن ملفات تقارير LCOV أو JaCoCo المضبوطة. وينبغي للتكامل تخصيص وجهة جديدة لكل تشغيل.

تصف بصمات ملفات JavaScript المصدرية النص الذي قيّمته بيئة التشغيل، حتى لو تغيّر الملف قبل كتابة التقرير. فالتغطية
قياس لتلك النسخة من المصدر. وغياب البصمة أو قياس الفروع يعني أن البيانات غير متاحة؛ ولا يعني أن الملف الحالي مطابق
ولا أن أي فرع لم يُنفَّذ. وتسجّل تغطية الأسطر ما إذا كان السطر قد غُطّي، لا عدد مرات تنفيذه.

تذهب تغطية JVM إلى `.dev/reports/coverage/jvm/<task>/` بصيغة HTML أو XML أو CSV؛ أما تغطية JavaScript و TypeScript
فبصيغة LCOV، في `.dev/reports/coverage/js/lcov.info` للاختبارات و `.dev/reports/coverage/js/run/lcov.info` لعمليات
التشغيل. وتطبع وحدة التحكم ملخصًا واحدًا مجمّعًا. تجمع الكتلة `coverage` في المستوى الأعلى التغطية دون الخيار:

```pkl
import "elide:Coverage.pkl" as Coverage

coverage {
  enabled = true
  scope = "tests"
  jvm {
    excludes { "org.example.generated.*" }
    reports {
      Coverage.xmlReport()
      Coverage.htmlReport()
    }
    minimum {
      line = 0.85
      branch = 0.70
    }
  }
  js {
    paths { "src" }
    minimum { line = 0.80 }
  }
}
```

| الخاصية | المعنى | الافتراضي |
| --- | --- | --- |
| `enabled` | الجمع دون `--coverage`. | `false` |
| `scope` | `"tests"` أو `"runs"` أو `"all"`؛ ويغطي `--coverage` مهمته دائمًا. | `"tests"` |
| `jvm.reports` | `Coverage.htmlReport()`، `xmlReport()`، `csvReport()`. | لا شيء |
| `jvm.excludes` | أنماط أصناف (`*`، `?`) لا تُرصد، مثل الشيفرة المولَّدة. | لا شيء |
| `jvm.minimum.line`، `jvm.minimum.branch` | الحد الأدنى لنسبة التغطية، من `0.0` إلى `1.0`. | لا شيء |
| `js.paths` | جذور المصادر المشمولة في التقرير؛ الفراغ يعني المشروع كله. | لا شيء |
| `js.minimum.line` | الحد الأدنى لنسبة الأسطر المغطّاة، من `0.0` إلى `1.0`. | لا شيء |

عندما يجمع التشغيل التغطية، يخرج `elide test` برمز غير صفري إذا لم يتحقق أحد قيم `minimum`، مع ذكر الخاصية والنسبة
المطلوبة والنسبة المقيسة. والحد الأدنى الذي لا يجد ما يقيسه، كغياب اختبارات JVM أو الأصناف المحلَّلة، يفشل أيضًا.
تُكتب التقارير في الحالتين. وتحتسب نسب JVM كل صنف يحلّله تشغيل الاختبارات.

مع التغطية، يبدأ `elide run` عملية JVM منفصلة.

## الخيارات

| الخيار | التأثير |
| --- | --- |
| `-t REGEX` | مطابقة اسم الاختبار أو مجموعة الاختبارات المحيطة به. |
| `--where CEL` | ⁦JavaScript:⁩ تشغيل الاختبارات التي يكون فيها تعبير [CEL](/docs/api-cel) على `name` و `parents` و `file` صحيحًا. |
| `--select=SELECTOR` | ⁦JVM:⁩ محدِّد `class:` أو `method:` أو `package:`؛ قابل للتكرار. |
| `--include-tag=EXPR` | ⁦JVM:⁩ تشغيل الاختبارات التي تطابق وسومها؛ ويُجمع التكرار بـ OR. |
| `--exclude-tag=EXPR` | ⁦JVM:⁩ تخطي الاختبارات التي تطابق وسومها؛ ويُجمع التكرار بـ AND. |
| `--bail[=N]` | التوقف بعد `N` حالة فشل (الافتراضي 1). |
| `--test-timeout=MS` | المهلة الافتراضية لكل اختبار. |
| `--timeout DURATION` | المهلة الزمنية للاستدعاء كله (عام). |
| `--only` | تشغيل الاختبارات المعلَّمة بـ `.only` فقط. |
| `--concurrency=N` | تشغيل الملفات أو أصناف JVM بالتوازي. الافتراضي `1`؛ و `0` غير صالح. |
| `--coverage` | جمع التغطية؛ راجع [التغطية](#coverage). |
| `--reporter=junit` | كتابة تقارير JUnit XML. |
| `--reporter=tap` | كتابة TAP 13 إلى stdout (وتحت `--reporter-outfile`). |
| `--reporter-outfile=DIR` | مجلد التقارير. |
| `--debugger[=MODE\|ADDRESS]` | إرفاق مصحِّح أخطاء؛ راجع ما يلي. |
| `--debugger-host=HOST`، `--debugger-port=PORT` | عنوان مصحِّح أخطاء JavaScript (المنفذ 4711 لـ DAP، و 1337 لـ CDP). |

| صيغة `--debugger` | ما يصحّحه |
| --- | --- |
| دون قيمة | اختبارات JVM عبر JDWP على `127.0.0.1:5005`، واختبارات JavaScript. |
| `=5005`، `=host:5005` | اختبارات JVM فقط (JDWP). |
| `=dap`، `=cdp` | اختبارات JavaScript فقط. |

الصياغة: [تصحيح الأخطاء](/docs/debugging). يفشل الخيار المجهول أو القيمة الناقصة قبل تشغيل أي شيء
([مهام البناء](/docs/toolchain/build-tasks#options)).

## القيود

- لا يوجد اكتشاف لاختبارات Python؛ شغّل unittest أو pytest بدلًا من ذلك ([اختبارات Python](/docs/python-testing)).
- تحتاج اختبارات JVM إلى ملف بيان.
- غير مُنفَّذ: لقطات `node:test`، و `mock.module`، ووضع المراقبة، و `run()` البرمجي، و `node:test/reporters`.

الواجهة المدعومة: [واجهة اختبارات Node](/docs/api-node-test).

## أمثلة

- [اختبارات TypeScript](/docs/code-samples#typescript-tests)
- [اختبارات Kotlin](/docs/code-samples#kotlin-tests)
- [تصفية الاختبارات باستخدام CEL](/docs/code-samples#filter-tests-with-cel)
- [JUnit XML في CI](/docs/code-samples#junit-xml-in-ci)

ابدأ من قالب:

```bash
elide init --template java        # Java app with a JUnit test
elide init --template ktjvm       # Kotlin app with a test
```

## حاويات اختبار مشتركة

صرّح بالخدمات المؤقتة في `testing.testcontainers`. يشغّلها Elide قبل مشغّلات اختبارات JavaScript و TypeScript
و JUnit المحددة في المشروع، وينتظر جاهزيتها، ويوقفها عند انتهاء تشغيل الاختبارات. ويتلقى كل مشغّل في ذلك المشروع قيم
الاتصال نفسها. يعمل هذا باستقلال عن Micronaut أو أي إطار عمل تطبيقات آخر.

```pkl
amends "elide:project.pkl"
name = "database-tests"

testing {
  testcontainers {
    containers {
      ["postgres"] {
        image = "postgres:17-alpine"
        environment {
          ["POSTGRES_USER"] = "test"
          ["POSTGRES_PASSWORD"] = "test"
          ["POSTGRES_DB"] = "app"
        }
        ports { 5432 }
        wait { timeoutSeconds = 90 }
      }
    }
    environment {
      ["DATABASE_HOST"] = "${postgres.host}"
      ["DATABASE_PORT"] = "${postgres.port.5432}"
      ["JDBC_URL"] = "jdbc:postgresql://${postgres.host}:${postgres.port.5432}/app"
    }
  }
}
```

اقرأ هذه القيم عبر `process.env` في ⁦JavaScript/TypeScript⁩ أو `System.getenv` في ⁦Java/Kotlin.⁩ تتجاوز الروابط متغيرات
البيئة الموروثة لمشغّلات الاختبارات فقط. يمكن أن يتضمن الربط `${name.host}` أو `${name.port.CONTAINER_PORT}` أو
`${name.id}`؛ وتفشل المراجع غير المعروفة قبل البدء. المنافذ هي منافذ TCP داخل الحاوية. يخصّص Testcontainers منافذ
متاحة على المضيف، لذا لا تحتاج التشغيلات المتزامنة إلى حجز منافذ ثابتة. ولأعضاء مساحة العمل مجموعات حاويات مستقلة.

تدعم كل حاوية `image`، وقائمة وسائط `command` اختيارية، و `environment` و `ports` و `wait`:

| استراتيجية الانتظار | الإعدادات المطلوبة | السلوك |
| --- | --- | --- |
| `"port"` (افتراضي) | `ports` غير فارغة | ينتظر حتى تستمع المنافذ المكشوفة |
| `"http"` | `wait.port` يسمّي منفذًا مكشوفًا | طلب GET إلى `wait.path` (افتراضيًا `/`)، متوقعًا `wait.status` (افتراضيًا `200`) |
| `"log"` | `wait.pattern` | ينتظر تطابقًا واحدًا مع تعبير Java النمطي في سجلات الحاوية |

القيمة الافتراضية لـ `wait.timeoutSeconds` هي 60. والقيمة الافتراضية لـ `startupTimeoutSeconds` العام هي 300، وتشمل
تنزيل الصور وكل فحوص الجاهزية. وتُفشل أخطاء البدء تشغيل الاختبارات. تُمرَّر وسائط أمر الحاوية مباشرة؛ استخدم أمر
shell صريحًا داخل الحاوية عند الحاجة.

يلزم خادم خلفي متوافق مع Docker و JDK 17 أو أحدث يدعم تشغيل الملفات المصدرية. يستخدم Elide سلسلة أدوات JVM المضبوطة،
ويحلّ Testcontainers بمعزل عن تبعيات التطبيق عند أول استخدام. تُورَث إعدادات الاتصال بـ Docker مثل `DOCKER_HOST`.
ويستخدم CLI الأصلي الخاص بـ Elide هذا المسار أيضًا؛ إذ يعمل Testcontainers في JVM مساعدة. ولا يضيف شيئًا إلى ملف JAR
الخاص بتطبيقك أو إلى Native Image.

لا يشغّل `elide install` ولا التصريف الحاويات. ويحافظ `elide test` على السلوك المعتاد لاختيار الاختبارات والتقارير
والتغطية؛ ويدعم `elide build test` الحاويات لمهام اختبار JVM أيضًا. يجري التنظيف بعد النجاح أو الفشل أو الإلغاء.
وتراقب العملية المساعدة اتصالها بالعملية الأم، ويتولى resource reaper الخاص بـ Testcontainers موارد Docker اليتيمة.
أبقِ resource reaper مفعّلًا في CI.

توجد ملفات الجلسة ضمن `.dev/testcontainers/`. تُحذف الطلبات التي تحتوي قيم بيئة الحاويات بعد أن تقرأها العملية
المساعدة، ومرة أخرى أثناء التنظيف. وتبقى سجلات العملية المساعدة هناك للتشخيص؛ وقد تحتوي مخرجات من مكتبة الحاويات. وفي
أنظمة POSIX تكون مجلدات الجلسات خاصة.

يحتوي مثال المشروع `testcontainers` على اختبارات JavaScript و JUnit تعمل على حاوية HTTP مشتركة واحدة. شغّله باستخدام
`elide test`.
