اختبارات التوثيق
أمثلة خاضعة للاختبار
اختبارات التوثيق درس مجاني في Learn Rust Coding على CoddyKit. هذا هو الدرس 4 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Learn Rust Coding، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Learn Rust Coding 4 دروس في المجموع.
ما اختبارات التوثيق؟
اختبارات التوثيق هي أمثلة شيفرة داخل تعليقات التوثيق، يقوم Cargo بتجميعها وتشغيلها فعليًا. وهي تحافظ على صحة توثيقكم وعمل أمثلتكم.
الشيفرة في تعليقات التوثيق
ضعوا شيفرة المثال في كتلة شيفرة محاطة بثلاث علامات خلفية داخل تعليق ///، وتحت عنوان # Examples. واللغة الافتراضية هي Rust.
/// Doubles a number.
///
/// # Examples
///
/// let result = my_crate::double(4);
/// assert_eq!(result, 8);
pub fn double(n: i32) -> i32 {
n * 2
}تشغيل اختبارات التوثيق
تُشغّل اختبارات التوثيق كجزء من cargo test. وتُعرض نتائجها بشكل منفصل ضمن قسم Doc-tests.
cargo testدوال التحقق في الأمثلة
تتضمن الأمثلة عادةً دوال تحقق، حتى يتسبب المثال الخاطئ في فشل الاختبار، لا في نجاح التجميع فحسب.
/// Returns the larger of two values.
///
/// # Examples
///
/// assert_eq!(my_crate::max(3, 7), 7);
/// assert_eq!(my_crate::max(9, 2), 9);
pub fn max(a: i32, b: i32) -> i32 {
if a > b { a } else { b }
}إخفاء أسطر الإعداد
ضعوا الرمز # في بداية السطر ليُشغّل السطر، لكن يُخفى من التوثيق المعروض. وهذا مفيد للشيفرة التمهيدية مثل الاستيرادات.
/// # Examples
///
/// # use my_crate::Counter;
/// let mut c = Counter::new();
/// c.increment();
/// assert_eq!(c.value(), 1);أمثلة تستخدم علامة الاستفهام
لاستخدام العامل ?، غلّفوا جسم المثال داخل main مخفية، أو داخل دالة مساعدة مخفية، تُرجع Result. وتبدأ الأسطر المخفية بالرمز #.
/// # Examples
///
/// # fn run() -> Result<(), std::num::ParseIntError> {
/// let n: i32 = "42".parse()?;
/// assert_eq!(n, 42);
/// # Ok(())
/// # }أمثلة no_run
ضعوا علامة no_run على كتلة الشيفرة المحاطة لتجميعها من دون تنفيذها — وهذا مناسب للأمثلة التي تحتاج إلى الشبكة أو الملفات.
/// Fetches a page (compiled but not executed).
///
/// Annotate the code fence with no_run so it is type-checked only.
pub fn fetch(url: &str) -> String {
format!("contents of {url}")
}ignore و should_panic
تعليقات أخرى على سياج الشيفرة:
ignore— لا تُجمع الشيفرة ولا تُشغّلshould_panic— من المتوقع أن تتسبب في حالة ذعرcompile_fail— من المتوقع ألا تُجمع
أهمية اختبارات التوثيق
تمنحكم اختبارات التوثيق فائدتين في آن واحد:
- توثيقًا دقيقًا دائمًا
- تغطية اختبارية مجانية لأمثلتكم العامة
إذا تعطل مثال، تفشل مجموعة الاختبارات.
اسم الصندوق في الأمثلة
تُشغّل اختبارات التوثيق كما لو كانت من خارج الصندوق، لذا أشيروا إلى العناصر باستخدام اسم الصندوق، مثل my_crate::func، أو باستخدام استيراد use.
الكتل المحاطة مقابل الكتل ذات المسافة البادئة
تقبل اختبارات التوثيق نمطين من الكتل:
- كتلة محاطة تستخدم ثلاث علامات خلفية، وتتيح تعليقات مثل
no_run - كتلة ذات مسافة بادئة، مقدارها أربع مسافات، كما هو موضح في هذه الأمثلة
تُستخدم الكتل المحاطة بشكل أكثر شيوعًا في الشيفرة الفعلية.
تحقق سريع
ماذا يفعل السطر الذي يبدأ بالرمز # داخل كتلة شيفرة لاختبار توثيق؟
مراجعة
لقد تعلمتم اختبارات التوثيق:
- تُجمع الشيفرة الموجودة في كتل
///وتُشغّل بواسطةcargo test - استخدموا دوال التحقق للتأكد من السلوك
- يخفي
#أسطر الإعداد من التوثيق المعروض - التعليقات:
no_runوignoreوshould_panicوcompile_fail - تحافظ هذه الاختبارات تلقائيًا على صحة الأمثلة
الأسئلة الشائعة
هل درس «اختبارات التوثيق» مجاني؟
نعم — نص درس «اختبارات التوثيق» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Learn Rust Coding، انتقل إلى CoddyKit PRO. تتضمن دورة Learn Rust Coding 4 دروس في المجموع.
ماذا ستتعلم في «اختبارات التوثيق»؟
أمثلة خاضعة للاختبار تتمرن على Learn Rust Coding مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ Learn Rust Coding؟
لا تُشترط خبرة سابقة. Learn Rust Coding على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 4 من أصل 4.
كم من الوقت يستغرق درس «اختبارات التوثيق»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس Learn Rust Coding هذا؟
نعم. كل درس في Learn Rust Coding يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.
جميع الدروس في هذه الدورة
- اختبارات الوحدة
- اختبارات التكامل
- تعليقات التوثيق
- اختبارات التوثيق