يشغّل الأمر elide test ملفات node:test المكتوبة بلغتي JavaScript و TypeScript واختبارات JUnit.
elide test
يجعل الاختبار الفاشل رمز الخروج غير صفري.
~/demo elide test --coverage
test/greet.test.ts
✓ greets by name
✓ greets the world
╭Coverage Report─────────────────────────────╮
│ TypeScript · 1 file │
│ Statements ━━━━━━━━━━━━━━━━━━━━ 6/6 100% │
│ Lines ━━━━━━━━━━━━━━━━━━━━ 1/1 100% │
│ Functions ━━━━━━━━━━━━━━━━━━━━ 4/4 100% │
╰────────────────────────────────────────────╯
2 pass
0 skip
0 fail
Ran 2 tests across one file. (0.07s)
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)، لذا لا يجد جذر مساحة العمل اختبارات الأعضاء.
حدّد مسارًا لتشغيلها.
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 (مجموعات المصادر).
- تحصل مجموعات الاختبار على
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:
elide test src/api
elide test src/api/client.test.ts
مع وسائط المسارات تُتخطى اختبارات JVM ويُطبع Path filtering unsupported for JVM tests: <paths>. ويطابق -t أسماء
الاختبارات في كلا المشغّلين:
elide test -t 'parses .+ headers'
تقبل اختبارات JVM محدِّدات JUnit وتعبيرات الوسوم:
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
~/demo elide test --select class:calc.CalculatorTest
calc.CalculatorTest
✓ divides evenly() [13ms]
✓ adds two numbers() [3ms]
✓ rejects division by zero() [19ms]
3 pass
0 skip
0 fail
Ran 3 tests across one file. (0.63s)
~/demo elide test --select 'method:calc.FormatTest#formats cents as dollars'
calc.FormatTest
✓ formats cents as dollars() [23ms]
1 pass
0 skip
0 fail
Ran one test across one file. (0.59s)
التعبير --include-tag='slow & !flaky' تعبير واحد. وتُطبَّق مرشحات الوسوم بعد المحدِّدات.
المخرجات والتقارير
يذهب التقدم إلى stderr، والحصيلة النهائية إلى stdout:
elide test > summary.txt
elide test 2> progress.txt
تُكتب التقارير في .dev/reports/tests/<language>/<source-set>/. ويفعّلها testing.reports في elide.pkl دون
خيار:
import "elide:Testing.pkl" as Testing
testing {
reports { Testing.xmlReport() }
}
مخرجات TAP
يجعل --reporter=tap مخرجات stdout تدفق TAP 13 خالصًا:
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 العاديون هذه التعليقات؛ وتبقى المخرجات الافتراضية والتقارير الخاصة بكل مجموعة كما هي.
التغطية
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.
يمكن لتكاملات الاختبار ضبط 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 في المستوى الأعلى التغطية دون الخيار:
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 على 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 |
جمع التغطية؛ راجع التغطية. |
--reporter=junit |
كتابة تقارير JUnit XML. |
--reporter=tap |
كتابة TAP 13 إلى stdout (وتحت --reporter-outfile). |
--reporter-outfile=DIR |
مجلد التقارير. |
--debugger[= |
إرفاق مصحِّح أخطاء؛ راجع ما يلي. |
--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 فقط. |
الصياغة: تصحيح الأخطاء. يفشل الخيار المجهول أو القيمة الناقصة قبل تشغيل أي شيء (مهام البناء).
القيود
- لا يوجد اكتشاف لاختبارات Python؛ شغّل unittest أو pytest بدلًا من ذلك (اختبارات Python).
- تحتاج اختبارات JVM إلى ملف بيان.
- غير مُنفَّذ: لقطات
node:test، وmock.module، ووضع المراقبة، وrun()البرمجي، وnode:test/reporters.
الواجهة المدعومة: واجهة اختبارات Node.
أمثلة
ابدأ من قالب:
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 أو أي إطار عمل تطبيقات آخر.
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.