آموزش Postman برای تست API؛ از درخواست اول تا Collection قابل‌تکرار

برای آزمودن یک API لازم نیست از همان ابتدا سراغ پروژه واقعی، توکن محرمانه یا درخواست تغییردهنده بروید. با یک درخواست عمومی و بی‌خطر می‌توانید فرق بین «درخواست ارسال شد»، «پاسخ را دیدم» و «رفتار مورد انتظار را آزمودم» را یاد بگیرید. در این راهنما از Postman Echo استفاده می‌کنیم، نتیجه را در یک Collection نگه می‌داریم و با متغیر، درخواست را قابل‌تکرار می‌کنیم. تمرین پایانی یک گزارش کوتاه می‌سازد که هم برای یادگیری و هم برای تحویل یک نمونه‌کار فنی مفید است.

اگر API خودتان را با Python ساخته‌اید، راهنمای ساخت API با FastAPI و SQLAlchemy مسیر سمت سرور را توضیح می‌دهد. این مقاله بر سمت مصرف‌کننده و آزمون درخواست تمرکز دارد. فرض می‌کنیم به Postman دسترسی دارید و یک درخواست HTTP ساده را می‌شناسید. ظاهر دقیق منوها ممکن است با نسخه برنامه تغییر کند، اما مفاهیم درخواست، پاسخ، Collection و Environment ثابت می‌مانند.

آزمون چه چیزی را باید ثابت کند؟

یک پاسخ ۲۰۰ فقط می‌گوید سرور برای آن درخواست موفقیت HTTP گزارش کرده است؛ لزوماً ثابت نمی‌کند داده درست، فیلتر اعمال‌شده یا قرارداد پاسخ رعایت شده است. برای هر درخواست، پیش از کلیک روی Send سه چیز را بنویسید: ورودی، نتیجه مورد انتظار و شاهدی که در پاسخ بررسی می‌کنید. در مثال ما ورودی یک پارامتر query با نام topic و مقدار portfolio است؛ انتظار داریم پاسخ JSON همان مقدار را در بخش مربوط به آرگومان‌ها بازتاب دهد. این انتظار مشخص از جمله مبهم «API کار می‌کند» بسیار بهتر است.

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

گام اول: یک درخواست GET بی‌خطر بفرستید

در Postman یک HTTP Request تازه باز کنید، روش را روی GET بگذارید و نشانی https://postman-echo.com/get?topic=portfolio را وارد کنید. سپس Send را بزنید. در بخش پاسخ، وضعیت HTTP، نوع محتوا و بدنه JSON را جداگانه ببینید. باید مقدار portfolio را در آرگومان‌های بازتاب‌یافته پیدا کنید. این درخواست نمونه پیش از تدوین مقاله به همان endpoint ارسال و بازتاب مقدار topic بررسی شد؛ این یک آزمون محدود برای نمونه است و ادعای تجربه از محیط کاربری Postman یا تضمین دسترسی همیشگی سرویس نیست.

راهنمای شروع رسمی Postman نیز نخستین درخواست را با Echo نشان می‌دهد. اگر URL را بدون query بفرستید، پاسخ ممکن است معتبر باشد اما شاهد موردنظر ما را نداشته باشد. پس تفاوت موفقیت انتقال HTTP و درست‌بودن داده بازگشتی را در گزارش خود حفظ کنید. اگر پاسخ JSON نیست، نخست نشانی، روش و خطای نمایش‌داده‌شده را بازبینی کنید؛ پیش از نتیجه‌گیری درباره API، مطمئن شوید درخواست به endpoint موردنظر رسیده است.

پارامتر را از کجا تغییر دهم؟

می‌توانید query را در URL ببینید یا از بخش Params در Postman کلید topic و مقدار portfolio را وارد کنید. دو ورودی هم‌نام را ناخواسته کنار هم نفرستید؛ URL نهایی را پیش از Send بررسی کنید. برای تمرین دوم، مقدار را به یک واژه آزمایشی دیگر تغییر دهید و ببینید فقط همان مقدار در پاسخ تغییر می‌کند. این مشاهده به شما یاد می‌دهد کدام قسمت پاسخ به کدام ورودی وابسته است. هیچ داده شخصی یا محرمانه‌ای برای این تمرین لازم نیست.

وقتی پاسخ با انتظار فرق دارد

نخست وضعیت و بدنه را ثبت کنید، سپس روش GET، نشانی کامل، نام پارامتر و مقدار آن را مقایسه کنید. خطای تایپی در نام کلید، فاصله اضافه یا انتخاب Environment اشتباه می‌تواند همان‌قدر مؤثر باشد که مشکل سرور. اگر از مرورگر نتیجه‌ای متفاوت می‌بینید، درخواست‌های واقعی را با هم مقایسه کنید؛ هدر، query و آدرس نهایی ممکن است یکسان نباشند. تغییر هم‌زمان چند گزینه تشخیص را دشوار می‌کند.

گام دوم: درخواست را در Collection ذخیره کنید

