دایره المعارف تست

مشخصات جامع محیط اجرای آزمون.

زمینه

زبان Bazel BUILD شامل قوانینی است که می توان از آنها برای تعریف برنامه های تست خودکار در بسیاری از زبان ها استفاده کرد.

تست ها با استفاده از bazel test اجرا می شوند.

کاربران همچنین می توانند باینری های آزمایشی را مستقیماً اجرا کنند. این امر مجاز است اما تأیید نمی شود، زیرا چنین فراخوانی به دستورات توضیح داده شده در زیر پایبند نیست.

تست ها باید هرمتیک باشند: یعنی آنها باید فقط به منابعی دسترسی داشته باشند که به آنها وابستگی اعلام شده دارند. اگر آزمایش ها به درستی هرمتیک نباشند، نتایج قابل تکرار تاریخی نمی دهند. این می‌تواند یک مشکل مهم برای یافتن مقصر (تعیین اینکه کدام تغییر یک آزمایش را شکست داده)، انتشار قابلیت ممیزی مهندسی، و جداسازی منابع آزمایش‌ها (فریم‌ورک‌های تست خودکار نباید سرور DDOS باشند، زیرا برخی از آزمایش‌ها اتفاقاً با آن صحبت می‌کنند).

هدف، واقعگرایانه

هدف این صفحه ایجاد رسمی محیط زمان اجرا و رفتار مورد انتظار تست های Bazel است. همچنین الزاماتی را بر دونده آزمایشی و سیستم ساخت تحمیل می کند.

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

این صفحه در نظر گرفته شده است که هم هنجاری و هم معتبر باشد. اگر این مشخصات و رفتار اجرا شده دونده آزمایشی مخالف باشد، مشخصات اولویت دارد.

مشخصات پیشنهادی

کلمات کلیدی "باید"، "نباید"، "الزامی"، "باید"، "نباید"، "باید"، "نباید"، "توصیه شده"، "ممکن است" و "اختیاری" باید تفسیر شوند. همانطور که در IETF RFC 2119 توضیح داده شده است.

هدف از آزمون ها

هدف از تست های Bazel تایید برخی از ویژگی های فایل های منبع بررسی شده در مخزن است. (در این صفحه، «فایل‌های منبع» شامل داده‌های آزمایش، خروجی‌های طلایی، و هر چیز دیگری است که تحت کنترل نسخه نگهداری می‌شود.) یکی از کاربران آزمایشی می‌نویسد تا ثابت کند که انتظار دارد ثابت بماند. سایر کاربران آزمایش را بعداً انجام می دهند تا بررسی کنند که آیا تغییرناپذیر شکسته شده است یا خیر. اگر آزمایش به متغیرهای دیگری غیر از فایل‌های منبع (غیر هرمتیک) بستگی داشته باشد، مقدار آن کاهش می‌یابد، زیرا کاربران بعدی نمی‌توانند مطمئن شوند که تغییرات آنها در زمانی که تست متوقف می‌شود اشتباه باشد.

بنابراین نتیجه یک آزمایش باید فقط به موارد زیر بستگی داشته باشد:

• فایل های منبعی که آزمون به آنها وابستگی اعلام شده دارد
• محصولات سیستم ساخت که تست وابستگی اعلام شده به آنها دارد
• منابعی که رفتار آنها توسط دونده آزمون تضمین شده است که ثابت بماند

در حال حاضر چنین رفتاری اجرا نمی شود. با این حال، دوندگان آزمون این حق را برای خود محفوظ می‌دارند که در آینده چنین اعمالی را اضافه کنند.

نقش سیستم ساخت

قوانین تست مشابه قوانین باینری هستند که هر کدام باید یک برنامه اجرایی ارائه دهند. برای برخی از زبان ها، این یک برنامه خرد است که یک مهار خاص زبان را با کد آزمون ترکیب می کند. قوانین تست باید خروجی های دیگری نیز تولید کنند. علاوه بر فایل اجرایی آزمایشی اولیه، اجراکننده آزمایش به مانیفست فایل‌های اجرا نیاز دارد، فایل‌های ورودی که باید در زمان اجرا در دسترس آزمون قرار گیرند، و ممکن است به اطلاعاتی در مورد نوع، اندازه و برچسب‌های آزمایش نیاز داشته باشد.

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

نقش دونده آزمون

