.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BATS" "1" "July 2026" "bats-core" "Bash Automated Testing System"
.SH "نام (NAME)"
bats \- سامانه خودکار اجرای آزمونهای بش (Bash Automated Testing System)
.SH "خلاصه دستور (SYNOPSIS)"
\fBbats\fR [\fIگزینه‌ها\fR] \fIآزمون‌ها\fR
.br
\fBbats\fR [\fB\-h\fR | \fB\-v\fR]
.P
\fIآزمون‌ها\fR مسیر یک فایل آزمون Bats، یا مسیر پوشه‌ای شامل فایل‌های آزمون Bats (با پسوند "\.bats") است\.
.SH "توضیحات (DESCRIPTION)"
Bats یک چارچوب آزمون سازگار با TAP برای Bash است\. این ابزار روشی ساده برای بررسی اینکه برنامه‌های یونیکسی که می‌نویسید مطابق انتظار رفتار می‌کنند، فراهم می‌سازد\.
.P
یک فایل آزمون Bats یک اسکریپت Bash با ساختار نحوی ویژه برای تعریف موارد آزمون (test cases) است\. در پشت صحنه، هر مورد آزمون صرفاً یک تابع به همراه یک توضیح است\.
.P
موارد آزمون از دستورات استاندارد شل تشکیل شده‌اند\. Bats هنگام اجرای موارد آزمون از گزینه
.B errexit
(\fBset \-e\fR)
در Bash استفاده می‌کند\. اگر تمام دستورات موجود در مورد آزمون با کد وضعیت
.B 0
(موفقیت) پایان یابند، آزمون پذیرفته می‌شود\. بدین ترتیب، هر خط از کد یک گزاره شرطی (assertion) برای درستی عملکرد است\.
.P
برای اطلاعات بیشتر در مورد نوشتن آزمون‌های Bats، به
.BR bats (7)
مراجعه کنید\.
.SH "اجرای آزمون‌ها (RUNNING TESTS)"
برای اجرای آزمون‌های خود، مفسر
.B bats
را با مسیر یک فایل آزمون فراخوانی کنید\. موارد آزمون موجود در فایل به‌صورت متوالی و در محیط ایزوله اجرا می‌شوند\. اگر تمام موارد آزمون با موفقیت سپری شوند،
.B bats
با کد وضعیت
.B 0
خارج می‌شود\. در صورت وجود هرگونه شکست یا خطا،
.B bats
با کد وضعیت
.B 1
خارج خواهد شد\.
.P
شما می‌توانید مفسر
.B bats
را با چندین آرگومان فایل آزمون، یا با مسیر پوشه‌ای حاوی چندین فایل
.B \.bats
فراخوانی کنید\. Bats هر فایل آزمون را به‌طور جداگانه اجرا کرده و نتایج را تجمیع می‌نماید\. در صورت شکست هر یک از موارد آزمون،
.B bats
با کد وضعیت
.B 1
خارج می‌شود\.
.SH "فیلتر کردن آزمون‌ها (FILTERING TESTS)"
سازوکارهای متعددی برای فیلتر کردن آزمون‌های اجرایی وجود دارد:
.IP "\(bu" 4
\fB\-\-filter <regex>\fR برای فیلتر بر اساس نام آزمون
.IP "\(bu" 4
\fB\-\-filter\-status <status>\fR برای فیلتر بر اساس وضعیت آزمون در آخرین اجرا
.IP "\(bu" 4
\fB\-\-filter\-tags <tag\-list>\fR برای فیلتر بر اساس برچسب‌های آزمون
.IP "" 0
.SH "\-\-FILTER\-TAGS <var>TAG\-LIST</var>"
برچسب‌ها می‌توانند برای فیلتر دقیق آزمون‌های اجرایی از طریق گزینه \fB\-\-filter\-tags\fR استفاده شوند\. این گزینه فهرستی از برچسب‌ها را که با کاما از هم جدا شده‌اند می‌پذیرد\. تنها آزمون‌هایی اجرا خواهند شد که با تمامی این برچسب‌ها مطابقت داشته باشند\. برای نمونه، \fBbats \-\-filter\-tags a,b,c\fR آزمون‌های دارای برچسب‌های \fBa,b,c\fR را اجرا می‌کند، اما آزمون‌هایی را که فاقد یک یا چند مورد از این برچسب‌ها باشند اجرا نخواهد کرد\.
.P
علاوه بر این، می‌توانید با \fBbats \-\-filter\-tags a,!b,c\fR برچسب‌های منفی مشخص کنید؛ در این صورت به‌دلیل وجود \fBb\fR، آزمون‌های دارای برچسب‌های \fBa,b,c\fR انتخاب نمی‌شوند، اما آزمون‌های دارای \fBa,c\fR انتخاب خواهند شد\. به‌بیان دقیق‌تر، \fB\-\-filter\-tags\fR یک عطف منطقی (AND) است\.
.P
برای امکان‌پذیر ساختن پرس‌وجوهای پیچیده‌تر، می‌توانید چندین بار از گزینه \fB\-\-filter\-tags\fR استفاده کنید\. یک آزمون در صورتی اجرا می‌شود که با دست‌کم یکی از آن‌ها مطابقت داشته باشد\. این یعنی چند گزینه \fB\-\-filter\-tags\fR یک فصل منطقی (OR) تشکیل می‌دهند\.
.P
پرس‌وجوی \fB\-\-filter\-tags a,!b \-\-filter\-tags b,c\fR را می‌توان چنین ترجمه کرد: تنها آزمون‌هایی را اجرا کن که (دارای برچسب a باشند و برچسب b را نداشته باشند) یا (دارای هر دو برچسب b و c باشند)\.
.P
یک فهرست برچسب خالی با آزمون‌های بدون برچسب مطابقت دارد\.
.SH "گزینه‌ها (OPTIONS)"
.IP "\(bu" 4
\fB\-\-abort\fR: توقف اجرای مجموعه آزمون در اولین شکست آزمون
.IP "\(bu" 4
\fB\-\-allow\-empty\-suite\fR: خروج با کد ۰ (به‌جای کد پیش‌فرض ۱) در صورتی که هیچ آزمونی یافت نشود\.
.IP "\(bu" 4
\fB\-c\fR, \fB\-\-count\fR: شمارش تعداد موارد آزمون بدون اجرای آزمون‌ها
.IP "\(bu" 4
\fB\-\-code\-quote\-style <style>\fR: یک رشته دوکاراکتری از جداکننده‌های نقل‌قول کد، یا \fBcustom\fR که نیازمند تنظیم متغیرهای \fB$BATS_BEGIN_CODE_QUOTE\fR و \fB$BATS_END_CODE_QUOTE\fR است\. همچنین می‌تواند از طریق \fB$BATS_CODE_QUOTE_STYLE\fR تنظیم شود\.
.IP "\(bu" 4
\fB\-\-line\-reference\-format\fR نحوه نمایش ارجاعات فایل/خط (مثلاً در ردپای پشته) را کنترل می‌کند:
.IP "\(bu" 4
comma_line (پیش‌فرض): a\.bats, line 1
.IP "\(bu" 4
colon: a\.bats:1
.IP "\(bu" 4
uri: file:///tests/a\.bats:1
.IP "\(bu" 4
custom: با تعریف تابع سفارشی bats_format_file_line_reference_custom با پارامترهای \fIfilename\fR و \fIline\fR و ذخیره از طریق \fBprintf \-v "$output"\fR
.IP "" 0
.IP "\(bu" 4
\fB\-\-errexit\fR: فعال‌سازی errexit (\fBset \-e\fR) برای دستورات اجراشده در \fBrun\fR
.IP "\(bu" 4
\fB\-f\fR, \fB\-\-filter <regex>\fR: فیلتر کردن موارد آزمون بر اساس نام‌های منطبق با عبارت باقاعده
.IP "\(bu" 4
\fB\-F\fR, \fB\-\-formatter <type>\fR: تغییر قالب‌بندی‌کننده خروجی: pretty (پیش‌فرض)، tap (پیش‌فرض بدون ترمینال)، tap13، junit، یا \fB/<مسیر مطلق به قالب‌بندی‌کننده>\fR
.IP "\(bu" 4
\fB\-\-filter\-status <status>\fR: تنها اجرای آزمون‌هایی با وضعیت مشخص در آخرین اجرای کامل‌شده (بدون فشردن کلیدهای میانبر CTRL+C/SIGINT)\. مقادیر معتبر \fIstatus\fR عبارتند از: failed \- اجرای آزمون‌هایی که شکست خورده‌اند یا در آخرین اجرا حضور نداشتند؛ missed \- اجرای آزمون‌هایی که در آخرین اجرا حضور نداشتند
.IP "\(bu" 4
\fB\-\-filter\-tags <comma\-separated\-tag\-list>\fR: تنها اجرای آزمون‌هایی که با تمام برچسب‌های موجود در فهرست مطابقت دارند (\fB&&\fR)\. می‌توانید با قرار دادن \fB!\fR در ابتدا، یک برچسب را نقیض کنید\. مشخص کردن چندباره این فلگ امکان استفاده از OR منطقی (\fB||\fR) را فراهم می‌آورد: \fB\-\-filter\-tags A,B \-\-filter\-tags A,!C\fR با برچسب‌های \fB(A && B) || (A && !C)\fR مطابقت دارد\.
.IP "\(bu" 4
\fB\-\-gather\-test\-outputs\-in <directory>\fR: جمع‌آوری خروجی آزمون‌های شکست‌خورده \fIو\fR موفق به‌صورت فایل در پوشه مشخص‌شده
.IP "\(bu" 4
\fB\-h\fR, \fB\-\-help\fR: نمایش این پیام راهنما
.IP "\(bu" 4
\fB\-j\fR, \fB\-\-jobs <jobs>\fR: تعداد کارهای موازی (نیازمند GNU parallel است)
.IP "\(bu" 4
\fB\-\-negative\-filter <regex>\fR: تنها اجرای آزمون‌هایی که با عبارت باقاعده مطابقت ندارند
.IP "\(bu" 4
\fB\-\-no\-tempdir\-cleanup\fR: نگه‌داشتن پوشه موقت خروجی آزمون‌ها
.IP "\(bu" 4
\fB\-\-no\-parallelize\-across\-files\fR: اجرای متوالی فایل‌های آزمون به‌جای اجرای موازی آن‌ها (نیازمند \-\-jobs > 1)
.IP "\(bu" 4
\fB\-\-no\-parallelize\-within\-files\fR: اجرای متوالی آزمون‌های درون فایل‌ها به‌جای اجرای موازی آن‌ها (نیازمند \-\-jobs > 1)
.IP "\(bu" 4
\fB\-\-parallel\-binary\-name <name>\fR: نام فایل باینری پردازش موازی
.IP "\(bu" 4
\fB\-\-report\-formatter <type>\fR: جابجایی بین گزارش‌دهنده‌ها (گزینه‌های یکسان با \-\-formatter)
.IP "\(bu" 4
\fB\-o\fR, \fB\-\-output <dir>\fR: پوشه برای نوشتن فایل‌های گزارش
.IP "\(bu" 4
\fB\-p\fR, \fB\-\-pretty\fR: فرم کوتاه برای "\-\-formatter pretty"
.IP "\(bu" 4
\fB\-\-print\-output\-on\-failure\fR: چاپ خودکار مقدار \fB$output\fR در آزمون‌های شکست‌خورده
.IP "\(bu" 4
\fB\-r\fR, \fB\-\-recursive\fR: شامل کردن آزمون‌های موجود در زیرپوشه‌ها
.IP "\(bu" 4
\fB\-\-show\-output\-of\-passing\-tests\fR: چاپ خروجی آزمون‌های موفق
.IP "\(bu" 4
\fB\-t\fR, \fB\-\-tap\fR: فرم کوتاه برای "\-\-formatter tap"
.IP "\(bu" 4
\fB\-T\fR, \fB\-\-timing\fR: افزودن اطلاعات زمان‌بندی به آزمون‌ها
.IP "\(bu" 4
\fB\-x\fR, \fB\-\-trace\fR: چاپ دستورات آزمون هنگام اجرا (مانند \fBset \-x\fR)
.IP "\(bu" 4
\fB\-\-verbose\-run\fR: چاپ پیش‌فرض \fB$output\fR توسط \fBrun\fR
.IP "\(bu" 4
\fB\-v\fR, \fB\-\-version\fR: نمایش شماره نسخه
.IP "" 0
.SH "خروجی (OUTPUT)"
هنگامی که Bats را از یک ترمینال اجرا می‌کنید، خروجی با اجرای هر آزمون نمایش داده می‌شود؛ در صورت قبولی آزمون یک علامت تیک در کنار نام آن، و در صورت شکست یک علامت "X" نمایش داده می‌شود\.
.IP "" 4
.nf
$ bats addition\.bats
 ✓ addition using bc
 ✓ addition using dc

