| LIT(1) | LLVM | LIT(1) |
نام (NAME)
lit - ابزار آزمون یکپارچه LLVM
خلاصه دستور (SYNOPSIS)
lit [options] [tests]
توضیحات (DESCRIPTION)
lit ابزاری قابل‌حمل برای اجرای مجموعه‌های آزمون به سبک LLVM و Clang، خلاصه‌سازی نتایج آن‌ها و نمایش موارد شکست‌خورده است. lit به عنوان ابزاری سبک برای آزمون با رابط کاربری تا حد ممکن ساده طراحی شده است.
lit باید با مشخص کردن یک یا چند آزمون (tests) در خط فرمان اجرا شود. آزمون‌ها می‌توانند فایل‌های آزمون مجزا یا دایرکتوری‌هایی برای جستجوی آزمون‌ها باشند (به بخش TEST DISCOVERY مراجعه کنید).
هر آزمون مشخص‌شده (احتمالاً به‌صورت هم‌روند) اجرا خواهد شد و پس از اجرای تمام آزمون‌ها، lit اطلاعات خلاصه‌ای از تعداد آزمون‌های موفق یا ناموفق را چاپ می‌کند (به بخش TEST STATUS RESULTS مراجعه کنید). در صورت شکست هر یک از آزمون‌ها، برنامه lit با وضعیت خروج غیرصفر خارج خواهد شد.
به‌طور پیش‌فرض، lit از نمایش مختصر پیشرفت استفاده می‌کند و تنها اطلاعات خلاصه مربوط به آزمون‌های ناموفق را چاپ خواهد کرد. برای گزینه‌های کنترل نمایش پیشرفت و خروجی lit، به بخش گزینه‌های خروجی (OUTPUT OPTIONS) مراجعه کنید.
همچنین lit شامل تعدادی گزینه برای کنترل چگونگی اجرای آزمون‌ها است (ویژگی‌های خاص ممکن است به قالب آزمون مربوطه بستگی داشته باشد). برای اطلاعات بیشتر به بخش EXECUTION OPTIONS مراجعه کنید.
در نهایت، lit از گزینه‌های دیگری برای اجرای تنها زیرمجموعه‌ای از گزینه‌های مشخص‌شده در خط فرمان نیز پشتیبانی می‌کند؛ برای اطلاعات بیشتر به بخش SELECTION OPTIONS مراجعه کنید.
lit پس از تجزیه گزینه‌های خط فرمان، گزینه‌ها را از متغیر محیطی LIT_OPTS تجزیه می‌کند. LIT_OPTS عمدتاً برای تکمیل یا بازنویسی گزینه‌های خط فرمانی مفید است که از طریق هدف‌های check تعریف‌شده توسط سیستم ساخت پروژه به lit داده می‌شوند.
همچنین lit می‌تواند گزینه‌ها را از فایل‌های پاسخ (response files) که با استفاده از نحو @path/to/file.rsp به‌عنوان ورودی مشخص می‌شوند بخواند. آرگومان‌های خوانده‌شده از فایل باید در هر خط یکی باشند و به‌گونه‌ای پردازش می‌شوند که گویی در همان جایگاه آرگومان ارجاع‌دهنده فایل در خط فرمان قرار داشته‌اند. یک فایل پاسخ می‌تواند به فایل‌های پاسخ دیگر نیز ارجاع دهد.
کاربرانی که به معماری lit یا طراحی یک پیاده‌سازی آزمون برای lit علاقه‌مند هستند، باید بخش LIT INFRASTRUCTURE را ببینند.
گزینه‌های عمومی (GENERAL OPTIONS)
- -h, --help
- نمایش پیام راهنمای lit و خروج.
- --version
- نمایش شماره نسخه lit و خروج.
- -j N, --workers N
- اجرای موازی N آزمون. به‌طور پیش‌فرض، این مقدار متناسب با تعداد پردازنده‌های شناسایی‌شده و در دسترس به‌طور خودکار انتخاب می‌شود.
- --config-prefix NAME
- هنگام جستجوی مجموعه‌های آزمون، به جای lit.cfg و lit.site.cfg به دنبال NAME.cfg و NAME.site.cfg بگردد.
- -D NAME[=VALUE], --param NAME[=VALUE]
- افزودن پارامتر سفارشی NAME با مقدار داده‌شده VALUE (یا رشته خالی در صورت مشخص نشدن). معنا و کاربرد این پارامترها به مجموعه آزمون بستگی دارد.
گزینه‌های خروجی (OUTPUT OPTIONS)
- -q, --quiet
- جلوگیری از هرگونه خروجی، به جز موارد شکست آزمون‌ها.
- -s, --succinct
- نمایش خروجی کمتر؛ برای نمونه اطلاعات مربوط به آزمون‌های موفق نشان داده نمی‌شود. همچنین یک نوار پیشرفت نمایش می‌دهد، مگر اینکه گزینه --no-progress-bar مشخص شده باشد.
- -v, --verbose
- نمایش
اطلاعات
بیشتر در
مورد شکست
آزمون‌ها،
برای نمونه
تمام خروجی
آزمون به
جای فقط
نتیجه آن.
هر دستور پیش از اجرا چاپ می‌شود. این کار می‌تواند برای اشکال‌زدایی شکست آزمون‌ها مفید باشد، زیرا آخرین دستور چاپ‌شده همان دستوری است که شکست خورده است. افزون بر این، lit عبارت 'RUN: at line N' را پس از هر خط‌لوله دستور در خروجی درج می‌کند تا به یافتن خط مبدا دستور ناموفق کمک کند.
- -vv, --echo-all-commands
- نام مستعار منسوخ‌شده برای -v.
- -a, --show-all
- فعال‌سازی -v برای تمام آزمون‌ها و نه فقط آزمون‌های ناموفق.
- -o PATH, --output PATH
- نوشتن نتایج آزمون در مسیر ارائه‌شده.
- --no-progress-bar
- عدم استفاده از نوار پیشرفت مبتنی بر curses.
- --show-excluded
- نمایش آزمون‌های مستثنی‌شده (excluded).
- --show-skipped
- نمایش آزمون‌های نادیده‌گرفته‌شده (skipped).
- --show-unsupported
- نمایش آزمون‌های پشتیبانی‌نشده (unsupported).
- --show-pass
- نمایش آزمون‌های موفق (pass).
- --show-flakypass
- نمایش آزمون‌هایی که پس از تلاش مجدد موفق شده‌اند (flakypass).
- --show-xfail
- نمایش آزمون‌هایی که شکست آن‌ها مورد انتظار بوده است (xfail).
- --gtest-sharding
- فعال‌سازی تکه‌بندی (sharding) برای قالب GoogleTest.
- --no-gtest-sharding
- غیرفعال‌سازی تکه‌بندی برای قالب GoogleTest.
- --path PATH
- تعیین یک PATH اضافی برای استفاده هنگام جستجوی فایل‌های اجرایی در آزمون‌ها.
- --vg
- اجرای هر
آزمون به
صورت
جداگانه
تحت valgrind (با
استفاده از
ابزار memcheck).
آرگومان
--error-exitcode برای valgrind
استفاده
می‌شود تا
شکست‌های valgrind
موجب خروج
برنامه با
وضعیتی غیر
از صفر
شوند.
هنگام فعال بودن این گزینه، lit همچنین به طور خودکار ویژگی "valgrind" را ارائه می‌دهد که می‌تواند برای غیرفعال کردن مشروط آزمون‌های خاص (یا انتظار شکست در آن‌ها) استفاده شود.
- --vg-leak
- هنگام استفاده از --vg، بررسی‌های نشت حافظه را فعال می‌کند. هنگام فعال بودن این گزینه، lit همچنین به طور خودکار ویژگی "vg_leak" را ارائه می‌دهد که می‌تواند برای غیرفعال کردن مشروط آزمون‌های خاص (یا انتظار شکست در آن‌ها) استفاده شود.
- --vg-arg ARG
- هنگام استفاده از --vg، یک آرگومان اضافی را برای ارسال به خود valgrind تعیین می‌کند.
- --no-execute
- هیچ آزمونی اجرا نشود (فرض می‌شود که همگی با موفقیت پاس شده‌اند).
- --xunit-xml-output XUNIT_XML_OUTPUT
- نوشتن گزارش‌های آزمون به صورت XML سازگار با XUnit در فایل مشخص‌شده.
- --report-failures-only
- تنها گنجاندن شکست‌ها (بخش TEST STATUS RESULTS را ببینید) در گزارش.
- --resultdb-output RESULTDB_OUTPUT
- نوشتن JSON سازگار با LuCI ResultDB در فایل مشخص‌شده.
- --time-trace-output TIME_TRACE_OUTPUT
- نوشتن JSON سازگار با Chrome tracing در فایل مشخص‌شده.
- --timeout MAXINDIVIDUALTESTTIME
- حداکثر زمان صرف‌شده برای اجرای یک آزمون منفرد (به ثانیه). 0 به معنای نامحدود بودن زمان است. [پیش‌فرض: 0]
- --timeout N
- صرف حداکثر N ثانیه (به طور تقریبی) برای اجرای هر آزمون جداگانه. 0 به معنای نبود محدودیت زمانی بوده و مقدار پیش‌فرض نیز 0 است. توجه داشته باشید که این گزینه نام مستعاری برای --max-time نیست؛ این دو مقادیر بیشینهٔ متفاوتی را کنترل می‌کنند.
- --max-failures MAX_FAILURES
- توقف اجرا پس از تعداد مشخص‌شده از شکست‌ها.
- --max-retries-per-test N
- تلاش مجدد برای اجرای آزمون‌های ناموفق حداکثر تا N بار. از میان گزینه‌های زیر برای اجرای مجدد آزمون‌های ناموفق، گزینهٔ --max-retries-per-test تنها موردی است که نیازی به تغییر در اسکریپت‌های آزمون یا پیکربندی آزمون ندارد:
- گزینهٔ lit با نام --max-retries-per-test
- گزینهٔ مجموعه آزمون با نام config.test_retry_attempts
- یادداشت ALLOW_RETRIES: در اسکریپت آزمون
هر گزینه در فهرست بالا، گزینهٔ پیش از خود را باطل می‌کند (بر آن ارجحیت دارد).
- --allow-empty-runs
- در صورتی که تمام آزمون‌ها فیلتر شوند، اجرا با شکست متوقف نشود.
- --per-test-coverage
- تولید داده‌های پوشش آزمون لازم، تفکیک‌شده به ازای هر مورد آزمون (شامل تنظیم یک مقدار یکتا برای LLVM_PROFILE_FILE به ازای هر RUN). فایل‌های داده‌های پوشش در دایرکتوری مشخص‌شده توسط config.test_exec_root ایجاد خواهند شد.
- --ignore-fail
- خروج با وضعیت صفر حتی اگر برخی از آزمون‌ها شکست بخورند.
- --skip-test-time-recording
- ردیابی نکردن زمان واقعی سپری‌شده (wall time) برای هر آزمون.
- --time-tests
- ردیابی
زمان واقعی
(wall time) صرف‌شده
برای اجرای
هر آزمون
جداگانه و
درج نتایج
در خروجی
خلاصه. این
گزینه برای
تشخیص
اینکه کدام
آزمون‌ها
در یک
مجموعه
آزمون
بیشترین
زمان را
برای اجرا
مصرف
می‌کنند،
مفید است.
به‌طور پیش‌فرض، lit ابتدا آزمون‌های ناموفق را اجرا می‌کند، سپس برای بهینه‌سازی همزمانی، آزمون‌ها را به ترتیب نزولی زمان اجرا، اجرا می‌کند. ترتیب اجرا را می‌توان با استفاده از گزینهٔ --order تغییر داد.
داده‌های زمان‌بندی در test_exec_root و در فایلی به نام .lit_test_times.txt ذخیره می‌شوند. اگر این فایل وجود نداشته باشد، lit برای تسریع اختیاری ساخت‌های تمیز (clean builds)، وجود فایل را در test_source_root بررسی می‌کند.
- --max-tests N
- حداکثر N آزمون را اجرا کرده و سپس پایان یابد.
- --max-time N
- حداکثر (تقریباً) N ثانیه را صرف اجرای آزمون‌ها کرده و سپس پایان یابد. توجه داشته باشید که این گزینه نام مستعاری برای --timeout نیست؛ این دو نوع متفاوتی از مقادیر حداکثری هستند.
- --order {lexical,random,smart}
- ترتیب اجرای آزمون‌ها را مشخص می‌کند. مقادیر پشتیبانی‌شده عبارتند از:
- lexical - آزمون‌ها بر اساس مسیر فایل آزمون به ترتیب لغوی اجرا خواهند شد. این گزینه زمانی که ترتیب آزمون قابل‌پیش‌بینی مورد نیاز باشد مفید است.
- random - آزمون‌ها به ترتیب تصادفی اجرا خواهند شد.
- smart - آزمون‌هایی که قبلاً ناموفق بوده‌اند ابتدا اجرا می‌شوند، سپس باقی آزمون‌ها، همگی به ترتیب نزولی زمان اجرا، اجرا خواهند شد. این مقدار پیش‌فرض است زیرا همزمانی را بهینه می‌کند.
- --shuffle
- آزمون‌ها را به ترتیب تصادفی اجرا می‌کند، نه به صورت ناموفق/کندترین در ابتدا. منسوخ شده است، به جای آن از --order استفاده کنید.
- -i, --incremental
- آزمون‌های ناموفق را ابتدا اجرا می‌کند (منسوخ شده است: از --order=smart استفاده کنید).
- --filter REGEXP
- تنها آزمون‌هایی را اجرا می‌کند که نام آن‌ها با عبارت منظم مشخص‌شده در REGEXP مطابقت داشته باشد. متغیر محیطی LIT_FILTER نیز می‌تواند به جای این گزینه استفاده شود، که به‌ویژه در محیط‌هایی که فراخوانی lit به‌طور غیرمستقیم انجام می‌شود مفید است.
- --filter-out REGEXP
- آزمون‌هایی که نام آن‌ها با عبارت منظم مشخص‌شده در REGEXP مطابقت دارد را فیلتر کرده و کنار می‌گذارد. متغیر محیطی LIT_FILTER_OUT نیز می‌تواند به جای این گزینه استفاده شود، که به‌ویژه در محیط‌هایی که فراخوانی lit به‌طور غیرمستقیم انجام می‌شود مفید است.
- --filter-failed
- تنها آزمون‌هایی را اجرا می‌کند که قبلاً ناموفق بوده‌اند. آزمون‌هایی که به تازگی اضافه شده‌اند اما هنوز اجرا نشده‌اند شامل نمی‌شوند.
- --xfail LIST
- آزمون‌هایی
که نام
آن‌ها در
فهرست
تفکیک‌شده
با
نقطه-ویرگول
LIST آمده است
را به عنوان
XFAIL در نظر
می‌گیرد.
این امر
زمانی که
نمی‌خواهید
مجموعه
آزمون را
دستکاری
کنید
می‌تواند
مفید باشد.
متغیر
محیطی LIT_XFAIL
نیز
می‌تواند
به جای این
گزینه
استفاده
شود، که
به‌ویژه در
محیط‌هایی
که
فراخوانی
lit به‌طور
غیرمستقیم
انجام
می‌شود
مفید است.
نام آزمون را می‌توان به عنوان یک نام فایل، نسبت به دایرکتوری مجموعه آزمون مشخص کرد. برای مثال:
LIT_XFAIL="affinity/kmp-hw-subset.c;offloading/memory_manager.cpp"
در این حالت، تمام آزمون‌های زیر به عنوان XFAIL در نظر گرفته می‌شوند:
libomp :: affinity/kmp-hw-subset.c libomptarget :: nvptx64-nvidia-cuda :: offloading/memory_manager.cpp libomptarget :: x86_64-pc-linux-gnu :: offloading/memory_manager.cpp
همچنین، نام آزمون می‌تواند به عنوان نام کامل آزمون گزارش‌شده در خروجی LIT مشخص شود. برای نمونه، می‌توانیم مثال قبلی را طوری تنظیم کنیم که نسخهٔ nvptx64-nvidia-cuda از offloading/memory_manager.cpp به عنوان XFAIL در نظر گرفته نشود:
LIT_XFAIL="affinity/kmp-hw-subset.c;libomptarget :: x86_64-pc-linux-gnu :: offloading/memory_manager.cpp"
- --xfail-not LIST
- آزمون‌های مشخص‌شده را به عنوان XFAIL در نظر نمی‌گیرد. متغیر محیطی LIT_XFAIL_NOT نیز می‌تواند به جای این گزینه استفاده شود. نحو استفاده همانند --xfail و LIT_XFAIL است. --xfail-not و LIT_XFAIL_NOT همواره بر تمامی دیگر تعاریف XFAIL، از جمله --xfail که جلوتر در خط فرمان ظاهر شده باشد، اولویت دارند و آن را لغو می‌کنند. هدف اصلی آن، فرونشاندن نتیجهٔ XPASS بدون دستکاری مورد آزمونی است که از دستورالعمل XFAIL استفاده می‌کند.
- --exclude-xfail
- آزمون‌های XFAIL اجرا نخواهند شد، مگر اینکه در فهرست‌های --xfail-not (یا LIT_XFAIL_NOT) قید شده باشند.
- --num-shards M
- مجموعه آزمون‌های انتخاب‌شده را به M زیرمجموعه هم‌اندازه یا "تکه" (shard) تقسیم کرده و فقط یکی از آن‌ها را اجرا می‌کند. باید همراه با گزینهٔ --run-shard=N استفاده شود که تکهٔ مورد نظر برای اجرا را انتخاب می‌کند. متغیر محیطی LIT_NUM_SHARDS نیز می‌تواند به جای این گزینه استفاده شود. این دو گزینه سازوکاری کلی برای بخش‌بندی مجموعه‌آزمون‌های بزرگ جهت اجرای موازی روی ماشین‌های مجزا (مثلاً در یک مزرعه آزمون بزرگ) فراهم می‌کنند.
- --run-shard N
- با فرض اینکه گزینهٔ --num-shards=M مشخص شده باشد، تعیین می‌کند که کدام تکه اجرا شود. این دو گزینه باید با هم استفاده شوند، و مقدار N باید در بازهٔ 1..M باشد. متغیر محیطی LIT_RUN_SHARD نیز می‌تواند به جای این گزینه استفاده شود.
- --debug
- اجرای lit در حالت اشکال‌زدایی، برای عیب‌یابی مشکلات پیکربندی و خود lit.
- --show-suites
- فهرست کردن مجموعه‌آزمون‌های کشف‌شده و خروج.
- --show-tests
- فهرست کردن تمام آزمون‌های کشف‌شده و خروج.
- --show-used-features
- نمایش تمام ویژگی‌های استفاده‌شده در مجموعه‌آزمون (در XFAIL، UNSUPPORTED و REQUIRES) و خروج.
- --update-tests
- ارسال آزمون‌های ناموفق به توابع موجود در فهرست lit_config.test_updaters برای بررسی اینکه آیا هیچ‌یک از آن‌ها روش به‌روزرسانی آزمون را برای موفقیت آن می‌دانند یا خیر.
وضعیت خروج (EXIT STATUS)
در صورتی که هرگونه شکستی رخ دهد (بخش نتایج وضعیت آزمون را ببینید) و گزینهٔ --ignore-fail داده نشده باشد، lit با کد خروج ۱ خارج خواهد شد. در غیر این صورت، با وضعیت ۰ خارج می‌شود. سایر کدهای خروج برای خطاهای غیرمرتبط با آزمون (برای مثال خطای کاربر یا خطای داخلی برنامه) استفاده می‌شوند.
شناسایی آزمون‌ها (TEST DISCOVERY)
ورودی‌های ارائه‌شده به lit می‌توانند آزمون‌های تکی، یا کل دایرکتوری‌ها یا سلسله‌مراتب‌هایی از آزمون‌ها برای اجرا باشند. هنگامی که lit آغاز به کار می‌کند، نخستین کاری که انجام می‌دهد تبدیل ورودی‌ها به فهرستی کامل از آزمون‌ها برای اجرا، به عنوان بخشی از فرایند کشف آزمون است.
در مدل lit، هر آزمون باید درون یک مجموعه‌آزمون قرار داشته باشد. lit ورودی‌های مشخص‌شده در خط فرمان را با جستجوی روبه‌بالا از مسیر ورودی تا رسیدن به فایل lit.cfg یا lit.site.cfg، به مجموعه‌آزمون‌ها نگاشت می‌کند. این فایل‌ها هم به عنوان نشانگر مجموعه‌آزمون و هم به عنوان فایل‌های پیکربندی عمل می‌کنند که lit آن‌ها را بارگذاری می‌کند تا متوجه شود چگونه آزمون‌های درون مجموعه‌آزمون را پیدا کرده و اجرا نماید.
پس از اینکه lit ورودی‌ها را به مجموعه‌آزمون‌ها نگاشت کرد، فهرست ورودی‌ها را پیمایش کرده، آزمون‌ها را برای فایل‌های منفرد اضافه نموده و دایرکتوری‌ها را به صورت بازگشتی برای یافتن آزمون‌ها جستجو می‌کند.
این رفتار، مشخص کردن زیرمجموعه‌ای از آزمون‌ها را برای اجرا ساده می‌کند، در حالی که همچنان به پیکربندی مجموعه‌آزمون اجازه می‌دهد نحوهٔ دقیق تفسیر آزمون‌ها را کنترل کند. علاوه بر این، lit همواره آزمون‌ها را بر اساس مجموعه‌آزمونی که در آن قرار دارند و مسیر نسبی آن‌ها در داخل مجموعه‌آزمون شناسایی می‌کند. برای پروژه‌هایی با پیکربندی مناسب، این امر به lit اجازه می‌دهد تا پشتیبانی راحت و منعطفی را برای ساخت‌های خارج از درخت (out-of-tree) فراهم سازد.
نتایج وضعیت آزمون (TEST STATUS RESULTS)
هر آزمون در نهایت یکی از هشت نتیجهٔ زیر را ایجاد می‌کند:
PASS
FLAKYPASS
FAIL
XPASS
FAIL
UNRESOLVED
UNSUPPORTED
TIMEOUT
آزمون‌های نامشخص (UNRESOLVED)، دارای پایان مهلت زمانی (TIMEOUT)، شکست‌خورده (FAIL) و به طور غیرمنتظره موفق‌شده (XPASS)، شکست محسوب می‌شوند.
بسته به قالب آزمون، ممکن است آزمون‌ها اطلاعات بیشتری دربارهٔ وضعیت خود تولید کنند (معمولاً فقط برای شکست‌ها). برای اطلاعات بیشتر بخش گزینه‌های خروجی (OUTPUT OPTIONS) را ببینید..SH "زیرساخت LIT (LIT INFRASTRUCTURE)"
این بخش به توصیف معماری آزمون lit برای کاربرانی می‌پردازد که علاقه‌مند به ایجاد یک پیاده‌سازی آزمون جدید با lit یا گسترش پیاده‌سازی‌های موجود هستند.
خود lit اساساً زیرساختی برای کشف و اجرای آزمون‌های دلخواه و ارائه‌ی یک واسط واحد و آسان برای این آزمون‌ها است. lit به خودی خود روش اجرای آزمون‌ها را نمی‌داند، بلکه این منطق توسط test suites تعریف می‌شود.
مجموعه‌های آزمون (TEST SUITES)
همان‌طور که در کشف آزمون (TEST DISCOVERY) توضیح داده شد، آزمون‌ها همواره درون یک test suite قرار دارند. مجموعه‌های آزمون قالبی برای تعریف فرمت آزمون‌های درون خود، منطق یافتن آن آزمون‌ها و هرگونه اطلاعات اضافی برای اجرای آزمون‌ها هستند.
ابزار lit مجموعه‌های آزمون را به‌عنوان دایرکتوری‌های حاوی فایل‌های lit.cfg یا lit.site.cfg شناسایی می‌کند (همچنین گزینهٔ --config-prefix را ببینید). مجموعه‌های آزمون در ابتدا با پیمایش بازگشتی سلسله‌مراتب دایرکتوری به سمت بالا برای تمام فایل‌های ورودی ارائه‌شده در خط فرمان کشف می‌شوند. می‌توانید از --show-suites برای نمایش مجموعه‌های آزمون کشف‌شده در هنگام راه‌اندازی استفاده کنید.
به‌محض کشف یک مجموعه آزمون، فایل پیکربندی آن بارگذاری می‌شود. فایل‌های پیکربندی خود ماژول‌های پایتون هستند که اجرا خواهند شد. هنگامی که فایل پیکربندی اجرا می‌شود، دو متغیر سراسری مهم از پیش تعریف شده‌اند:
lit_config
config
name [اجباری] نام مجموعه آزمون، جهت استفاده در گزارش‌ها و پیام‌های خطایابی.
test_format [اجباری] شیء فرمت آزمون که برای کشف و اجرای آزمون‌ها در مجموعه آزمون استفاده خواهد شد. این معمولاً یک فرمت آزمون توکار است که در ماژول lit.formats در دسترس است.
test_source_root مسیر سیستم‌فایل به ریشهٔ مجموعه آزمون. برای ساخت‌های خارج از دایرکتوری منبع (out-of-dir builds)، این دایرکتوری‌ای است که برای یافتن آزمون‌ها اسکن می‌شود.
test_exec_root برای ساخت‌های خارج از دایرکتوری منبع، مسیر ریشهٔ مجموعه آزمون درون دایرکتوری شیء (object directory) است. این مکانی است که آزمون‌ها در آن اجرا می‌شوند و فایل‌های خروجی موقت در آن قرار می‌گیرند.
environment یک دیکشنری نشان‌دهندهٔ محیطی که هنگام اجرای آزمون‌ها در مجموعه استفاده می‌شود.
standalone_tests هنگامی که true باشد، یک دایرکتوری را با آزمون‌هایی که انتظار می‌رود به‌صورت مستقل (standalone) اجرا شوند علامت‌گذاری می‌کند. فرآیند کشف آزمون برای آن دایرکتوری غیرفعال می‌شود. زمانی که این متغیر true است، lit.suffixes و lit.excludes باید خالی باشند.
suffixes برای فرمت‌های آزمون lit که دایرکتوری‌ها را برای آزمون‌ها اسکن می‌کنند، این متغیر فهرستی از پسوندها برای شناسایی فایل‌های آزمون است. استفاده‌شده توسط: ShTest.
substitutions برای فرمت‌های آزمون lit که متغیرها را در یک اسکریپت آزمون جایگزین می‌کنند، فهرست جایگزینی‌هایی است که باید انجام شوند. استفاده‌شده توسط: ShTest.
unsupported یک دایرکتوری پشتیبانی‌نشده را مشخص می‌کند؛ تمامی آزمون‌های درون آن به‌عنوان پشتیبانی‌نشده گزارش خواهند شد. استفاده‌شده توسط: ShTest.
parent پیکربندی والد؛ این شیء پیکربندی برای دایرکتوری حاوی مجموعه آزمون یا None است.
root پیکربندی ریشه. این بالاترین پیکربندی lit در پروژه است.
pipefail به‌طور معمول آزمونی که از پایپ شل (pipe) استفاده می‌کند، در صورت شکست هر یک از دستورهای درون پایپ با شکست مواجه می‌شود. در صورتی که این رفتار مطلوب نباشد، تنظیم این متغیر روی false باعث می‌شود آزمون تنها زمانی با شکست مواجه شود که آخرین دستور در پایپ شکست بخورد.
available_features مجموعه‌ای از ویژگی‌ها که می‌توان در دستورالعمل‌های XFAIL، REQUIRES و UNSUPPORTED استفاده کرد.
کشف آزمون (TEST DISCOVERY)
پس از تعیین محل مجموعه‌های آزمون، lit به‌صورت بازگشتی دایرکتوری منبع را (بر اساس test_source_root) برای یافتن آزمون‌ها پیمایش می‌کند. هنگامی که lit وارد یک زیردایرکتوری می‌شود، ابتدا بررسی می‌کند که آیا یک مجموعه آزمون تودرتو در آن دایرکتوری تعریف شده است یا خیر. در این صورت، آن مجموعه آزمون را به‌صورت بازگشتی بارگذاری می‌کند؛ در غیر این صورت، یک پیکربندی آزمون محلی برای آن دایرکتوری نمونه‌سازی می‌کند (بخش فایل‌های پیکربندی محلی (LOCAL CONFIGURATION FILES) را ببینید).
آزمون‌ها بر اساس مجموعه آزمونی که در آن قرار دارند و مسیر نسبی درون آن مجموعه شناسایی می‌شوند. توجه داشته باشید که مسیر نسبی ممکن است به یک فایل واقعی روی دیسک اشاره نکند؛ برخی از فرمت‌های آزمون (مانند GoogleTest) «آزمون‌های مجازی» ("virtual tests") را تعریف می‌کنند که دارای مسیری هستند که هم شامل مسیر فایل آزمون واقعی و هم یک زیرمسیر برای شناسایی آزمون مجازی است.
فایل‌های پیکربندی محلی (LOCAL CONFIGURATION FILES)
هنگامی که lit زیردایرکتوری‌ای را در یک مجموعه آزمون بارگذاری می‌کند، با کلون کردن پیکربندی دایرکتوری والد، یک پیکربندی آزمون محلی ایجاد می‌کند --- ریشهٔ این زنجیرهٔ پیکربندی همواره یک مجموعه آزمون خواهد بود. پس از کلون شدن پیکربندی آزمون، lit وجود فایل lit.local.cfg را در زیردایرکتوری بررسی می‌کند. در صورت وجود، این فایل بارگذاری می‌شود و می‌تواند برای اختصاصی‌سازی پیکربندی برای هر دایرکتوری مجزا استفاده شود. این امکان می‌تواند برای تعریف زیردایرکتوری‌هایی از آزمون‌های اختیاری، یا تغییر سایر پارامترهای پیکربندی --- برای مثال تغییر فرمت آزمون، یا پسوندهایی که فایل‌های آزمون را مشخص می‌کنند --- استفاده شود.
جایگزینی‌ها (SUBSTITUTIONS)
ابزار lit امکان جایگزینی الگوها را درون دستورهای RUN فراهم می‌کند. همچنین مجموعهٔ پایه‌ای زیر از جایگزینی‌ها را ارائه می‌دهد که در TestRunner.py تعریف شده‌اند:
| ماکرو (Macro) | جایگزینی (Substitution) |
| %s | مسیر منبع (مسیر فایلی که در حال حاضر اجرا می‌شود) |
| %S | دایرکتوری منبع (دایرکتوری فایلی که در حال حاضر اجرا می‌شود) |
| %p | مشابه %S |
| %{pathsep} | جداساز مسیر |
| %{fs-src-root} | مؤلفهٔ ریشه از مسیرهای سیستم‌فایل که به مخزن LLVM اشاره دارند |
| %{fs-tmp-root} | مؤلفهٔ ریشه از مسیرهای سیستم‌فایل که به دایرکتوری موقت آزمون اشاره دارند |
| %{fs-sep} | جداساز مسیر سیستم‌فایل |
| %t | مسیری یکتا برای آزمون (که ممکن است برای ایجاد فایل‌ها یا دایرکتوری‌ها استفاده شود) |
| %basename_t | آخرین مؤلفهٔ مسیر %t بدون پسوند .tmp (منسوخ‌شده، به‌جای آن از %{t:stem} استفاده کنید) |
| %% | % |
| %/s | همان %s اما \ با / جایگزین شده است |
| %/S | همان %S اما \ با / جایگزین شده است |
| %/p | همان %p اما \ با / جایگزین شده است |
| %/t | همان %t اما \ با / جایگزین شده است |
| %{s:basename} | آخرین مؤلفهٔ مسیر %s |
| %{t:stem} | آخرین مؤلفهٔ مسیر %t بدون پسوند .tmp (نام مستعار برای %basename_t) |
| %{s:real} | همان %s پس از باز کردن تمام پیوندهای نمادین و درایوهای جایگزین |
| %{S:real} | همان %S پس از باز کردن تمام پیوندهای نمادین و درایوهای جایگزین |
| %{p:real} | همان %p پس از باز کردن تمام پیوندهای نمادین و درایوهای جایگزین |
| %{t:real} | همان %t پس از باز کردن تمام پیوندهای نمادین و درایوهای جایگزین |
| %{/s:real} | همان %/s پس از باز کردن تمام پیوندهای نمادین و درایوهای جایگزین |
| %{/S:real} | همان %/S پس از باز کردن تمام پیوندهای نمادین و درایوهای جایگزین |
| %{/p:real} | همان %/p پس از باز کردن تمام پیوندهای نمادین و درایوهای جایگزین |
| %{/t:real} | همان %/t پس از باز کردن تمام پیوندهای نمادین و درایوهای جایگزین |
| %{/s:regex_replacement} | همان %/s اما برای استفاده در جایگزینیِ دستور s@@@ در sed اسکیپ شده است |
| %{/S:regex_replacement} | همان %/S اما برای استفاده در جایگزینیِ دستور s@@@ در sed اسکیپ شده است |
| %{/p:regex_replacement} | همان %/p اما برای استفاده در جایگزینیِ دستور s@@@ در sed اسکیپ شده است |
| %{/t:regex_replacement} | همان %/t اما برای استفاده در جایگزینیِ دستور s@@@ در sed اسکیپ شده است |
| %:s | در ویندوز، همان %/s اما اگر : نویسهٔ دوم باشد حذف می‌شود. در غیر این صورت، همان %s با حذف یک / ابتدایی. |
| %:S | در ویندوز، همان %/S اما اگر : نویسهٔ دوم باشد حذف می‌شود. در غیر این صورت، همان %S با حذف یک / ابتدایی. |
| %:p | در ویندوز، همان %/p اما اگر : نویسهٔ دوم باشد حذف می‌شود. در غیر این صورت، همان %p با حذف یک / ابتدایی. |
| %:t | در ویندوز، همان %/t اما اگر : نویسهٔ دوم باشد حذف می‌شود. در غیر این صورت، همان %t با حذف یک / ابتدایی. |
| %{readfile:<filename>} | فایل مشخص‌شده را می‌خواند. |
جایگزینی‌های دیگری نیز ارائه می‌شوند که اشکال متفاوتی از این مجموعهٔ پایه هستند و الگوهای جایگزینی بیشتری می‌توانند توسط هر ماژول آزمون تعریف شوند. بخش فایل‌های پیکربندی محلی (LOCAL CONFIGURATION FILES) ماژول‌ها را ببینید.
اطلاعات دقیق‌تر دربارهٔ جایگزینی‌ها را می‌توان در راهنمای زیرساخت آزمون LLVM <> یافت..SS قالب خروجی اجرای آزمون (TEST RUN OUTPUT FORMAT)
خروجی lit برای یک اجرای آزمون، هم در حالت خلاصه و هم در حالت پرگو (verbose) از طرح‌واره (schema) زیر پیروی می‌کند (اگرچه در حالت خلاصه هیچ خط PASS نشان داده نخواهد شد). این طرح‌واره به‌گونه‌ای انتخاب شده است که تجزیه قابل‌اعتماد آن توسط ماشین (به‌عنوان مثال در استخراج گزارش‌های buildbot) و تولید آن توسط سایر ابزارها نسبتاً آسان باشد.
انتظار می‌رود نتیجه هر آزمون در خطی ظاهر شود که با الگوی زیر مطابقت دارد:
<result code>: <test name> (<progress info>)
که در آن <result-code> یک نتیجه استاندارد آزمون مانند PASS، FAIL، XFAIL، XPASS، UNRESOLVED یا UNSUPPORTED است. کدهای نتیجه کارایی مانند IMPROVED و REGRESSED نیز مجاز هستند.
فیلد <test name> می‌تواند شامل هر رشته دلخواهی بدون نویسه خط جدید (newline) باشد.
فیلد <progress info> می‌تواند برای گزارش اطلاعات پیشرفت مانند (1/300) استفاده شود یا خالی باشد، اما حتی در صورت خالی بودن نیز پرانتزها الزامی هستند.
اگر به یک آزمون اجازه تلاش مجدد داده شده باشد (یادداشت ALLOW_RETRIES: را ببینید) و برای موفقیت به بیش از یک تلاش نیاز داشته باشد، فیلد <progress info> با این اطلاعات بسط می‌یابد:
, <num_attempts_made> of <max_allowed_attempts> attempts
هر نتیجه آزمون ممکن است شامل اطلاعات گزارش تکمیلی (چندخطی) در قالب زیر باشد:
<log delineator> TEST '(<test name>)' <trailing delineator> ... log message ... <log delineator>
که در آن <test name> باید نام یک آزمون گزارش‌شده پیشین باشد، <log delineator> رشته‌ای از نویسه‌های "*" به طول حداقل چهار نویسه است (طول توصیه‌شده ۲۰ است)، و <trailing delineator> یک رشته دلخواه (تجزیه‌نشده) است.
در ادامه نمونه‌ای از خروجی اجرای آزمون شامل چهار آزمون A، B، C و D، و یک پیام گزارش برای آزمون ناموفق C آمده است:
PASS: A (1 of 4) PASS: B (2 of 4) FAIL: C (3 of 4) ******************** TEST 'C' FAILED ******************** Test 'C' failed as a result of exit code 1. ******************** PASS: D (4 of 4)
ویژگی‌های پیش‌فرض (DEFAULT FEATURES)
برای راحتی کار، lit به‌طور خودکار available_features را برای برخی موارد استفاده رایج اضافه می‌کند.
ابزار lit یک ویژگی بر اساس سیستم‌عامل میزبان ساخت اضافه می‌کند، به‌عنوان مثال: system-darwin، system-linux و غیره. lit همچنین به‌طور خودکار یک ویژگی بر اساس معماری فعلی می‌افزاید، برای نمونه target-x86_64، target-aarch64 و غیره.
هنگام ساخت با سانایتایزرهای فعال (sanitizers)، lit به‌طور خودکار نام کوتاه سانایتایزر را اضافه می‌کند، برای مثال: asan، tsan و غیره.
برای مشاهده فهرست کامل ویژگی‌هایی که می‌توان اضافه کرد، llvm/utils/lit/lit/llvm/config.py را ببینید.
آزمون‌های نمونه LIT (LIT EXAMPLE TESTS)
توزیع lit شامل چندین پیاده‌سازی نمونه از مجموعه‌های آزمون در دایرکتوری ExampleTests است.
همچنین ببینید (SEE ALSO)
valgrind(1)
نویسندگان (AUTHORS)
نگه‌داری‌شده توسط تیم LLVM (https://llvm.org).
کپی‌رایت و تکثیر (COPYRIGHT)
2003-2026, LLVM Project
| 2026-07-15 | 22 |