BATS(1) Bash Automated Testing System BATS(1)

bats - سامانه خودکار اجرای آزمونهای بش (Bash Automated Testing System)

bats [گزینه‌ها] آزمون‌ها
bats [-h | -v]

آزمون‌ها مسیر یک فایل آزمون Bats، یا مسیر پوشه‌ای شامل فایل‌های آزمون Bats (با پسوند ".bats") است.

Bats یک چارچوب آزمون سازگار با TAP برای Bash است. این ابزار روشی ساده برای بررسی اینکه برنامه‌های یونیکسی که می‌نویسید مطابق انتظار رفتار می‌کنند، فراهم می‌سازد.

یک فایل آزمون Bats یک اسکریپت Bash با ساختار نحوی ویژه برای تعریف موارد آزمون (test cases) است. در پشت صحنه، هر مورد آزمون صرفاً یک تابع به همراه یک توضیح است.

موارد آزمون از دستورات استاندارد شل تشکیل شده‌اند. Bats هنگام اجرای موارد آزمون از گزینه errexit (set -e) در Bash استفاده می‌کند. اگر تمام دستورات موجود در مورد آزمون با کد وضعیت 0 (موفقیت) پایان یابند، آزمون پذیرفته می‌شود. بدین ترتیب، هر خط از کد یک گزاره شرطی (assertion) برای درستی عملکرد است.

برای اطلاعات بیشتر در مورد نوشتن آزمون‌های Bats، به bats(7) مراجعه کنید.

برای اجرای آزمون‌های خود، مفسر bats را با مسیر یک فایل آزمون فراخوانی کنید. موارد آزمون موجود در فایل به‌صورت متوالی و در محیط ایزوله اجرا می‌شوند. اگر تمام موارد آزمون با موفقیت سپری شوند، bats با کد وضعیت 0 خارج می‌شود. در صورت وجود هرگونه شکست یا خطا، bats با کد وضعیت 1 خارج خواهد شد.

شما می‌توانید مفسر bats را با چندین آرگومان فایل آزمون، یا با مسیر پوشه‌ای حاوی چندین فایل .bats فراخوانی کنید. Bats هر فایل آزمون را به‌طور جداگانه اجرا کرده و نتایج را تجمیع می‌نماید. در صورت شکست هر یک از موارد آزمون، bats با کد وضعیت 1 خارج می‌شود.

سازوکارهای متعددی برای فیلتر کردن آزمون‌های اجرایی وجود دارد:

  • --filter <regex> برای فیلتر بر اساس نام آزمون
  • --filter-status <status> برای فیلتر بر اساس وضعیت آزمون در آخرین اجرا
  • --filter-tags <tag-list> برای فیلتر بر اساس برچسب‌های آزمون

برچسب‌ها می‌توانند برای فیلتر دقیق آزمون‌های اجرایی از طریق گزینه --filter-tags استفاده شوند. این گزینه فهرستی از برچسب‌ها را که با کاما از هم جدا شده‌اند می‌پذیرد. تنها آزمون‌هایی اجرا خواهند شد که با تمامی این برچسب‌ها مطابقت داشته باشند. برای نمونه، bats --filter-tags a,b,c آزمون‌های دارای برچسب‌های a,b,c را اجرا می‌کند، اما آزمون‌هایی را که فاقد یک یا چند مورد از این برچسب‌ها باشند اجرا نخواهد کرد.

علاوه بر این، می‌توانید با bats --filter-tags a,!b,c برچسب‌های منفی مشخص کنید؛ در این صورت به‌دلیل وجود b، آزمون‌های دارای برچسب‌های a,b,c انتخاب نمی‌شوند، اما آزمون‌های دارای a,c انتخاب خواهند شد. به‌بیان دقیق‌تر، --filter-tags یک عطف منطقی (AND) است.

برای امکان‌پذیر ساختن پرس‌وجوهای پیچیده‌تر، می‌توانید چندین بار از گزینه --filter-tags استفاده کنید. یک آزمون در صورتی اجرا می‌شود که با دست‌کم یکی از آن‌ها مطابقت داشته باشد. این یعنی چند گزینه --filter-tags یک فصل منطقی (OR) تشکیل می‌دهند.

پرس‌وجوی --filter-tags a,!b --filter-tags b,c را می‌توان چنین ترجمه کرد: تنها آزمون‌هایی را اجرا کن که (دارای برچسب a باشند و برچسب b را نداشته باشند) یا (دارای هر دو برچسب b و c باشند).

