انتقل إلى المحتوى

الاختبار

شغّل ملفات node:test المكتوبة بلغتي JavaScript و TypeScript واختبارات JUnit باستخدام elide test: الاكتشاف، واختيار الاختبارات، والخيارات، والتقارير، والتغطية.

اقرأ دون اتصالelide help tooling-jvm-testing

في هذه الصفحة

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

الطرفية
bash
elide test

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

اكتشاف اختبارات JavaScript وتشغيلها باستخدام Elide
 ~/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)، لذا لا يجد جذر مساحة العمل اختبارات الأعضاء. حدّد مسارًا لتشغيلها.

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

test("adds two values", () => {
  assert.equal(1 + 1, 2);
});
utf-8 · js · الأسطر: 6

اختبارات 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:⁩

الطرفية
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
elide test — محدِّدات JUnit في مشروع Kotlin
 ~/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:⁩

الطرفية
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() }
}
utf-8 · pkl · الأسطر: 5

مخرجات 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
utf-8 · text · الأسطر: 11
  • يفتح # 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.

يمكن لتكاملات الاختبار ضبط 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 }
  }
}
utf-8 · pkl · الأسطر: 21
الخاصية المعنى الافتراضي
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[=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 فقط.

الصياغة: تصحيح الأخطاء. يفشل الخيار المجهول أو القيمة الناقصة قبل تشغيل أي شيء (مهام البناء).

القيود

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

الواجهة المدعومة: واجهة اختبارات Node.

أمثلة

ابدأ من قالب:

الطرفية
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"
    }
  }
}
utf-8 · pkl · الأسطر: 24

اقرأ هذه القيم عبر 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.

هل كانت هذه الصفحة مفيدة؟