تست REST API با Postman
تست REST API با Postman چگونه انجام میشود؟ بررسی عمیق Environment، Collection، Pre-request Script، Test Script، Newman و CI/CD Integration با آمار و اصطلاحات فنی.
اولین باری که با Postman کار کردم، فکر میکردم فقط یک ابزار ساده برای ارسال درخواستهای HTTP است. اما وقتی در یکی از پروژههایم با یک API پیچیده با ۴۰ endpoint و چند محیط (dev، staging، production) روبرو شدم، فهمیدم Postman بسیار بیشتر از یک کلاینت HTTP است. در آن پروژه، با استفاده از Environment Variables، Collection Runner و Pre-request Scripts، توانستیم تیم را از سردرگمی نجات دهیم و فرآیند تست را خودکار کنیم. در این مقاله، بر اساس تجربههای عملی و مطالعه مستندات رسمی Postman، نحوه تست حرفهای REST API با این ابزار را بررسی میکنم.
طبق گزارش Postman State of the API، بیش از ۲۰ میلیون توسعهدهنده از Postman استفاده میکنند و این ابزار در بیش از ۵۰۰,۰۰۰ شرکت فعال است. در ۲۰۲۶، Postman به یک پلتفرم کامل API تبدیل شده که شامل طراحی، تست، مستندسازی، مانیتورینگ و Mocking است. اگر با مفاهیم پایهای REST آشنا نیستید، پیشنهاد میکنم ابتدا REST API چیست و اصول طراحی REST API را مطالعه کنید.
چرا Postman برای تست API ضروری است؟
تست REST API، بخش جدانشدنی از فرآیند توسعه است. بدون تست، امکان تشخیص خطا در زمان توسعه وجود ندارد و API به احتمال زیاد در محیط تولید شکست میخورد. ابزارهای متعددی برای تست API وجود دارند: curl، Postman، Insomnia، Paw و... . اما Postman به دلیل سه ویژگی، در اکثر پروژهها انتخاب اول است: اول، رابط کاربری گرافیکی ساده و قدرتمند. دوم، امکانات جامع برای خودکارسازی تست. سوم، یکپارچگی با CI/CD و ابزارهای تیم.
تست REST API سه سطح دارد: تست دستی، تست خودکار و تست مانیتورینگ. Postman در هر سه سطح ابزار ارائه میدهد. برای تست دستی، رابط کاربری گرافیکی. برای تست خودکار، Test Scripts و Collection Runner. برای مانیتورینگ، Postman Monitors.
طبق مطالعهای که در پروژههای مختلف انجام شده، استفاده از Postman به عنوان ابزار اصلی تست REST API، به کاهش ۴۰ تا ۶۰ درصدی زمان تست دستی و کاهش ۷۰ درصدی خطاها در محیط تولید منجر میشود. این آمارها نشان میدهد که Postman یک سرمایهگذاری منطقی برای هر تیم توسعه است.
نصب و پیکربندی اولیه
Postman در سه نسخه ارائه میشود: Desktop App (Windows، macOS، Linux)، Web App و CLI (Newman). نسخه Desktop رایجترین است و برای اکثر کاربردها توصیه میشود. نصب آن از سایت رسمی postman.com انجام میشود و در عرض چند دقیقه تمام میشود.
بعد از نصب، سه کار اولیه توصیه میشود: اول، ساخت یک حساب کاربری برای همگامسازی Collectionها بین دستگاهها. دوم، پیکربندی Proxy در صورت نیاز (برای تست در محیطهای محدود). سوم، نصب افزونههای ضروری مثل Interceptor برای ضبط درخواستهای مرورگر.
نکات مهم درباره نصب: Postman به صورت پیشفرض از TLS 1.2 و بالاتر پشتیبانی میکند. اگر با APIهای داخلی با گواهی self-signed کار میکنید، باید تنظیمات SSL Verification را در Settings غیرفعال کنید. اما این کار را فقط در محیط dev انجام دهید، نه در production.
اگر با احراز هویت API آشنا نیستید، احراز هویت در REST API و JWT چیست را مطالعه کنید.
ساخت درخواستهای HTTP
ساخت یک درخواست HTTP در Postman ساده است: URL را وارد کنید، متد HTTP را انتخاب کنید، هدرها و بدنه را تنظیم کنید، و دکمه Send را بزنید. اما برای تست حرفهای، نکات مهمی وجود دارد.
انتخاب متد HTTP: در Postman، متدهای GET، POST، PUT، PATCH، DELETE، HEAD، OPTIONS و چند متد دیگر پشتیبانی میشوند. انتخاب متد درست، بخشی از طراحی صحیح API است. اگر با معنای متدها آشنا نیستید، REST از پایه تا طراحی حرفهای و آموزش REST API را بخوانید.
هدرها: هدرهای مهم شامل Content-Type (نوع بدنه درخواست)، Accept (نوع پاسخ مورد انتظار)، Authorization (توکن احراز هویت)، و هدرهای سفارشی API. در Postman، میتوانید هدرها را به صورت جداگانه در تب Headers تنظیم کنید یا از Presets استفاده کنید.
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-API-Version: 2
بدنه درخواست: برای متدهای POST، PUT و PATCH، معمولاً نیاز به بدنه دارید. Postman از چند فرمت پشتیبانی میکند: raw JSON، form-data، x-www-form-urlencoded، binary و GraphQL. برای APIهای REST مدرن، raw JSON رایجترین است.
پاسخ: بعد از ارسال درخواست، Postman پاسخ را در سه بخش نمایش میدهد: Body (بدنه پاسخ)، Cookies (کوکیها)، Headers (هدرهای پاسخ). همچنین زمان پاسخ (Response Time) و حجم پاسخ (Response Size) نمایش داده میشوند.
Environment و متغیرها
Environment و متغیرها یکی از قدرتمندترین امکانات Postman هستند که به مدیریت تفاوتهای محیطی کمک میکنند. بدون این ابزار، برای تست در محیطهای dev، staging و production، باید URLها، توکنها و سایر پارامترها را به صورت دستی تغییر دهید. با Environment، این کار خودکار میشود.
Postman از چند نوع متغیر پشتیبانی میکند:
| نوع متغیر | Scope | کاربرد |
|---|---|---|
| Global | همه Collectionها | متغیرهای عمومی |
| Environment | یک محیط | URL، توکن، کلیدها |
| Collection | یک Collection | متغیرهای خاص Collection |
| Local | یک درخواست | مقادیر موقت |
| Data | یک Run | دادههای تست از فایل |
نمونه تعریف متغیرهای محیطی:
base_url: https://api.example.com
api_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
api_version: v2
timeout: 30000
استفاده از متغیرها در درخواست:
GET {{base_url}}/{{api_version}}/users
Authorization: Bearer {{api_token}}
مزایای استفاده از Environment: اول، امکان تعویض سریع بین محیطها با یک کلیک. دوم، عدم نیاز به تغییر دستی URL و توکن در هر درخواست. سوم، امکان همکاری تیمی، چون هر عضو تیم میتواند Environment خودش را داشته باشد. چهارم، امکان به اشتراک گذاری Environment بدون افشای مقادیر حساس (با استفاده از Vault).
نکات امنیتی در Environment: هرگز توکنها و کلیدهای API را در Environment ذخیره نکنید و آن را به اشتراک بگذارید. به جای آن، از Postman Vault یا Initial Values استفاده کنید که فقط به صورت محلی نگهداری میشوند.
Collection و Organization
Collection در Postman، مجموعهای از درخواستهای مرتبط است که با یک ساختار سلسلهمراتبی سازماندهی میشوند. Collection به تیم اجازه میدهد درخواستها را به صورت منطقی گروهبندی کند و به اشتراک بگذارد.
ساختار پیشنهادی برای Collection: اول، بر اساس دامنه کسبوکار (مثل Users، Orders، Products). دوم، بر اساس نوع عملیات (مثل CRUD). سوم، بر اساس محیط (dev، staging، production). ساختار دو سطحی معمولاً بهترین تعادل را فراهم میکند: یک سطح برای دامنه و یک سطح برای عملیات.
📁 My API Collection
📁 Users
➡ GET /users
➡ POST /users
➡ GET /users/:id
➡ PUT /users/:id
➡ DELETE /users/:id
📁 Orders
➡ GET /orders
➡ POST /orders
نکات مهم درباره Collection: اول، از Folder برای گروهبندی منطقی استفاده کنید. دوم، به هر درخواست یک نام توصیفی بدهید. سوم، از متغیرها در URL و Headers استفاده کنید. چهارم، از Pre-request Scripts و Test Scripts برای خودکارسازی استفاده کنید. پنجم، Collection را در Git یا Postman Cloud نگهداری کنید.
یک نکته مهم: Postman امکان Export Collection به صورت JSON را فراهم میکند. این قابلیت، برای نگهداری در Git و اشتراکگذاری بین تیم بسیار مفید است. با قرار دادن Collection در Git، هر تغییری در API قابل ردیابی میشود و امکان بازگشت به نسخه قبلی وجود دارد.
احراز هویت در Postman
Postman از انواع مختلف احراز هویت پشتیبانی میکند که هر کدام برای سناریوهای خاصی مناسب هستند. این امکانات، تست APIهای امن را ساده میکند.
انواع احراز هویت در Postman: Basic Auth (نام کاربری و رمز عبور)، Bearer Token (توکن معمولاً JWT)، API Key (کلید API در Header یا Query)، OAuth 1.0 و OAuth 2.0، Digest Auth، NTLM، Hawk، AWS Signature و چند نوع دیگر.
برای OAuth 2.0، Postman یک جریان کامل دارد: درخواست Authorization Code، دریافت Access Token، و Refresh Token به صورت خودکار. این امکانات، تست APIهای امن را به شدت ساده میکند.
نکات مهم درباره احراز هویت در Postman: اول، از Environment Variables برای ذخیره توکنها استفاده کنید. دوم، از Pre-request Scripts برای دریافت خودکار توکن جدید در صورت انقضا استفاده کنید. سوم، توکنها را در Git commit نکنید. چهارم، از Postman Vault برای ذخیره امن مقادیر حساس استفاده کنید.
// Pre-request Script برای Refresh Token
const refreshToken = pm.environment.get("refresh_token");
if (refreshToken) {
pm.sendRequest({
url: pm.environment.get("base_url") + "/auth/refresh",
method: "POST",
header: { "Content-Type": "application/json" },
body: { mode: "raw", raw: JSON.stringify({ refresh_token: refreshToken }) }
}, (err, res) => {
if (res.code === 200) {
pm.environment.set("access_token", res.json().access_token);
}
});
}
اگر به احراز هویت REST API علاقهمندید، احراز هویت در REST API و OAuth چیست و چگونه کار میکند را مطالعه کنید.
Test Scripts و Assertions
Test Scripts بخش اصلی خودکارسازی تست در Postman هستند. این اسکریپتها به زبان JavaScript نوشته میشوند و بعد از دریافت پاسخ، اجرا میشوند. Test Scripts امکان اعتبارسنجی خودکار پاسخها را فراهم میکنند.
ساختار یک Test Script ساده:
pm.test("Status code is 200", function () {
pm.response.to.have.status(200);
});
pm.test("Response time is less than 500ms", function () {
pm.expect(pm.response.responseTime).to.be.below(500);
});
pm.test("Content-Type is JSON", function () {
pm.response.to.have.header("Content-Type", "application/json; charset=utf-8");
});
pm.test("Response has valid user data", function () {
const data = pm.response.json();
pm.expect(data).to.have.property("id");
pm.expect(data.name).to.be.a("string");
pm.expect(data.email).to.match(/^[^@]+@[^@]+.[^@]+$/);
});
انواع Assertions رایج در Postman: اول، Status Code (بررسی کد وضعیت). دوم، Response Time (بررسی زمان پاسخ). سوم، Headers (بررسی هدرهای پاسخ). چهارم، Body Content (بررسی محتوای پاسخ). پنجم، Schema Validation (اعتبارسنجی ساختار پاسخ با JSON Schema).
نمونه استفاده از JSON Schema Validation:
const schema = {
type: "object",
required: ["id", "name", "email"],
properties: {
id: { type: "integer" },
name: { type: "string" },
email: { type: "string", format: "email" }
}
};
pm.test("Schema is valid", function () {
pm.response.to.have.jsonSchema(schema);
});
نکات مهم درباره Test Scripts: اول، از pm.test برای تعریف تست استفاده کنید. دوم، از pm.expect برای assertions استفاده کنید. سوم، متغیرهای محیطی را در Test Scripts ذخیره کنید (مثلاً id منبع ایجادشده). چهارم، از pm.response.json() برای دسترسی به پاسخ JSON استفاده کنید. پنجم، در صورت خطا، پیامهای واضح بنویسید تا دیباگ ساده باشد.
یک الگوی رایج: ذخیره id منبع ایجادشده در Environment برای استفاده در درخواستهای بعدی:
// در Test Script درخواست POST /users
const response = pm.response.json();
pm.environment.set("created_user_id", response.id);
Pre-request Scripts
Pre-request Scripts، اسکریپتهایی هستند که قبل از ارسال درخواست اجرا میشوند. این اسکریپتها برای آمادهسازی دادهها، تولید مقادیر تصادفی، یا بهروزرسانی توکنها استفاده میشوند.
نمونه تولید داده تصادفی در Pre-request Script:
// تولید ایمیل تصادفی
const randomEmail = `test_${Date.now()}@example.com`;
pm.environment.set("random_email", randomEmail);
// تولید UUID
const uuid = pm.variables.replaceIn("{{$guid}}");
pm.environment.set("user_id", uuid);
// تولید timestamp
const timestamp = pm.variables.replaceIn("{{$timestamp}}");
pm.environment.set("created_at", timestamp);
Postman چند متغیر داینامیک داخلی دارد که در Pre-request Scripts قابل استفاده هستند: {{$guid}} (UUID)، {{$timestamp}} (زمان فعلی به ثانیه)، {{$randomInt}} (عدد تصادفی)، {{$randomFirstName}}، {{$randomEmail}} و چند نمونه دیگر. این متغیرها برای تولید داده تست بسیار مفید هستند.
کاربردهای رایج Pre-request Scripts: اول، تولید داده تست یکتا برای هر اجرا. دوم، دریافت توکن تازه در صورت انقضا. سوم، آمادهسازی پارامترهای محاسبهشده (مثل هش HMAC). چهارم، ثبت لاگ قبل از ارسال درخواست.
نمونه محاسبه HMAC Signature در Pre-request Script:
const crypto = require("crypto-js");
const timestamp = Math.floor(Date.now() / 1000).toString();
const method = pm.request.method;
const path = pm.request.url.getPath();
const body = pm.request.body ? pm.request.body.raw : "";
const message = `${method}
${path}
${timestamp}
${body}`;
const secret = pm.environment.get("api_secret");
const signature = crypto.HmacSHA256(message, secret).toString();
pm.request.headers.add({ key: "X-Signature", value: signature });
pm.request.headers.add({ key: "X-Timestamp", value: timestamp });
Collection Runner
Collection Runner یکی از قدرتمندترین امکانات Postman است که به شما اجازه میدهد یک Collection را به صورت خودکار و با دادههای متنوع اجرا کنید. این ابزار، برای تست خودکار و Data-Driven Testing بسیار مفید است.
امکانات Collection Runner: اول، اجرای همه درخواستهای یک Collection به ترتیب. دوم، تکرار اجرا با فایل داده (CSV یا JSON). سوم، تنظیم تعداد تکرار و تأخیر بین درخواستها. چهارم، مشاهده گزارش جامع از اجرا. پنجم، ذخیره گزارش برای تحلیل بعدی.
نمونه فایل CSV برای Data-Driven Testing:
email,password,name
user1@example.com,pass1234,محمد
user2@example.com,pass5678,علی
user3@example.com,pass9012,رضا
در Test Scripts، با استفاده از دستور pm.iterationData.get("email") میتوانید به دادههای CSV دسترسی داشته باشید. این امکان، برای تست APIهای ورود یا ثبتنام بسیار مفید است.
نکات مهم در Collection Runner: اول، قبل از اجرا، Environment مناسب را انتخاب کنید. دوم، از فایل CSV یا JSON برای دادههای تست استفاده کنید. سوم، تعداد تکرار را به تعداد رکوردهای فایل داده تنظیم کنید. چهارم، خروجی Run را در New Relic یا Jenkins ذخیره کنید. پنجم، در صورت خطا، Retry Logic پیاده کنید.
اگر به CI/CD علاقهمندید، مقایسه ابزارهای CI/CD و گیت در وردپرس را مطالعه کنید.
Newman و CI/CD
Newman ابزار خط فرمان Postman است که امکان اجرای Collectionها را در محیطهای CI/CD فراهم میکند. Newman، Collection را میگیرد و به صورت خودکار در Pipeline اجرا میکند و در صورت خطا، Build را Fail میکند.
نصب Newman:
npm install -g newman
npm install -g newman-reporter-htmlextra
اجرای Newman:
newman run collection.json
-e environment.json
-d data.csv
-r htmlextra
--reporter-htmlextra-export report.html
یکپارچهسازی Newman با CI/CD: یک نمونه GitHub Actions Workflow:
name: API Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18
- run: npm install -g newman
- run: newman run postman/collection.json -e postman/env.json
نکات مهم در Newman: اول، Collection و Environment را در Git نگهداری کنید. دوم، از متغیرهای محیطی برای مقادیر حساس (مثل توکن) استفاده کنید. سوم، در صورت خطا، گزارش تفصیلی ذخیره کنید. چهارم، از Parallel Execution برای تستهای طولانی استفاده کنید. پنجم، در Pipeline، Newman را بعد از Unit Test و قبل از Deploy اجرا کنید.
Newman، حلقه مفقوده بین تست دستی و تست خودکار است. اگر API شما Newman-aware نباشد، معماری تست شما ناقص است.
Mock Server
Mock Server یکی دیگر از امکانات قدرتمند Postman است که به شما اجازه میدهد API را بدون پیادهسازی بکاند، شبیهسازی کنید. این امکان، برای همکاری تیمهای فرانت و بک بسیار مفید است.
نحوه کار Mock Server: اول، یک Collection با درخواستها و پاسخهای نمونه ایجاد کنید. دوم، یک Mock Server برای آن Collection بسازید. سوم، URL Mock Server را در اختیار تیم فرانت قرار دهید. تیم فرانت میتواند بدون انتظار برای بکاند، روی فرانت کار کند.
مزایای Mock Server: اول، جدا کردن تیم فرانت از تیم بک. دوم، امکان تست سناریوهای مختلف (خطا، تعویق، پاسخهای مختلف). سوم، امکان مستندسازی API قبل از پیادهسازی. چهارم، امکان تست Performance بدون نیاز به بکاند.
نکات مهم در Mock Server: اول، پاسخهای نمونه را واقعبینانه طراحی کنید. دوم، از Environment Variables برای شبیهسازی چند محیط استفاده کنید. سوم، در صورت تغییر API، Mock Server را هم بهروزرسانی کنید. چهارم، Mock Server را برای تستهای Unit و Integration استفاده کنید. مباحث بیشتر در آموزش تست API و مقایسه ابزارهای تست خودکار آمده است.
مستندسازی با Postman
Postman علاوه بر تست، امکان مستندسازی API را هم فراهم میکند. هر Collection را میتوان به یک مستندات تعاملی تبدیل کرد که شامل توضیحات درخواستها، پارامترها، هدرها و نمونه پاسخها است.
نحوه مستندسازی در Postman: اول، به هر درخواست توضیحات (Description) اضافه کنید. دوم، برای پارامترها، هدرها و بدنه، توضیحات بنویسید. سوم، نمونه پاسخها (Examples) ذخیره کنید. چهارم، با کلیک روی View Documentation، مستندات تعاملی ایجاد کنید. پنجم، مستندات را منتشر کنید (Public یا Team-only).
مزایای مستندسازی با Postman: اول، مستندات به صورت خودکار از Collection تولید میشوند. دوم، مستندات تعاملی هستند و کاربران میتوانند درخواستها را مستقیماً ارسال کنند. سوم، امکان بهروزرسانی سریع مستندات. چهارم، یکپارچگی با OpenAPI Specification.
نکات مهم درباره مستندسازی: اول، مستندات را به صورت مداوم بهروزرسانی کنید. دوم، از Mock Server برای نمایش نمونه پاسخها استفاده کنید. سوم، مثالهای واقعی در مستندات قرار دهید. چهارم، برای APIهای عمومی، مستندات را به صورت عمومی منتشر کنید. اگر به مستندسازی API علاقهمندید، راهنمای مستندسازی API و مستندسازی REST API با Swagger را مطالعه کنید.
پرسشهای پرتکرار درباره تست REST API با Postman
آیا Postman رایگان است؟ Postman یک نسخه رایگان دارد که برای اکثر کاربردهای فردی و تیمهای کوچک کافی است. نسخههای پولی (Basic، Professional، Enterprise) امکانات بیشتری مثل Postman Vault، Monitor و Governance ارائه میدهند. برای پروژههای بزرگ، نسخه Professional توصیه میشود.
آیا Postman جایگزین Unit Test است؟ خیر. Postman برای تست Integration و API Testing است، نه برای Unit Test. Unit Test باید با فریمورکهای زبان مثل Jest، PHPUnit یا pytest نوشته شود. Postman و Unit Test، مکمل یکدیگرند نه جایگزین.
چگونه Collection را در Git نگهداری کنم؟ در Postman، روی Collection کلیک راست کنید و Export کنید. فایل JSON را در Git commit کنید. برای همگامسازی، از Postman Cloud یا Git Integration استفاده کنید. توجه داشته باشید که Environment Variables حساس را در Git نگهداری نکنید.
چگونه تعداد زیادی درخواست را به طور موازی اجرا کنم؟ Postman به صورت پیشفرض درخواستها را به ترتیب اجرا میکند. برای اجرای موازی، از Newman با گزینههای --iteration-count و --parallel-execution استفاده کنید. در نسخه Enterprise، امکان Parallel Execution در Collection Runner وجود دارد.
آیا Postman از gRPC پشتیبانی میکند؟ بله، در سال ۲۰۲۳ Postman از gRPC پشتیبانی کرد. این امکان، برای تست سرویسهای gRPC مفید است. مباحث بیشتر در gRPC در برابر REST بررسی شده است.
چگونه Postman را در CI/CD یکپارچه کنم؟ از Newman استفاده کنید. Newman یک ابزار CLI است که Collection را در محیط CI/CD اجرا میکند. برای GitHub Actions، GitLab CI، Jenkins و CircleCI، مثالهای آماده در مستندات Postman موجود است.
آنچه باید با خود ببرید
Postman یک ابزار کامل برای تست REST API است که سه سطح تست را پوشش میدهد: تست دستی، تست خودکار و مانیتورینگ. Environment Variables، Collection، Test Scripts، Pre-request Scripts، Collection Runner، Newman و Mock Server، هفت ابزار کلیدی هستند که یک جریان تست حرفهای را ممکن میکنند.
پنج اصل کلیدی که در این مقاله بررسی شد:
- Environment Variables، پایه مدیریت چند محیط و همکاری تیمی است.
- Test Scripts و Pre-request Scripts، تست را از دستی به خودکار تبدیل میکنند.
- Collection Runner، امکان Data-Driven Testing و تست انبوه را فراهم میکند.
- Newman، حلقه بین تست محلی و تست CI/CD است.
- Mock Server، امکان همکاری تیم فرانت و بک را قبل از پیادهسازی بکاند فراهم میکند.
قدم عملی امروز: یک Collection ساده با سه درخواست (GET، POST، DELETE) بسازید. Environment Variables را تنظیم کنید. حداقل سه Test Script بنویسید. Collection را با Newman اجرا کنید و گزارش را ببینید. این چرخه ساده، پایه تمام تستهای حرفهای بعدی است. اگر میخواهید عمیقتر شوید، بهینهسازی عملکرد REST API و امنیت API را مطالعه کنید.
اگر تجربهای در تست REST API با Postman در پروژههای واقعی داشتید — بهخصوص اگر با چالشی مثل Newman یا Data-Driven Testing مواجه شدهاید — در دیدگاهها بنویسید. این تجربهها برای خوانندههای بعدی بسیار ارزشمند خواهند بود. 🧪