درخواست موفق را با نامی روشن مانند «Echo - query topic» در Collection تازه‌ای برای تمرین API ذخیره کنید. Collection فهرستی از درخواست‌های ذخیره‌شده و قابل‌سازمان‌دهی است؛ مستند رسمی Collection کاربرد آن برای گروه‌بندی درخواست‌ها و ساخت مجموعه آزمون را شرح می‌دهد. نام درخواست باید ورودی یا هدف را روشن کند، نه فقط «Test 1». اگر بعدها درخواست خطای عمدی یا حالت بدون پارامتر اضافه کردید، آن‌ها را با نام مستقل نگه دارید تا نتیجه هرکدام قابل‌فهم باشد.

ذخیره درخواست با ذخیره پاسخ یکی نیست. برای بازتولید مسئله باید روش، URL، پارامتر، هدر لازم و انتظار آزمون را حفظ کنید. پاسخ ممکن است در زمان‌های مختلف تغییر کند؛ آنچه باید پایدار بماند قرارداد مورد انتظار و روش آزمون است. در توضیح Collection بنویسید چرا آن را ساخته‌اید، کدام endpoint عمومی است و چه چیزی نباید داخل آن قرار گیرد، مانند کلید خصوصی. این توضیح کوتاه از اشتراک‌گذاری تصادفی داده حساس جلوگیری می‌کند.

گام سوم: URL را با متغیر بازاستفاده کنید

اگر چند درخواست به یک میزبان می‌روند، تکرار نشانی پایه در همه آن‌ها خطا را زیاد می‌کند. در Collection یا Environment یک متغیر به نام base_url با مقدار https://postman-echo.com بسازید و نشانی درخواست را به {{base_url}}/get?topic=portfolio تغییر دهید. قبل از Send، مقدار حل‌شده را در Postman بررسی کنید. راهنمای رسمی متغیرها همین الگو و تفاوت محدوده‌ها را توضیح می‌دهد.

برای این تمرین، متغیر Collection کافی است؛ اگر قرار است همان درخواست را میان محیط توسعه و آزمایش جابه‌جا کنید، Environment انتخاب مناسب‌تری است. نام متغیر را یکسان نگه دارید و با انتخاب محیط، مقدار آن را عوض کنید. مراقب باشید مقدار محلی و مقدار مشترک یک چیز نیستند: مستند Postman می‌گوید مقدار محلی به‌طور پیش‌فرض فقط در نمونه خودتان استفاده می‌شود، در حالی که اشتراک‌گذاری مقدار می‌تواند آن را به فضای ابری تیم ببرد. پیش از اشتراک‌گذاری Collection یا Environment، مقدارهای حساس و سطح دسترسی را بازبینی کنید.

متغیر حل نمی‌شود؛ چه چیزی را بررسی کنم؟

املای base_url در تعریف و نشانی درخواست باید دقیقاً یکی باشد. فعال‌بودن Environment درست و مقدار محلی متغیر را ببینید. اگر متغیر با همین نام در چند محدوده تعریف شده، مقدار محدوده نزدیک‌تر ممکن است استفاده شود؛ خروجی درخواست نهایی را ملاک قرار دهید، نه تصور خود از مقدار. برای تمرین عمومی ما هیچ کلید یا توکن لازم نیست، بنابراین اگر درخواست ناگهان هدر Authorization گرفت، تنظیمات inherited را هم بررسی کنید و پیش از ارسال به میزبان عمومی حذفش کنید.

گام چهارم: از مشاهده پاسخ به یک شرط آزمون برسید

در بخش Scripts و زبانه Post-response می‌توانید با Snippetهای خود Postman شرطی برای وضعیت ۲۰۰ اضافه کنید و نتیجه را در Test Results ببینید. مستند رسمی آزمون پاسخ محل افزودن اسکریپت و نمایش نتیجه را توضیح می‌دهد. این مقاله بلوک کد آماده‌ای که در محیط شما اجرا نشده ارائه نمی‌کند؛ از Snippet رسمی در رابط برنامه استفاده کنید و سپس شرط را با یک پاسخ موفق و یک انتظار عمداً نادرست بیازمایید تا مطمئن شوید شکست هم دیده می‌شود.

شرط وضعیت تنها شروع کار است. برای سناریوی Echo، مقدار بازتاب‌یافته topic را نیز با مقدار ورودی مورد انتظار مقایسه کنید. اگر هنوز اسکریپت‌نویسی در Postman را نمی‌دانید، ابتدا این مقایسه را به‌صورت دستی در گزارش ثبت کنید و سپس طبق مثال‌های رسمی یک assertion داده‌ای بیفزایید. آزمونی که هر پاسخ ۲۰۰ را موفق بداند، حتی وقتی مقدار اشتباه است، ارزش تشخیصی کمی دارد. نام شرط باید رفتار را توصیف کند؛ مثلاً «پارامتر topic بازتاب داده شد» از «Test passed» آموزنده‌تر است.

گام پنجم: Collection را دوباره اجرا و نتیجه را ثبت کنید