از نظر اجراکننده تست، هر تست یک برنامه است که می توان آن را با execve() فراخوانی کرد. ممکن است راه های دیگری برای اجرای آزمایش ها وجود داشته باشد. برای مثال، یک IDE ممکن است اجازه اجرای آزمایش‌های جاوا را در فرآیند بدهد. با این حال، نتیجه اجرای آزمون به عنوان یک فرآیند مستقل باید معتبر در نظر گرفته شود. اگر یک فرآیند آزمایشی به پایان برسد و به طور معمول با یک کد خروجی صفر خاتمه یابد، آزمایش با موفقیت انجام شده است. هر نتیجه دیگری شکست تست تلقی می شود. به طور خاص، نوشتن هر یک از رشته‌ها PASS یا FAIL در stdout هیچ اهمیتی برای اجراکننده آزمایش ندارد.

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

به کل هدف آزمون (نه روش‌ها یا آزمایش‌های فردی) زمان محدودی برای اجرا تا تکمیل داده می‌شود. محدودیت زمانی برای یک آزمون بر اساس ویژگی timeout آن مطابق جدول زیر است:

تست‌هایی که به‌صراحت زمان‌بندی را مشخص نمی‌کنند، بر اساس size آزمون به شرح زیر است:

یک تست "بزرگ" بدون تنظیم زمان صریح 900 ثانیه برای اجرا اختصاص داده می شود. آزمون "متوسط" با تایم اوت "کوتاه" 60 ثانیه اختصاص داده می شود.

بر خلاف timeout ، size علاوه بر این، حداکثر استفاده مفروض از منابع دیگر (مانند RAM) را هنگام اجرای آزمایش به صورت محلی تعیین می کند، همانطور که در تعاریف رایج توضیح داده شده است.

همه ترکیب‌های برچسب‌های size و timeout قانونی قانونی هستند، بنابراین ممکن است یک آزمایش "بسیار زیاد" دارای بازه زمانی "کوتاه" اعلام شود. احتمالاً کارهای بسیار وحشتناکی را خیلی سریع انجام می دهد.

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

زمانی که به صورت دستی تحت شرایطی که به کندی شناخته شده است اجرا می شود، می توان با پرچم --test_timeout لغو شد. مقادیر --test_timeout بر حسب ثانیه هستند. به عنوان مثال، --test_timeout=120 زمان تست را روی دو دقیقه تنظیم می کند.

همچنین یک حد پایین توصیه شده برای وقفه های آزمایشی به شرح زیر وجود دارد:

به عنوان مثال، اگر یک آزمون "متوسط" در 5.5 ثانیه به پایان می رسد، تنظیم timeout = "short" یا size = "small" را در نظر بگیرید. با استفاده از گزینه خط فرمان --test_verbose_timeout_warnings ، تست هایی که اندازه مشخص شده آنها خیلی بزرگ است را نشان می دهد.

اندازه‌های تست و زمان‌بندی در فایل BUILD طبق مشخصات اینجا مشخص شده‌اند. اگر نامشخص باشد، اندازه آزمون به طور پیش‌فرض روی «متوسط» خواهد بود.

اگر فرآیند اصلی یک آزمون خارج شود، اما برخی از فرزندان آن هنوز در حال اجرا هستند، دونده آزمون باید اجرا را کامل در نظر بگیرد و بر اساس کد خروجی مشاهده شده از فرآیند اصلی، آن را به عنوان موفقیت یا شکست حساب کند. دونده آزمایشی ممکن است هر فرآیند سرگردان را از بین ببرد. آزمایش ها نباید به این شکل فرآیندها را نشت کنند.

تست شاردینگ

تست ها را می توان از طریق تقسیم بندی تست موازی کرد. برای فعال کردن اشتراک گذاری آزمایشی، --test_sharding_strategy و shard_count را ببینید. وقتی شاردینگ فعال است، اجرای آزمایشی یک بار در هر خرده راه اندازی می شود. متغیر محیطی TEST_TOTAL_SHARDS تعداد خرده‌ها است و TEST_SHARD_INDEX شاخص خرده‌ای است که از 0 شروع می‌شود. دونده‌ها از این اطلاعات برای انتخاب آزمایش‌هایی استفاده می‌کنند - برای مثال، با استفاده از استراتژی دورگرد. همه آزمایش‌کنندگان از Sharding پشتیبانی نمی‌کنند. اگر یک رانر از اشتراک گذاری پشتیبانی می کند، باید آخرین تاریخ تغییر فایل مشخص شده توسط TEST_SHARD_STATUS_FILE را ایجاد یا به روز کند. در غیر این صورت، Bazel فرض می کند که از شاردینگ پشتیبانی نمی کند و دونده های اضافی را راه اندازی نخواهد کرد.

