نظام التسجيل - اختبار وبنية التحقق

Audience: Engineers maintaining release confidence, deterministic الجمهور: المهندسون الذين يحافظون على ثقة الإصدار، والتحقق الحتمي، وقطع الاختبار الجاهزة للتدقيق.

جدول المحتويات

نظرة عامة تنفيذية
عقد اختبار النظام
جرد مدفوع بالسجل
مصفوفة التغطية ونموذج الفجوة
عقد الأثر والنصوص
أدوات التنفيذ
هيكل المجموعة
مرجع متقاطع ملف بملف

نظرة عامة تنفيذية

يعمل نظام الاختبار على التحقق من السلوك من خلال حدود الإنتاج الحقيقية (CLI و استيعاب المحول)، ويصدر قطع أثرية منظمة، ويتتبع التغطية باستخدام ملفات TOML الخاصة بالسجل + الفجوات. تم تصميم الحزمة للحفاظ على تشغيل الاختبارات بشكل حتمي وقابل للتفتيش.

F:system-tests/README.md L12-L39 F:system-tests/AGENTS.md L12-L35

عقد اختبار النظام

اختبارات النظام تتطلب:

تأكيدات الفشل المغلقة،
لا توجد دقة تعتمد على النوم،
أوامر الإنتاج وواجهات البيانات،
إصدار الأرتيفكت لكل اختبار إلزامي.

F:system-tests/AGENTS.md L14-L37

تساعد ميزة التحكم في الوصول على إبقاء اختبارات النظام واضحة في CI والتشغيلات المحلية. F:system-tests/README.md L34-L45

جرد مدفوع بالسجل

system-tests/test_registry.toml هو المرجع المعتمد لـ:

الفئات،
بيانات التعريف لكل اختبار،
نقاط دخول الأوامر،
العناصر المطلوبة،
الوقت المقدر للتشغيل.

F:system-tests/test_registry.toml L5-L14 F:system-tests/test_registry.toml L15-L480

مصفوفة التغطية ونموذج الفجوة

system-tests/TEST_MATRIX.md يحدد لقطات تغطية الأهداف P0/P1/P2. F:system-tests/TEST_MATRIX.md L12-L42

system-tests/test_gaps.toml تتبع الفجوات المفتوحة/المغلقة مع معايير قبول واضحة وتخطيط الفئات/الأولويات. F:system-tests/test_gaps.toml L4-L74 F:system-tests/test_gaps.toml L75-L190