یک فهرست برچسب خالی با آزمون‌های بدون برچسب مطابقت دارد.

  • --abort: توقف اجرای مجموعه آزمون در اولین شکست آزمون
  • --allow-empty-suite: خروج با کد ۰ (به‌جای کد پیش‌فرض ۱) در صورتی که هیچ آزمونی یافت نشود.
  • -c, --count: شمارش تعداد موارد آزمون بدون اجرای آزمون‌ها
  • --code-quote-style <style>: یک رشته دوکاراکتری از جداکننده‌های نقل‌قول کد، یا custom که نیازمند تنظیم متغیرهای $BATS_BEGIN_CODE_QUOTE و $BATS_END_CODE_QUOTE است. همچنین می‌تواند از طریق $BATS_CODE_QUOTE_STYLE تنظیم شود.
  • --line-reference-format نحوه نمایش ارجاعات فایل/خط (مثلاً در ردپای پشته) را کنترل می‌کند:
  • comma_line (پیش‌فرض): a.bats, line 1
  • colon: a.bats:1
  • uri: file:///tests/a.bats:1
  • custom: با تعریف تابع سفارشی bats_format_file_line_reference_custom با پارامترهای filename و line و ذخیره از طریق printf -v "$output"
  • --errexit: فعال‌سازی errexit (set -e) برای دستورات اجراشده در run
  • -f, --filter <regex>: فیلتر کردن موارد آزمون بر اساس نام‌های منطبق با عبارت باقاعده
  • -F, --formatter <type>: تغییر قالب‌بندی‌کننده خروجی: pretty (پیش‌فرض)، tap (پیش‌فرض بدون ترمینال)، tap13، junit، یا /<مسیر مطلق به قالب‌بندی‌کننده>
  • --filter-status <status>: تنها اجرای آزمون‌هایی با وضعیت مشخص در آخرین اجرای کامل‌شده (بدون فشردن کلیدهای میانبر CTRL+C/SIGINT). مقادیر معتبر status عبارتند از: failed - اجرای آزمون‌هایی که شکست خورده‌اند یا در آخرین اجرا حضور نداشتند؛ missed - اجرای آزمون‌هایی که در آخرین اجرا حضور نداشتند
  • --filter-tags <comma-separated-tag-list>: تنها اجرای آزمون‌هایی که با تمام برچسب‌های موجود در فهرست مطابقت دارند (&&). می‌توانید با قرار دادن ! در ابتدا، یک برچسب را نقیض کنید. مشخص کردن چندباره این فلگ امکان استفاده از OR منطقی (||) را فراهم می‌آورد: --filter-tags A,B --filter-tags A,!C با برچسب‌های (A && B) || (A && !C) مطابقت دارد.
  • --gather-test-outputs-in <directory>: جمع‌آوری خروجی آزمون‌های شکست‌خورده و موفق به‌صورت فایل در پوشه مشخص‌شده
  • -h, --help: نمایش این پیام راهنما
  • -j, --jobs <jobs>: تعداد کارهای موازی (نیازمند GNU parallel است)
  • --negative-filter <regex>: تنها اجرای آزمون‌هایی که با عبارت باقاعده مطابقت ندارند
  • --no-tempdir-cleanup: نگه‌داشتن پوشه موقت خروجی آزمون‌ها
  • --no-parallelize-across-files: اجرای متوالی فایل‌های آزمون به‌جای اجرای موازی آن‌ها (نیازمند --jobs > 1)
  • --no-parallelize-within-files: اجرای متوالی آزمون‌های درون فایل‌ها به‌جای اجرای موازی آن‌ها (نیازمند --jobs > 1)
  • --parallel-binary-name <name>: نام فایل باینری پردازش موازی
  • --report-formatter <type>: جابجایی بین گزارش‌دهنده‌ها (گزینه‌های یکسان با --formatter)
  • -o, --output <dir>: پوشه برای نوشتن فایل‌های گزارش
  • -p, --pretty: فرم کوتاه برای "--formatter pretty";
  • --print-output-on-failure: چاپ خودکار مقدار $output در آزمون‌های شکست‌خورده
  • -r, --recursive: شامل کردن آزمون‌های موجود در زیرپوشه‌ها
  • --show-output-of-passing-tests: چاپ خروجی آزمون‌های موفق
  • -t, --tap: فرم کوتاه برای "--formatter tap";
  • -T, --timing: افزودن اطلاعات زمان‌بندی به آزمون‌ها
  • -x, --trace: چاپ دستورات آزمون هنگام اجرا (مانند set -x)
  • --verbose-run: چاپ پیش‌فرض $output توسط run
  • -v, --version: نمایش شماره نسخه

هنگامی که Bats را از یک ترمینال اجرا می‌کنید، خروجی با اجرای هر آزمون نمایش داده می‌شود؛ در صورت قبولی آزمون یک علامت تیک در کنار نام آن، و در صورت شکست یک علامت "X" نمایش داده می‌شود.

$ bats addition.bats
 ✓ addition using bc
 ✓ addition using dc
2 tests, 0 failures

اگر Bats به یک ترمینال متصل نباشد -- به‌بیان دیگر، اگر آن را از یک سیستم یکپارچه‌سازی مداوم (CI) اجرا کنید یا خروجی آن را به یک فایل هدایت نمایید -- نتایج در قالب TAP که برای انسان خوانا و برای ماشین قابل پردازش است نمایش داده می‌شوند. شما می‌توانید با فراخوانی Bats با گزینه --tap خروجی ترمینال را نیز به قالب TAP وادار کنید.

$ bats --tap addition.bats
1..2
ok 1 addition using bc
ok 2 addition using dc

مفسر bats در صورتی که تمام موارد آزمون موفق باشند با مقدار 0 و در صورتی که یک یا چند مورد آزمون شکست بخورند با مقدار 1 خارج می‌شود.

ویکی Bats: https://github.com/bats-core/bats-core/wiki

bash(1), bats(7)

(c) 2017-2022 bats-core organization
(c) 2011-2016 Sam Stephenson

نرم‌افزار Bats تحت شرایط مجوزی با سبک MIT منتشر شده است.

July 2026 bats-core