شرایط اولیه

هنگام اجرای یک آزمون، دونده آزمون باید شرایط اولیه خاصی را ایجاد کند.

اجراکننده آزمون باید هر تست را با مسیر آزمایشی قابل اجرا در argv[0] فراخوانی کند. این مسیر باید نسبی و زیر دایرکتوری فعلی تست باشد (که در درخت runfiles، در زیر مشاهده کنید). اجراکننده تست نباید هیچ آرگومان دیگری را به یک تست ارسال کند، مگر اینکه کاربر صریحاً آن را درخواست کند.

بلوک محیط اولیه باید به صورت زیر تشکیل شود:

محیط ممکن است حاوی ورودی های اضافی باشد. آزمایش‌ها نباید به وجود، نبود یا مقدار متغیرهای محیطی که در بالا ذکر نشده است بستگی داشته باشند.

دایرکتوری کاری اولیه باید $TEST_SRCDIR/$TEST_WORKSPACE باشد.

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

توصیف‌گر فایل 0 ( stdin ) باید برای خواندن باز باشد، اما آنچه به آن پیوست شده است نامشخص است. تست ها نباید از روی آن خوانده شوند. توصیف‌کننده‌های فایل 1 ( stdout ) و 2 ( stderr ) باید برای نوشتن باز باشند، اما آنچه که به آن پیوست شده‌اند مشخص نشده است. این می تواند یک ترمینال، یک لوله، یک فایل معمولی یا هر چیز دیگری باشد که می توان کاراکترها را روی آن نوشت. آنها ممکن است یک ورودی را در جدول فایل باز به اشتراک بگذارند (به این معنی که نمی توانند به طور مستقل جستجو کنند). آزمون ها نباید هیچ توصیفگر فایل باز دیگری را به ارث ببرند.

umask اولیه باید 022 یا 027 باشد.

هیچ زنگ هشدار یا تایمر فاصله ای نباید معلق باشد.

ماسک اولیه سیگنال های مسدود شده باید خالی باشد. همه سیگنال ها باید روی عملکرد پیش فرض خود تنظیم شوند.

محدودیت های منابع اولیه، چه نرم و چه سخت، باید به صورت زیر تنظیم شوند:

زمان‌های فرآیند اولیه (برگردانده شده توسط times() ) و استفاده از منابع (به عنوان بازگشت توسط getrusage() ) مشخص نشده است.

خط مشی زمانبندی اولیه و اولویت مشخص نشده است.

نقش سیستم میزبان

علاوه بر جنبه‌های بافت کاربر تحت کنترل مستقیم اجرای آزمایشی، سیستم عاملی که آزمایش‌ها بر روی آن اجرا می‌شوند باید ویژگی‌های خاصی را برآورده کند تا اجرای آزمایشی معتبر باشد.

سیستم فایل

دایرکتوری ریشه مشاهده شده توسط آزمایش ممکن است دایرکتوری ریشه واقعی باشد یا نباشد.

/proc باید نصب شود.

همه ابزارهای ساخت باید در مسیرهای مطلق در زیر /usr که توسط یک نصب محلی استفاده می شود وجود داشته باشند.

مسیرهایی که با /home شروع می شوند ممکن است در دسترس نباشند. تست ها نباید به چنین مسیرهایی دسترسی داشته باشند.

/tmp باید قابل نوشتن باشد، اما تست ها باید از استفاده از این مسیرها اجتناب کنند.

آزمایش ها نباید فرض کنند که هیچ مسیر ثابتی برای استفاده انحصاری آنها در دسترس است.

آزمایش‌ها نباید فرض کنند که atime برای هر فایل سیستم نصب شده فعال است.

کاربران و گروه ها

کاربران root، nobody و unittest باید وجود داشته باشند. گروه های root، nobody و eng باید وجود داشته باشند.

تست ها باید به عنوان یک کاربر غیر ریشه اجرا شوند. شناسه های کاربر واقعی و موثر باید برابر باشند. همینطور برای شناسه های گروهی فراتر از این، شناسه کاربر فعلی، شناسه گروه، نام کاربری و نام گروه مشخص نشده است. مجموعه شناسه های گروه تکمیلی نامشخص است.