اعتبارًا من 2026-02-07، تم إغلاق جميع فجوات P1 الأساسية المتعقبة (إزالة التكرار للمحدد المركب، مرابط إثبات الجزء الجزئي، فشل الإغلاق المتقاطع بين الأجزاء، فشل إغلاق التعلق، توازن SQLite/في الذاكرة). اعتبارًا من 2026-02-14، تم أيضًا إغلاق تغطية ضغط/أداء P2 مع آثار أداء أساسية وجانبية حتمية وCI لمصفوفة الملف الشخصي. اعتبارًا من نفس التاريخ، تم تأمين نتائج الأمان لإطلاق OSS 0 من خلال اختبار النظام لحدود/سياسات CLI، ومسارات التلاعب الهيكلي للبيان، وتجسيد فساد SQLite، وإنفاذ الجزء المفتوح الفردي. اعتبارًا من نفس التاريخ، يتم تأمين دورة حياة HTTP للجزء الجانبي واستمرار عدم التكرار من خلال اختبار النظام مع عمليات فرعية حقيقية للجزء الجانبي + سير عمل نقل TCP. اعتبارًا من 2026-02-08، يتم عكس متابعة توسيع عالم CLI OSS من الدرجة الأولى بالكامل في اختبارات النظام: التحقق من شكل معرف المسجل، وفحوصات فشل الإغلاق للإدخال العدائي لتسجيل التعلق، ومدة الإغلاق التلقائي/مسارات دورة الحياة المجمعة، وتجزئة JSON للاستعلام + حواجز الحماية فوق الحد، ومسارات أوامر CLI لـ Decision Gate ingest-fixture بفشل/نجاح صارم. اعتبارًا من 2026-02-08، يتم أيضًا تأمين تعبئة حاوية الجزء الجانبي من خلال اختبار النظام عبر مجموعة sidecar_docker (فحوصات تقوية الأصول + مسار Docker Compose e2e مع سياسة تخطي/فشل صريحة عبر RECORDER_REQUIRE_DOCKER). اعتبارًا من 2026-02-08، يتحقق مسار Docker Compose أيضًا من سلوك بدء التشغيل/اختبار الجاهزية للحاويات (/startup, /ready) قبل وبعد انتقالات دورة الحياة لفتح الجزء. اعتبارًا من 2026-02-13، يتحقق مسار Docker Compose من تقوية التمهيد السري: يتم توفير مادة مصدر الرمز المميز عبر إدخال سر Docker، ثم يتم تجسيدها في مسار ملف الرمز المميز tmpfs داخل الحاوية قبل بدء تشغيل الجزء الجانبي. اعتبارًا من 2026-02-10، تشمل تغطية العمليات مسار توليد العقود الذي يؤكد آثار إسقاط SDK/OpenAPI المطبقة (sdk/types.json, sdk/methods.json, مكونات OpenAPI الصارمة Bundle/VerificationVerdict) لاستعداد مولد SDK في الأسفل. اعتبارًا من 2026-02-11، تم تقسيم مجموعة العمليات إلى وحدات (operations/{query,config,locale,contract}.rs) للحفاظ على نطاق ملفات الاختبار وقابليتها للمراجعة مع الحفاظ على سلوك الآثار/التقارير الحتمية. اعتبارًا من 2026-02-11، تم أيضًا تقسيم مجموعات الأمان والتكامل إلى ملفات (security_{support,limits,signer,contract_bundle}.rs, integration_openclaw_{support,core,additional}.rs, integration_decision_gate_{support,contract_shape,ingest}.rs) للحفاظ على قابلية مراجعة أسطح الاختبار مع الحفاظ على سلوك حتمي وبيانات تشغيل. اعتبارًا من نفس التاريخ، تشمل تغطية الأمان تحقق فشل الإغلاق من تشبع قائمة عمليات SQLite مع آثار ملخص التشبع الحتمية (sqlite_operation_queue_saturation_fails_closed). اعتبارًا من 2026-02-14، تشمل تغطية الأداء أيضًا:

performance::stress_concurrent_append_query_sqlite,
performance::performance_bundle_materialization_smoke,
sidecar_perf::sidecar_perf_smoke_generates_gate_report,
sidecar_capacity::sidecar_capacity_sweep_generates_report, with profile-matrix orchestration (scripts/ci/perf_matrix.py) and release gating (scripts/ci/perf_gate.py) against committed baseline policy files (system-tests/perf_baselines/*.json). نموذج أداء السايدكار مقسم إلى مسارين صريحين:
regression lane (sidecar_perf): fixed deterministic workload for CI سلامة مضادة للتراجع؛
capacity lane (sidecar_capacity): release-only saturation sweep used to characterize max sustainable ingest throughput and enforce pinned-runner floors. The sidecar regression/capacity lanes are aligned with the current single-writer v1 contract: stream-scoped query requests include required tenant_id and recorder_id, and envelope writes include canonical stream identity fields. As of 2026-02-14 (perf architecture split), both lanes emit explicit workload.* metadata and lane identity (regression/capacity) in artifacts; capacity reports additionally emit max_sustainable_rps, knee_rps, and error/latency-at-knee fields. As of 2026-02-15, benchmark orchestration is standardized through scripts/perf/run.py presets (smoke, regression, capacity) with schema-v2 normalized report emission under target/perf/v2/*.json, triage output under target/perf/triage/latest.md, and capability-aware gate evaluation via the same baseline policy surface. As of the same date, core macro performance reports are emitted both at legacy target/performance/latest.json and per-suite paths target/performance/stress/latest.json, target/performance/bundle/latest.json to prevent suite overwrite ambiguity. As of the same date (Phase 3 expansion), the sidecar regression lane executes multi-trial timed windows and emits percentile confidence-spread metadata, the core performance suite emits query-cardinality and SQLite durability sweeps plus bundle scale-curve and deterministic replay hash-equality metrics, and the capacity lane emits explicit authoritative vs non-authoritative gate labeling. As of 2026-02-16, sidecar regression drift-ratio enforcement is runner-authoritative: write_path_trial_drift_ratio remains emitted for all runner classes, but the hard ceiling gate is blocking only for linux_x86_64_ci and linux_x86_64_pinned; local runner-class executions are informational for that metric while still emitting the same artifact schema. As of 2026-02-16, sidecar regression memory metrics are split into hot-path high-water (rss_growth_bytes) and quiesced retained-growth (rss_growth_quiesced_bytes) signals, with rss_reclaim_ratio emitted for allocator high-water context. As of 2026-02-16, sidecar durability characterization coverage includes post-saturation graceful-stop restart timing (restart_ready_ms) and restart-correctness hardening for rolled parallel load paths; integration coverage now explicitly guards against multi-open-segment persistence across restart boundaries. As of the same date, durability measurement strictness captures live wal_size_bytes plus coupled PRAGMA wal_checkpoint(NOOP) state per case and emits durability_wal_ratio_vs_1000_comparable so WAL-ratio decisions can fail-closed when baseline WAL sampling is non-comparable. As of the same date, sidecar perf coverage also includes an informational retained-memory attribution lane (sidecar_perf_rss_retained_memory_attribution_characterization, ignored by default due runtime) that emits target/sidecar-perf/rss_attribution_latest.json with sequential/parallel quiesce-window RSS checkpoints and smaps_rollup class deltas. As of the same date, sidecar perf coverage also includes an ignored ingest- tuning characterization lane (sidecar_perf_rss_ingest_tuning_characterization) that sweeps ingest queue and batch knobs across sequential/parallel workers, emits target/sidecar-perf/rss_ingest_tuning_latest.json, and records a data-derived mechanism classification (queue_backlog_dominated, batch_churn_dominated, or mixed) plus mitigation recommendation metadata. As of 2026-02-16, sidecar helper startup readiness waits up to 30 seconds for the /health probe before failing closed, reducing false negatives under high-concurrency nextest runs while preserving early-exit diagnostics. As of 2026-02-22, recorder lifecycle coverage includes explicit restart-boundary sealed-chain continuity validation (recorder_segment_chain_continuity_across_restart_fail_closed) and verification coverage includes explicit fail-closed predecessor-id tamper detection over multi-segment fixtures (bundle_verify_rejects_sealed_predecessor_tamper_after_multi_segment_fixture). As of the same date, storage-level latest-sealed accessor behavior is covered with property-based tests across memory and SQLite backends (latest_sealed_accessor_property_memory, latest_sealed_accessor_property_sqlite) and is exercised in a dedicated blocking nightly hard-adversarial lane (nightly-hard-adversarial). As of the same date, CI perf lanes remain advisory while correctness/security lanes remain hard-gated: PR/main perf jobs execute with non-blocking posture, بينما يتم حظر مسارات تصحيح/تقوية الملكية الليلية.

عقد الأثر والنصوص

كل تشغيل اختبار يصدر على الأقل:

summary.json,
summary.md,
tool_transcript.json.

TestReporter و TestArtifacts ينشئان جذور تشغيل حتمية، يفرضان سياسة إعادة استخدام جذور التشغيل، وينتجان مستندات ملخص موحدة. CliSession الآن يحل recorder عبر كل من ملف التعريف المباشر و تخطيطات ثنائية deps ويفضل حل target/debug في مساحة العمل قبل التراجع عن البناء، مما يحافظ على تنفيذ أوامر مسار التشغيل بشكل حتمي عبر تخطيطات عمليات cargo test و cargo nextest على أنظمة Windows و Unix.

F:system-tests/tests/helpers/artifacts.rs L65-L131 F:system-tests/tests/helpers/artifacts.rs L133-L214 F:system-tests/tests/helpers/cli.rs L19-L107 F:system-tests/tests/helpers/cli.rs L109-L240

أدوات التنفيذ

Python المساعدات:

test_runner.py: registry-based execution with optional parallelism, test_runner.py: تنفيذ قائم على السجل مع إمكانية التوازي الاختياري، جذور الأثر لكل اختبار، وتوليد البيان.
coverage_report.py: ينشئ مستندات من السجل + الفجوات.
gap_tracker.py: يسرد/يعرض/يغلق الفجوات ويولد مطالبات التنفيذ.
docs_verify.py: enforces full-scope docs registry/metadata policy and يتم تنفيذ الكتل المحاطة القابلة للتشغيل/التحليل/التحقق منها بشكل اختياري.
docs_tag_fences.py: inserts default dg-* metadata on untagged fences for وثائق محددة النطاق للمحقق.
docs_linkify_refs.py: enforces [F:...] cross-reference linkification in Docs/** و README.md.

سياسة التحقق من الوثائق:

In-scope docs are declared in Docs/verification/registry.toml with explicit mode = "runnable" أو mode = "static".
Docs/roadmap/** مستثنى عمداً من نطاق مدقق الوثائق.
CI posture is strict:
- PR: --scope=all --run --level=fast --strict-requires
- main/release: --scope=all --run --level=all --strict-requires.
Nightly posture is tiered:
- مسارات صعبة: الجودة، الوثائق، واختبارات النظام P0/P1 تفشل في سير العمل؛
- informational lanes: regression perf, optional P2 perf, and optional توصيف السعة دائمًا قم بتحميل العناصر ولا تعطل النجاح.

تفرض CI أيضًا بوابات تغطية على مستوى المصدر من خلال scripts/ci/coverage_gate.sh، الذي يقوم بتشغيل cargo llvm-cov --workspace --all-features --all-targets --summary-only و يفشل عند إغلاقه عندما تنخفض تغطية خطوط العمل أو الجانبية دون عتبات السياسة، أو عندما تنخفض ملفات معالجات الجانبية/البرمجيات الوسيطة/الخادم دون حد أدنى من خطوط الملفات لكل ملف. تعمل البوابة في كل من سير العمل PR والرئيسي بعد مسارات الاختبار.

F:scripts/system_tests/test_runner.py L64-L112 F:scripts/system_tests/test_runner.py L119-L199 F:scripts/system_tests/coverage_report.py L43-L101 F:scripts/system_tests/gap_tracker.py L92-L140 F:scripts/docs/docs_verify.py F:scripts/docs/docs_tag_fences.py F:scripts/docs/docs_linkify_refs.py F:Docs/verification/registry.toml F:scripts/ci/coverage_gate.sh F:.github/workflows/ci_pr.yml F:.github/workflows/ci_main.yml F:.github/workflows/ci_nightly.yml F:.github/workflows/release.yml

هيكل المجموعة

تغطي وحدات المجموعة:

smoke: بدء تشغيل CLI وفحوصات المساعدة/الإصدار،
bundle: بناء/تحقق/تفتيش واكتشاف التلاعب،
persistence: إعادة التشغيل، الحتمية، وفحوصات التوافق بين SQLite/الذاكرة.
operations: query ordering/cursor plus JSON pagination/limit guardrails and recorder-id + auto-seal config validation parity checks, plus typed فحوصات عرض SDK لإنشاء العقود،
security: bounded CLI input surfaces, malformed-identifier rejection, secure signer-file policy, signer-rotation recovery/corruption behavior, contract path safety, hostile bundle parse-boundary checks, and hostile record-with-attachments boundary checks, plus SQLite operation queue سلوك الفشل المغلق عند التشبع مع آثار ملخصة حتمية،
recorder: lifecycle plus auto-seal count/duration/combined behavior and recorder: دورة الحياة بالإضافة إلى عدد/مدة الإغلاق التلقائي/السلوك المدمج و فحوصات استمرارية تسجيل المرفقات عبر الحدود الحقيقية لواجهة سطر الأوامر،
sidecar: real sidecar process lifecycle over HTTP (record/query/build/verify) and restart-boundary idempotency فحص استمرارية إعادة التشغيل/الصراع،
sidecar_perf: deterministic regression-lane sidecar perf artifact emission لـ CI gating،
sidecar_capacity: release-only capacity-lane sidecar saturation sweep for توصيف/تحديد مرور العداء المثبت
sidecar_docker: Dockerfile/Compose/config hardening checks and Docker Compose build/up/down with containerized sidecar startup/readiness probe checks plus record/query workflow, including secret-source + tmpfs token مساواة البوتستراب،
integration_openclaw: fixture-driven OpenClaw gateway/CLI ingest, signed/unsigned verification lanes, sequence-gap policy checks, sensitive integration_openclaw: بوابة/واجهة سطر الأوامر OpenClaw المدفوعة بالمكونات، مسارات التحقق الموقعة/غير الموقعة، فحوصات سياسة فجوات التسلسل، حذف الحقول الحساسة، وفحوصات التعامل مع الحمولة المحدودة.
integration_decision_gate: fixture-driven Decision Gate MCP runpack flow ingest through the production recorder-decision-gate-adapter crate, signed/unsigned verification lanes, runpack-integrity strict-vs-anomaly policy checks (including manifest self-integrity recomputation), sensitive transcript-field redaction, bounded transcript payload handling checks, CLI decision-gate ingest-fixture command-path validation, and a fixture conformance gate that enforces canonical Decision Gate tool request/response shapes (including export-vs-verify checked_files الدلالات).

مرجع متقاطع لكل ملف

المنطقة	الملف	الملاحظات
العقد والمعايير	`system-tests/AGENTS.md`	متطلبات سلوكية وفنية للاختبارات النظامية.
نظرة عامة على التنفيذ	`system-tests/README.md`	كيفية تشغيل وتوسيع الحزم.
لقطة تغطية	`system-tests/TEST_MATRIX.md`	مصفوفة P0/P1/P2.
سجل الاختبار	`system-tests/test_registry.toml`	جرد موثوق وأوامر التشغيل.
بيانات تتبع الفجوات	`system-tests/test_gaps.toml`	فجوات التغطية ومعايير القبول.
مساعد الأرتيفكت	`system-tests/tests/helpers/artifacts.rs`	عقدة تشغيل الجذر وتوليد الملخص.
مساعد CLI	`system-tests/tests/helpers/cli.rs`	تنفيذ أوامر CLI الحقيقية والتقاط النص.
مساعد Sidecar	`system-tests/tests/helpers/sidecar.rs`	بدء/إيقاف عملية sidecar الحقيقية والتقاط نص HTTP.
مساعد أداء Sidecar	`system-tests/tests/helpers/perf_sidecar.rs`	عميل مشترك للحفاظ على الاتصال، توليد حمولة حتمية، وأدوات بيانات وصف lane لأداء sidecar.
مساعد Docker	`system-tests/tests/helpers/docker.rs`	استقصاءات Docker daemon/compose ومساعدات الأوامر للمسارات المعبأة.
حزمة Sidecar	`system-tests/tests/suites/sidecar.rs`	دورة حياة HTTP لـ sidecar (تسجيل/استعلام/بناء/تحقق) والتحقق من عدم التكرار عند إعادة التشغيل.
حزم أداء Sidecar	`system-tests/tests/suites/sidecar_perf.rs`, `system-tests/tests/suites/sidecar_capacity.rs`	توليد الأرتيفكت لمسار الانحدار ومسار السعة لسياسة أداء ingest لـ sidecar، بالإضافة إلى مسار نسبة الذاكرة المحتفظ بها غير المعتمد (`target/sidecar-perf/rss_attribution_latest.json`) ومسار تخصيص ضبط ingest (`target/sidecar-perf/rss_ingest_tuning_latest.json`).
تنسيق الأداء	`scripts/perf/run.py`, `scripts/perf/report_schema_v2.json`, `scripts/perf/collect_runner_fingerprint.py`, `scripts/perf/update_baseline.py`	نقطة دخول مضبوطة، عقد تقرير schema-v2، التقاط بصمة العداء، وعملية تحديث الأساس المدارة.
مساعد تحليل الأداء	`scripts/perf/profile_hotspot.sh`	عملية سريعة لتحويل مجموعة الفشل إلى محلل للأماكن الساخنة.
حزمة Docker لـ Sidecar	`system-tests/tests/suites/sidecar_docker.rs`	تقوية تعبئة حاوية sidecar والتحقق من سير العمل لـ Docker Compose، بما في ذلك استقصاءات بدء التشغيل/الجاهزية وسلوك تمهيد رمز tmpfs لمصدر سري.
حزمة تكامل OpenClaw	`system-tests/tests/suites/integration_openclaw.rs`, `system-tests/tests/suites/integration_openclaw_support.rs`, `system-tests/tests/suites/integration_openclaw_core.rs`, `system-tests/tests/suites/integration_openclaw_additional.rs`	تحقق من إدخال المحول المدفوع بالترتيب لتدفقات المحاكاة للبوابة + CLI.
أدوات OpenClaw	`system-tests/tests/fixtures/openclaw_gateway_mock_events.json`	أداة تدفق المحاكاة للبوابة متوافقة مع مخطط أحداث OpenClaw.
أدوات OpenClaw	`system-tests/tests/fixtures/openclaw_cli_mock_events.json`	أداة تدفق المحاكاة بأسلوب التراجع متوافقة مع مخطط أحداث OpenClaw.
بنية تكامل OpenClaw	Docs/architecture/recorder_openclaw_integration_architecture.md	خريطة إصدار، حذف، وعقد سياسة الحمولة المحدودة.
محول إنتاج Decision Gate	`crates/recorder-decision-gate-adapter/src/adapter.rs`	تنفيذ خريطة Decision Gate إلى Recorder القياسية التي تم اختبارها بواسطة الاختبارات النظامية.
حزمة تكامل Decision Gate	`system-tests/tests/suites/integration_decision_gate.rs`, `system-tests/tests/suites/integration_decision_gate_support.rs`, `system-tests/tests/suites/integration_decision_gate_contract_shape.rs`, `system-tests/tests/suites/integration_decision_gate_ingest.rs`	تحقق من تدفق MCP المدفوع بالترتيب لربط مستوى التحكم.
أداة Decision Gate	`system-tests/tests/fixtures/decision_gate_runpack_mock_flow.json`	أداة تدفق MCP المحاكي متوافقة مع نص Decision Gate وتخطيط بيان runpack.
بنية تكامل Decision Gate	Docs/architecture/recorder_decision_gate_integration_architecture.md	خريطة تدفق MCP بالإصدار، سياسة سلامة runpack، وحذف النص/عقد الحدود.
تحليل البيئة	`system-tests/src/config/env.rs`	تحليل صارم للبيئة لتكوين الاختبار.
نص العداء	`scripts/system_tests/test_runner.py`	محرك تنفيذ مدفوع بالسجل.
مولد وثائق التغطية	`scripts/system_tests/coverage_report.py`	خط أنابيب وثائق الاختبار المولدة.
نص إدارة الفجوات	`scripts/system_tests/gap_tracker.py`	أدوات دورة حياة الفجوات.
سجل التحقق من الوثائق	`Docs/verification/registry.toml`	سلطة وضع التشغيل/الثابت للوثائق التي تخضع للمحقق (خارطة الطريق مستثناة).
نصوص التحقق من الوثائق	`scripts/docs/docs_verify.py`, `scripts/docs/docs_tag_fences.py`, `scripts/docs/docs_linkify_refs.py`	سياسة بيانات السياج، فحوصات تنفيذ الوثائق القابلة للتشغيل، وفرض الربط `[F:...]`.