.\" Copyright (C) 2018  Free Software Foundation, Inc.
.\" You may distribute this file under the terms of the GNU Free
.\" Documentation License.
.Dd December 31, 2018
.Os GNU
.Dt DEJAGNU-REPORT-CARD 1 URM
.Sh "نام (NAME)"
.Nm dejagnu\ report\ card
.Nd خلاصه‌سازی نتایج حاصل از آزمون چندین ابزار
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm dejagnu\ report\ card
.Oo Ao Ar option Ac \*(Ba Ao Ar tool Ac \*(Ba Ao Ar file Ac Oc ...
.Sh "توضیحات (DESCRIPTION)"
دستور
.Nm
نتایج حاصل از آزمون ابزارهای متعدد را در قالب جدول نمایش می‌دهد.
جدول ایجادشده برای هر ابزار (و چنانچه چندین مرحله اجرا شده باشد، برای هر مرحله) تعداد آزمون‌های موفق (passed)، ناموفق (failed)، پشتیبانی‌نشده (unsupported)، حل‌نشده (unresolved) و آزموده‌نشده (untested) را فهرست می‌کند. آزمون‌هایی که انتظار شکست آن‌ها وجود دارد، در ستون‌هایی مجزا از آزمون‌هایی که انتظار قبولی آن‌ها می‌رود شمرده می‌شوند، اما شکست‌های «شناخته‌شده» (known) و شکست‌های «مورد انتظار» (expected) با یکدیگر خلاصه می‌شوند. اگر آزمونی هشدارها یا خطاهایی تولید کرده باشد، برچسب
.Ql !W!
یا
.Ql !E!
به انتهای خط مربوطه اضافه می‌شود.
.Pp
علاوه بر گزینه‌ها، فهرست آرگومان‌ها ممکن است شامل نام ابزارها یا فایل‌ها باشد. دستور
.Nm
ترجیح می‌دهد فایل‌های خلاصهٔ DejaGnu را بخواند و نام‌ها را بر همین اساس تفسیر می‌کند:
.Bl -tag -width ".Pa *.sum"
.It Pa *.sum
به همان صورت استفاده می‌شود.
.It Pa *.log
با همان ریشه به
.Pa *.sum
تبدیل می‌شود.
.It Pa *.
رشتهٔ
.Pa sum
برای انتخاب یک فایل خلاصه الصاق می‌شود. این پردازش برای راحتی هنگام استفاده از تکمیل نام فایل Readline در پوسته انجام می‌شود که تا نقطه را کامل می‌کند.
.It Pa *
به‌عنوان نام ابزار در نظر گرفته می‌شود؛ پسوند
.Pa .sum
به انتهای آن اضافه می‌شود.
.El
.Sh "گزینه‌ها (OPTIONS)"
.Bl -tag -width ".Fl v , -verbose"
.It Fl v , -verbose
خروجی‌های بیشتری را در توصیف عملکرد خودِ
.Nm
تولید می‌کند.
.El
.Sh "فایل‌ها (FILES)"
دستور
.Nm
خروجی خود را با خواندن فایل‌های خلاصه تولیدشده توسط DejaGnu و شمارش مقادیر «PASS»، «FAIL» و غیره تولید می‌کند.
.Pp
اگر هیچ نامی به‌عنوان آرگومان داده نشود، تمام فایل‌های منطبق بر
.Pa *.sum
در دایرکتوری جاری خوانده می‌شوند.
.Sh "مثال‌ها (EXAMPLES)"
.Ss نمونه‌ای ساده از مجموعه آزمون‌های خود DejaGnu
.Bd -literal
$ dejagnu report card
\             __________________________________________________
\            /    PASS   FAIL  ?PASS  ?FAIL  UNSUP  UNRES UNTEST
\            |--------------------------------------------------
\  launcher  |      52      0      0      0      0      0      0
libdejagnu  |       5      0      0      0      0      0      0
\   runtest  |     135      0      0      0      0      0      0
\            |--------------------------------------------------
\            |     192      0      0      0      0      0      0
\            \\__________________________________________________
.Ed
.Pp
سه ابزار با مجموع ۱۹۲ آزمون بررسی شدند که انتظار می‌رفت همگی موفق شوند. در این مثال، تمام آزمون‌ها با موفقیت سپری شدند، بنابراین سایر ستون‌ها صفر هستند. ستون‌های
.Ql ?PASS
و
.Ql ?FAIL
آزمون‌های شناخته‌شده یا مورد انتظاری را می‌شمارند که قرار بود با شکست مواجه شوند، اما یا به‌طور غیرمنتظره موفق شدند یا طبق انتظار شکست خوردند. سه ستون باقی‌مانده، نتایج استثنایی را برای آزمون‌های پشتیبانی‌نشده، آزمون‌های حل‌نشده و آزمون‌های ساختگی (stub) که صرفاً خود را آزمایش‌نشده اعلام می‌کنند، شمارش می‌کنند.
.Pp
.ne 16v
.Ss همان مثال پس از افزودن آزمون‌ها برای dejagnu-report-card
.Bd -literal
$ dejagnu report-card
\                    __________________________________________________
\                   /    PASS   FAIL  ?PASS  ?FAIL  UNSUP  UNRES UNTEST
\                   |--------------------------------------------------
\   launcher        |      52      0      0      0      0      0      0
\ libdejagnu        |       5      0      0      0      0      0      0
report-card / awk  |      36      0      0      0      0      0      0
report-card / sh   |      36      0      0      0      0      0      0
report-card / tcl  |      36      0      0      0      0      0      0
\    runtest        |     135      0      0      0      0      0      0
\                   |--------------------------------------------------
\              awk  |      36      0      0      0      0      0      0
\              sh   |      36      0      0      0      0      0      0
\              tcl  |      36      0      0      0      0      0      0
\                   |--------------------------------------------------
\                   |     300      0      0      0      0      0      0
\                   \\__________________________________________________
.Ed
.Pp
ابزار
.Ql report-card
اضافه شده است، با سه مرحله، یکی برای هر پیاده‌سازی. (پیاده‌سازی‌های shell و Tcl بعداً برای کاهش بار نگهداری در آینده کنار گذاشته شدند.) مانند قبل، تمام آزمون‌ها طبق انتظار با موفقیت سپری شدند. تفاوت جالب نسبت به مثال قبل، استفاده از قابلیت آزمون چندمرحله‌ای (multipass) در DejaGnu و اضافه شدن خطوط خلاصهٔ مجزا برای هر مرحله است. در این مثال، تنها ابزار
.Ql report-card
از آزمون چندمرحله‌ای استفاده می‌کند، بنابراین مجموع هر مرحله صرفاً تعداد آزمون‌های مربوط به
.Ql report-card
است، نه یک مجموع تفکیک‌شدهٔ جداگانه.
.Pp
همچنین توجه داشته باشید دستوری که برای فراخوانی
.Nm
استفاده شده در اینجا کمی متفاوت است. راه‌انداز
.Xr dejagnu 1
کلمات متعددی را که با خط تیره به یک آرگومان واحد متصل شده‌اند نیز می‌پذیرد. این قابلیت اجازه می‌دهد کلمات مجزا در نام یک دستور، در خط فرمان به جای یکدیگر با خط تیره یا فاصله از هم جدا شوند.
.Sh "همچنین ببینید (SEE ALSO)"
.Xr dejagnu 1
.Xr runtest 1
.Pp
مستندات کامل DejaGnu در قالب یک دفترچه راهنمای Texinfo نگهداری می‌شود. اگر برنامهٔ
.Nm info
به‌درستی روی سیستم شما نصب شده باشد، دستور
.Li info dejagnu
باید دسترسی به دفترچه راهنمای کامل را برای شما فراهم کند.
.Sh "نویسندگان (AUTHORS)"
.An Jacob Bachmeyer
.\".Sh BUGS
.\"  LocalWords:  Dt dejagnu URM Nm Ao Oo Oc DejaGnu Xr runtest DejaGnu's Bd Ql
.\"  LocalWords:  testsuite UNSUP UNRES UNTEST libdejagnu Readline Ss tcl awk
.\"  LocalWords:  ne multipass