شناسه کاربر فعلی و شناسه گروه باید نام‌های متناظری داشته باشند که می‌توانند با getpwuid() و getgrgid() بازیابی شوند. این ممکن است برای شناسه های گروه تکمیلی صادق نباشد.

کاربر فعلی باید یک فهرست اصلی داشته باشد. ممکن است قابل نوشتن نباشد. آزمون ها نباید سعی کنند روی آن بنویسند.

شبکه سازی

نام میزبان نامشخص است. ممکن است حاوی نقطه باشد یا نباشد. حل کردن نام میزبان باید آدرس IP میزبان فعلی را بدهد. حل کردن برش نام میزبان پس از اولین نقطه نیز باید کار کند. نام میزبان localhost باید حل شود.

منابع دیگر

تست ها حداقل یک هسته CPU اعطا می کنند. سایرین ممکن است در دسترس باشند اما این تضمین نشده است. سایر جنبه های عملکردی این هسته مشخص نشده است. می توانید با افزودن برچسب "cpu:n" (که n عدد مثبت است) به یک قانون تست، رزرو را به تعداد بیشتری از هسته های CPU افزایش دهید. اگر دستگاهی دارای تعداد هسته‌های CPU کمتر از درخواستی باشد، Bazel همچنان آزمایش را اجرا می‌کند. اگر آزمایشی از اشتراک گذاری استفاده می کند، هر قطعه جداگانه تعداد هسته های CPU مشخص شده در اینجا را رزرو می کند.

تست ها ممکن است فرآیندهای فرعی ایجاد کنند، اما گروه ها یا جلسات را پردازش نمی کنند.

محدودیتی در تعداد فایل های ورودی که ممکن است یک آزمایش مصرف کند وجود دارد. این محدودیت ممکن است تغییر کند، اما در حال حاضر در محدوده ده‌ها هزار ورودی است.

زمان و تاریخ

زمان و تاریخ فعلی مشخص نشده است. منطقه زمانی سیستم مشخص نشده است.

X Windows ممکن است در دسترس باشد یا نباشد. تست هایی که به سرور X نیاز دارند باید Xvfb را شروع کنند.

تست تعامل با فایل سیستم

همه مسیرهای فایل مشخص شده در متغیرهای محیط آزمایشی به جایی در سیستم فایل محلی اشاره می کنند، مگر اینکه طور دیگری مشخص شده باشد.

آزمایش‌ها باید فایل‌ها را فقط در دایرکتوری‌های تعیین‌شده توسط $TEST_TMPDIR و $TEST_UNDECLARED_OUTPUTS_DIR (در صورت تنظیم) ایجاد کنند.

این دایرکتوری ها در ابتدا خالی خواهند بود.

آزمایش ها نباید سعی در حذف، chmod یا تغییر این دایرکتوری ها داشته باشند.

این دایرکتوری ها ممکن است یک پیوند نمادین باشند.

نوع سیستم فایل $TEST_TMPDIR/. نامشخص باقی مانده است.

آزمایش‌ها همچنین ممکن است فایل‌های .part را در $TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR تا فایل‌های خروجی اعلام‌نشده را حاشیه‌نویسی کنند.

در موارد نادر، ممکن است آزمایش مجبور شود فایل‌هایی را در /tmp ایجاد کند. برای مثال، محدودیت‌های طول مسیر برای سوکت‌های دامنه یونیکس معمولاً نیاز به ایجاد سوکت در زیر /tmp دارند. Bazel قادر به ردیابی چنین فایل هایی نخواهد بود. خود آزمون باید مراقب باشد که هرمتیک باشد، از مسیرهای منحصربه‌فرد برای جلوگیری از برخورد با سایر آزمایش‌ها و فرآیندهای غیرآزمایشی همزمان استفاده کند و فایل‌هایی را که در /tmp ایجاد می‌کند پاک کند.

برخی از چارچوب‌های آزمایشی محبوب، مانند JUnit4 TemporaryFolder یا Go TempDir ، راه‌های خاص خود را برای ایجاد یک فهرست موقت تحت /tmp دارند. این چارچوب‌های آزمایشی شامل عملکردی هستند که فایل‌ها را در /tmp پاک می‌کند، بنابراین می‌توانید از آنها استفاده کنید حتی اگر آنها فایل‌هایی خارج از TEST_TMPDIR ایجاد کنند.