درخواست ذخیره‌شده را یک بار از Collection به‌صورت دستی دوباره بفرستید و ببینید بدون ساختن درخواست تازه همان رفتار تکرار می‌شود. اگر چند درخواست یا چند شرط دارید، Collection Runner می‌تواند درخواست‌های Collection را به‌ترتیب انتخابی اجرا کند و نتیجه آزمون‌ها را کنار هم نشان دهد. برای این تمرین یک اجرای محلی و محدود کافی است؛ نیازی به زمان‌بندی ابری یا ارسال داده پروژه به سرویس دیگری ندارید.

گزارش تمرین را کوتاه نگه دارید: تاریخ، روش و endpoint، مقدار پارامتر، وضعیت HTTP، مقدار بازتاب‌یافته، نتیجه شرط و هر خطایی که دیدید. اگر بار دوم نتیجه متفاوت شد، فقط از روی یک اجرای سبز یا قرمز نتیجه قطعی درباره پایداری سرویس نگیرید. شبکه، تغییر داده و تفاوت Environment را بررسی کنید. اگر درخواست به API خودتان مربوط است، ورودی‌ها و پاسخ‌ها را پیش از اشتراک‌گذاری از داده شخصی و توکن پاک کنید.

چک‌لیست تحویل یک آزمون API قابل‌تکرار

1. هدف آزمون را به یک جمله قابل‌سنجش تبدیل کنید؛ مثلاً بازتاب پارامتر مشخص.
2. روش، endpoint و ورودی را پیش از ارسال یادداشت کنید.
3. درخواست اول را بدون کلید خصوصی و با داده آزمایشی بی‌خطر بفرستید.
4. وضعیت HTTP و مقدار مورد انتظار را جداگانه بررسی کنید.
5. درخواست را با نام روشن داخل Collection ذخیره کنید.
6. نشانی پایه را با متغیر مناسب بازاستفاده کنید و مقدار حل‌شده را بازبینی کنید.
7. از Snippet رسمی برای یک شرط ساده استفاده کنید و عمداً شکست آن را هم آزمایش کنید.
8. Collection را دوباره اجرا کنید و تفاوت اجرای اول و دوم را ثبت کنید.
9. قبل از اشتراک‌گذاری، هدرها، متغیرها، مقدارهای مشترک و اسکرین‌شات‌ها را از داده حساس پاک کنید.
10. گزارش را با ورودی، انتظار، نتیجه و محدودیت آزمون به هم‌تیمی تحویل دهید.

برای توسعه‌دهنده بک‌اند، همین Collection کوچک می‌تواند نقطه شروع گفت‌وگو درباره قرارداد API باشد. اگر endpoint پروژه شما خطاهای ۴۰۰ یا ۴۰۴ دارد، بعداً سناریوهای منفی را هم جدا اضافه کنید؛ اما آن‌ها را با درخواست عمومی Echo قاطی نکنید. هر آزمون باید هدف، داده و معیار موفقیت خاص خود را داشته باشد. این نظم باعث می‌شود تغییر در API را به‌جای حدس، با شواهد پیگیری کنید.

پرسش‌های متداول

آیا بدون API key می‌توانم Postman را یاد بگیرم؟

بله. برای تمرین اولیه از endpoint عمومی Echo و درخواست GET استفاده کنید. ورود کلید واقعی در تمرین عمومی نه لازم است و نه مطلوب.

چرا پاسخ ۲۰۰ به‌تنهایی کافی نیست؟

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

Collection با Environment چه فرقی دارد؟

Collection درخواست‌ها و آزمون‌های مرتبط را گروه‌بندی می‌کند؛ Environment مقدار متغیرهای وابسته به بافت اجرا را نگه می‌دارد. درخواست یکسان می‌تواند با انتخاب محیط دیگر، مقدار پایه متفاوتی بگیرد.

آیا مقدار API key را در Collection مشترک بگذارم؟

خیر، بدون بررسی محدوده و اشتراک‌گذاری مقدار چنین کاری نکنید. مقدار محلی یا سازوکار امن مناسب تیم را به‌کار ببرید و قبل از اشتراک‌گذاری، درخواست و خروجی را بازبینی کنید.

جمع‌بندی و گام بعدی

یادگیری Postman از فرستادن یک درخواست شروع می‌شود اما در همان‌جا تمام نمی‌شود. با Echo یک ورودی و خروجی واقعی می‌بینید، در Collection درخواست را حفظ می‌کنید، با متغیر از تکرار نشانی جلوگیری می‌کنید و با شرط آزمون می‌فهمید کدام رفتار باید در اجرای بعدی هم برقرار بماند. همین مسیر کوچک، پایه‌ای برای آزمون API پروژه خودتان است؛ فقط هنگام انتقال از سرویس عمومی به داده واقعی، امنیت و محدوده دسترسی را جدی‌تر کنید.

امروز یک درخواست GET بی‌خطر به Postman Echo بسازید، آن را در Collection ذخیره کنید و نتیجه پاسخ و آزمون را با تاریخ و ورودی مشخص ثبت کنید.