2 tests, 0 failures
.fi
.IP "" 0
.P
اگر Bats به یک ترمینال متصل نباشد \-\- به‌بیان دیگر، اگر آن را از یک سیستم یکپارچه‌سازی مداوم (CI) اجرا کنید یا خروجی آن را به یک فایل هدایت نمایید \-\- نتایج در قالب TAP که برای انسان خوانا و برای ماشین قابل پردازش است نمایش داده می‌شوند\. شما می‌توانید با فراخوانی Bats با گزینه \fB\-\-tap\fR خروجی ترمینال را نیز به قالب TAP وادار کنید\.
.IP "" 4
.nf
$ bats \-\-tap addition\.bats
1\.\.2
ok 1 addition using bc
ok 2 addition using dc
.fi
.IP "" 0
.SH "وضعیت خروج (EXIT STATUS)"
مفسر
.B bats
در صورتی که تمام موارد آزمون موفق باشند با مقدار
.B 0
و در صورتی که یک یا چند مورد آزمون شکست بخورند با مقدار
.B 1
خارج می‌شود\.
.SH "همچنین ببینید (SEE ALSO)"
ویکی Bats: \fIhttps://github.com/bats-core/bats-core/wiki\fR
.P
\fBbash\fR(1), \fBbats\fR(7)
.SH "حق نشر (COPYRIGHT)"
(c) 2017\-2022 bats\-core organization
.br
(c) 2011\-2016 Sam Stephenson
.P
نرم‌افزار Bats تحت شرایط مجوزی با سبک MIT منتشر شده است\.