تست ها باید از طریق مکانیزم runfiles یا سایر بخش های محیط اجرا که به طور خاص برای در دسترس قرار دادن فایل های ورودی در نظر گرفته شده اند، به ورودی ها دسترسی داشته باشند.

تست‌ها نباید به خروجی‌های دیگر سیستم ساخت در مسیرهای استنتاج شده از محل فایل اجرایی خودشان دسترسی داشته باشند.

مشخص نیست که درخت runfiles حاوی فایل‌های معمولی، پیوندهای نمادین یا ترکیبی است. درخت runfiles ممکن است حاوی پیوندهای نمادین به دایرکتوری ها باشد. آزمایش ها باید از استفاده از مسیرهای حاوی اجزای .. در درخت runfiles اجتناب کنند.

هیچ دایرکتوری، فایل یا پیوند نمادی در درخت runfiles (از جمله مسیرهایی که از پیوندهای نمادین عبور می کنند) نباید قابل نوشتن باشد. (به این نتیجه می رسد که دایرکتوری کاری اولیه نباید قابل نوشتن باشد.) آزمایش ها نباید فرض کنند که هیچ بخشی از فایل های اجرا قابل نوشتن است یا متعلق به کاربر فعلی است (مثلاً chmod و chgrp ممکن است شکست بخورند).

درخت runfiles (از جمله مسیرهایی که از پیوندهای نمادین عبور می کنند) نباید در طول اجرای آزمایش تغییر کند. دایرکتوری های والد و مانت های سیستم فایل نباید به هیچ وجه تغییر کنند که بر نتیجه حل یک مسیر در درخت runfiles تأثیر بگذارد.

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

کنوانسیون ها را تگ کنید

برخی از برچسب ها در قوانین آزمون معنای خاصی دارند. همچنین به دایره المعارف ساخت Bazel در ویژگی tags مراجعه کنید.

ران فایل ها

در ادامه، فرض کنید یک قانون *_binary() با برچسب //foo/bar:unittest ، با یک وابستگی زمان اجرا به قانون با برچسب //deps/server:server وجود دارد.

محل

دایرکتوری runfiles برای هدف //foo/bar:unittest دایرکتوری $(WORKSPACE)/$(BINDIR)/foo/bar/unittest.runfiles است. این مسیر به عنوان runfiles_dir می شود.

وابستگی ها

دایرکتوری runfiles به عنوان یک وابستگی زمان کامپایل از قانون *_binary() اعلام می شود. خود دایرکتوری runfiles به مجموعه ای از فایل های BUILD بستگی دارد که بر قانون *_binary() یا هر یک از وابستگی های زمان کامپایل یا زمان اجرا آن تأثیر می گذارد. تغییر فایل های منبع بر ساختار دایرکتوری runfiles تأثیری نمی گذارد و بنابراین باعث ایجاد هیچ گونه بازسازی نمی شود.

فهرست

دایرکتوری runfiles شامل موارد زیر است:

• پیوندهای نمادین به وابستگی‌های زمان اجرا : هر OutputFile و CommandRule که یک وابستگی زمان اجرا از قانون *_binary() است با یک پیوند نمادین در فهرست فایل‌ها نشان داده می‌شود. نام پیوند $(WORKSPACE)/package_name/rule_name است. به عنوان مثال، پیوند نماد سرور $(WORKSPACE)/deps/server/server و مسیر کامل $(WORKSPACE)/foo/bar/unittest.runfiles/$(WORKSPACE)/deps/server/server بود. . مقصد symlink، OutputFileName() OutputFile یا CommandRule است که به صورت یک مسیر مطلق بیان می شود. بنابراین، مقصد پیوند نمادین ممکن است $(WORKSPACE)/linux-dbg/deps/server/42/server باشد.
• پیوندهای نمادین به فایل‌های فرعی : برای هر *_binary() Z که وابستگی زمان اجرا به *_binary() C است، یک پیوند دوم در فهرست فایل‌های run در C به فایل‌های run از Z وجود دارد. نام پیوند نمادین است. $(WORKSPACE)/package_name/rule_name.runfiles . هدف سیملینک دایرکتوری runfiles است. به عنوان مثال، همه زیربرنامه ها یک پوشه runfiles مشترک دارند.