شیوه‌نامه نگارش ATP (Acceptance Test Protocol)

این سند قالب استاندارد و راهنمای نگارش فایل‌های ATP پروژه MFire است. هر endpoint یا گروه endpoint مرتبط باید یک فایل Markdown جداگانه داشته باشد که طبق این شیوه‌نامه تهیه شود.

۲. ساختار کلی سند

هر فایل ATP از یک عنوان اصلی (#) و چند بخش ثابت (##) تشکیل می‌شود. ترتیب زیر توصیه می‌شود؛ بخش‌های اختیاری با (اختیاری) مشخص شده‌اند.

# ATP - [عنوان فارسی endpoint] ([METHOD] [مسیر])

## Endpoint                    ← توصیه‌شده
## هدف آزمون                   ← اجباری
## شرایط آزمون                 ← اجباری
## فرآیند آزمون                ← اجباری
## معرفی ویژگی                 ← اجباری
## سناریوی آزمون               ← اجباری
## قالب API                     ← اجباری
## قالب API خروجی              ← اختیاری (در صورت پیچیدگی پاسخ)
## Swagger                      ← اجباری
## نمونه ورودی                 ← توصیه‌شده (برای POST/PUT/PATCH)
## نمونه خروجی                 ← اجباری
### Status Codes               ← اجباری (زیرمجموعه نمونه خروجی)
## نتیجه مورد انتظار           ← اجباری
## روال صحت‌سنجی               ← اجباری
## توضیحات                     ← اجباری

برای چند endpoint در یک فایل، پس از اتمام بخش‌های اولین endpoint، با خط جداکننده --- و تکرار ساختار از ## Endpoint برای endpoint بعدی ادامه دهید (مثل 26_profile_lock.md).

۳. شرح بخش‌ها

`# ATP - [عنوان]`

هدف: شناسایی یکتا و خوانا در فهرست ATP و خروجی HTML.

محتوا:
- عنوان فارسی واضح (فعل + موضوع)
- در پرانتز: متد HTTP و مسیر کامل

نمونه:

# ATP - ارسال کلید به پنجره فعال (POST /send-key)

نکات:
- از عنوان‌های مبهم مثل «تست API» پرهیز کنید.
- اگر endpoint به پروفایل وابسته است، نام مرورگر یا مسیر /profile/{browser}/ را ذکر کنید.

`## Endpoint` (توصیه‌شده)

هدف: نمایش سریع مسیر و متد بدون ورود به Swagger.

محتوا: بلوک کد با متد(ها) و مسیر(ها).

نمونه:

## Endpoint
\`\`\`
POST /send-key
\`\`\`

نکات:
- برای چند متد، هر خط یک endpoint.
- Path parameterها را با {نام} بنویسید: /profile/firefox/{profile_name}/open-url
- مسیرها باید با پیاده‌سازی فعلی (app/main.py و routerها) هم‌خوان باشند.

`## هدف آزمون`

هدف: یک جمله که مشخص کند چه رفتاری باید تأیید شود.

محتوا: جملهٔ خبری کوتاه؛ تمرکز بر نتیجهٔ قابل آزمون، نه جزئیات پیاده‌سازی.

نمونه:

## هدف آزمون
ارسال یک کلید کیبورد به پنجره Firefox فعال

نکات:
- حداکثر ۱–۲ جمله.
- فعل آغازین: «بررسی»، «ارسال»، «قفل کردن»، «دریافت» و مانند آن.

`## شرایط آزمون`

هدف: پیش‌نیازهای محیط و داده قبل از اجرای تست.

محتوا: لیست bullet با -؛ هر مورد یک شرط مستقل.

نمونه:

## شرایط آزمون
- داشتن پروفایل Firefox باز و فعال
- دسترسی به mfire API
- پنجره Firefox باید در حالت focus باشد

نکات:
- شامل: وضعیت سرویس، وجود پروفایل، ابزار سیستم (xdotool، xclip)، Docker/VNC، قفل پروفایل و غیره.
- شرایطی که در حین تست ساخته می‌شوند (مثل «پروفایل ساخته شود») را در فرآیند آزمون بیاورید.

`## فرآیند آزمون`

هدف: گام‌های سطح بالا برای اجرای ATP (بدون جزئیات assert).

محتوا: لیست شماره‌دار 1. 2. 3.

نمونه:

## فرآیند آزمون
1. ارسال درخواست POST به endpoint
2. ارسال کلید مورد نظر در body
3. دریافت تأیید عملیات

نکات:
- ۳ تا ۷ گام؛ از تکرار سناریوها خودداری کنید.
- ترتیب منطقی: آماده‌سازی → درخواست → بررسی پاسخ → (اختیاری) بررسی side effect

`## معرفی ویژگی`

هدف: توضیح محصولی/فنی endpoint برای خواننده ATP و توسعه‌دهنده.

محتوا:
- پاراگراف کوتاه مقدمه
- لیست bullet با برچسب پررنگ برای قابلیت‌ها
- (اختیاری) نکات مهم، محدودیت‌ها، رفتار edge case با **نکته مهم**:

نمونه:

## معرفی ویژگی
این API امکان ارسال کلیدهای کیبورد به پنجره Firefox فعال را فراهم می‌کند. ویژگی‌های اصلی:

- **ارسال کلیدهای ترکیبی**: پشتیبانی از ctrl+t، ctrl+w
- **ارسال کلیدهای ساده**: Return (Enter)
- **کنترل تأخیر**: پارامتر delay به ثانیه

نکات:
- تفاوت با endpointهای مشابه را روشن کنید (مثلاً PyDoll در برابر xdotool).
- وابستگی به middleware (قفل پروفایل، timeout خودکار) را اینجا ذکر کنید.

`## سناریوی آزمون`

هدف: پوشش مسیر موفق، خطا و edge case به‌صورت قابل اجرا.

محتوا:
- زیرعنوان‌های ### سناریو N: [عنوان کوتاه]
- برای هر سناریو: یک خط توضیح (بدون عنوان جدا) + گام‌های شماره‌دار

الگوی سناریو:

### سناریو 1: [مسیر موفق — عنوان واضح]
[یک جمله: کاربر/سیستم چه می‌خواهد]
1. ...
2. ...
3. ...

### سناریو N: خطا - [علت خطا]
[شرایط خطا]
1. ...
2. سرور خطای [کد] را برمی‌گرداند
3. بررسی پیام خطای مناسب

سناریوهای پیشنهادی حداقلی:

نوع	مثال عنوان
موفق ساده	«ارسال کلید Enter»
موفق با پارامتر اختیاری	«ارسال کلید با تأخیر»
خطای 400	«خطا — مرورگر باز نیست»
خطای 403	«خطا — پروفایل دیگر قفل است» (در صورت مرتبط)
خطای 404	«خطا — پروفایل وجود ندارد»

نکات:
- عنوان سناریو با ### سناریو شروع شود (سازگار با convert_atp_to_html.py).
- گام‌ها با 1. 2. شروع شوند.
- سناریوهای قفل پروفایل را برای endpointهای /profile/... در نظر بگیرید.

`## قالب API`

هدف: جدول پارامترهای ورودی (Path، Query، Body).

محتوا: جدول Markdown با ستون‌های استاندارد.

ستون‌های اجباری:

ستون	توضیح
مولفه	نام فیلد یا پارامتر
نوع	`Path` / `Query` / `Body` / `Header`
نوع داده	`string`، `integer`، `float`، `boolean`، `array`، `object`
اجباری	`بله` / `خیر` / `خیر (پیش‌فرض: …)`

ستون اختیاری:

ستون	توضیح
توضیحات	مقدار پیش‌فرض، محدوده، مثال

نمونه:

## قالب API

| مولفه | نوع | نوع داده | اجباری | توضیحات |
|--------|-----|---------|--------|---------|
| key | Body | string | بله | کلید (مثلاً ctrl+t، Return) |
| delay | Body | float | خیر | تأخیر بعد از ارسال؛ پیش‌فرض 0.05 |

نکات:
- برای GET بدون پارامتر: یک ردیف — یا حذف ستون توضیحات (مثل 01_root_endpoint.md).
- endpoint بدون body فقط Path/Query را جدول کنید.

`## قالب API خروجی` (اختیاری)

هدف: وقتی ساختار JSON پاسخ چند فیلد دارد یا چند نوع پاسخ وجود دارد.

محتوا: جدول مشابه قالب API؛ ستون «اجباری» معمولاً حذف می‌شود.

نمونه:

## قالب API خروجی

| مولفه | نوع | نوع داده | توضیحات |
|--------|-----|---------|---------|
| status | Response | string | وضعیت عملیات (success) |
| message | Response | string | پیام توضیحی |

`## Swagger`

هدف: بازتاب خلاصه OpenAPI برای هم‌ترازی با /docs.

محتوا: بلوک ```yaml با متد، summary، parameters/requestBody، responses.

نمونه:

## Swagger

\`\`\`yaml
post:
  summary: Send key to active Firefox window
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
            - key
          properties:
            key:
              type: string
              example: "Return"
  responses:
    200:
      description: Key sent successfully
    400:
      description: Bad request
\`\`\`

نکات:
- summary انگلیسی؛ توضیحات فارسی در description مجاز است.
- همه status codeهای مهم (200، 400، 403، 404، 500) را فهرست کنید.

`## نمونه ورودی` (توصیه‌شده)

هدف: نمونهٔ قابل اجرا برای تست دستی یا Postman.

محتوا:
- زیرعنوان ### برای هر نوع درخواست
- بلوک bash با curl کامل (شامل -H و -d)

نمونه:

## نمونه ورودی

### ارسال کلید Enter
\`\`\`bash
curl -X POST "http://localhost:8000/send-key" \\
  -H "Content-Type: application/json" \\
  -d '{"key": "Return"}'
\`\`\`

نکات:
- پورت نمونه: 8000 یا پورت استاندارد محیط تست پروژه؛ در کل ATP یکسان بگیرید.
- URL base را کامل بنویسید.
- برای GET می‌توان این بخش را حذف و فقط در «نمونه خروجی» از curl استفاده کرد.

`## نمونه خروجی`

هدف: نمونهٔ پاسخ موفق یا بدنهٔ پاسخ شاخص.

محتوا:
- بلوک json برای APIهای JSON
- یا توضیح متنی/HTML برای endpointهای غیر JSON (مثل GET /)

نمونه:

## نمونه خروجی

\`\`\`json
{
  "status": "success",
  "message": "Key sent successfully"
}
\`\`\`

`### Status Codes`

هدف: فهرست کدهای HTTP و معنی فارسی؛ بلافاصله زیر «نمونه خروجی».

محتوا: لیست bullet با -

نمونه:

### Status Codes
- 200: کلید با موفقیت ارسال شد
- 400: خطا در درخواست (مرورگر باز نیست)
- 403: پروفایل قفل است و دسترسی مجاز نیست

نکات:
- عنوان دقیقاً ### Status Codes باشد (سازگار با تبدیل HTML).
- همه کدهای mencion شده در Swagger را پوشش دهید.

`## نتیجه مورد انتظار`

هدف: جمع‌بندی observable برای pass/fail تست.

محتوا: ۱–۳ جمله؛ شامل کد وضعیت، شکل پاسخ، و side effect اصلی.

نمونه:

## نتیجه مورد انتظار
در صورت موفقیت، پاسخ JSON با `status: "success"` و کد 200 برگردانده می‌شود. کلید به پنجره فعال ارسال می‌شود.

`## روال صحت‌سنجی`

هدف: چک‌لیست گام‌به‌گام برای tester.

محتوا: لیست شماره‌دار؛ هر مورد یک assert مشخص.

نمونه:

## روال صحت‌سنجی
1. بررسی ارسال صحیح پارامتر `key`
2. بررسی وجود پنجره Firefox باز و فعال
3. بررسی کد وضعیت 200
4. (اختیاری) بررسی اثر کلید در مرورگر

نکات:
- عنوان ## روال صحت‌سنجی یا ## روال صحت سنجی (هر دو در parser پشتیبانی می‌شوند).
- موارد اختیاری را با (اختیاری) علامت بزنید.

`## توضیحات`

هدف: نکات تکمیلی، محدودیت‌ها، وابستگی‌ها، ارجاع به کد یا env.

محتوا: لیست bullet.

نمونه:

## توضیحات
- این API از xdotool استفاده می‌کند
- نیاز به پنجره Firefox در focus دارد
- کلیدهای رایج: ctrl+t، ctrl+w، Return
- `delay` برای کنترل سرعت عملیات است

۴. قالب خالی (کپی برای ATP جدید)

# ATP - [عنوان فارسی] ([METHOD] [مسیر])

## Endpoint
\`\`\`
[METHOD] [مسیر]
\`\`\`

## هدف آزمون
[یک جمله]

## شرایط آزمون
- [پیش‌نیاز ۱]
- [پیش‌نیاز ۲]

## فرآیند آزمون
1. [گام ۱]
2. [گام ۲]
3. [گام ۳]

## معرفی ویژگی
[پاراگراف کوتاه]

- **[قابلیت ۱]**: [توضیح]
- **[قابلیت ۲]**: [توضیح]

## سناریوی آزمون

### سناریو 1: [مسیر موفق]
[توضیح یک خطی]
1. ...
2. ...

### سناریو 2: خطا - [علت]
[توضیح]
1. ...
2. سرور خطای [کد] را برمی‌گرداند

## قالب API

| مولفه | نوع | نوع داده | اجباری | توضیحات |
|--------|-----|---------|--------|---------|
| | | | | |

## Swagger

\`\`\`yaml
[method]:
  summary: [English summary]
  responses:
    200:
      description: Success
\`\`\`

## نمونه ورودی

### [عنوان درخواست]
\`\`\`bash
curl -X [METHOD] "http://localhost:8000[مسیر]" \\
  -H "Content-Type: application/json" \\
  -d '{}'
\`\`\`

## نمونه خروجی

\`\`\`json
{}
\`\`\`

### Status Codes
- 200: [توضیح]
- 400: [توضیح]

## نتیجه مورد انتظار
[جمع‌بندی]

## روال صحت‌سنجی
1. ...
2. ...

## توضیحات
- ...

۵. نکات کیفی و یکنواختی

زبان: متن بدنه فارسی؛ summary در Swagger و نام فیلدهای JSON انگلیسی.
مسیرها: از مسیرهای فعلی API استفاده کنید (/profile/firefox/ نه /firefox-profiles/ مگر در سند قدیمی که هنوز به‌روز نشده).
مرورگرها: برای endpointهای Chromium مشابه، در عنوان مرورگر و مسیر (chrome، chromium، chrome-pydoll) را دقیق بنویسید.
قفل پروفایل: برای endpointهای وابسته به profile_name، حداقل یک سناریوی 403 در نظر بگیرید.
چند endpoint در یک فایل: فقط وقتی منطقاً یک گروه هستند (مثل lock/unlock/lock-status یا tabs).
تبدیل HTML: اسکریپت convert_atp_to_html.py بخش‌های ## استاندارد و ### سناریو / ### Status Codes را parse می‌کند؛ از تغییر نام این هدرها خودداری کنید.
به‌روزرسانی: با تغییر رفتار API، ابتدا ATP مربوطه و سپس در صورت نیاز 01_root_endpoint.md و صفحهٔ اصلی (GET /) را هماهنگ کنید.

۶. چک‌لیست قبل از merge

[ ] عنوان # ATP - شامل متد و مسیر است
[ ] حداقل یک سناریوی موفق و یک سناریوی خطا وجود دارد
[ ] جدول قالب API با پیاده‌سازی و DTO هم‌خوان است
[ ] نمونه curl اجراپذیر است
[ ] ### Status Codes زیر «نمونه خروجی» آمده است
[ ] روال صحت‌سنجی قابل اجرا توسط tester است
[ ] مسیر endpoint با کد منبع (app/) یکسان است

نسخه شیوه‌نامه: 1.0 — هم‌راستا با ساختار ATPهای 01–27 و اسکریپت convert_atp_to_html.py

شیوه‌نامه نگارش ATP

شیوه‌نامه نگارش ATP (Acceptance Test Protocol)

۲. ساختار کلی سند

۳. شرح بخش‌ها

# ATP - [عنوان]

## Endpoint (توصیه‌شده)

## هدف آزمون

## شرایط آزمون

## فرآیند آزمون

## معرفی ویژگی

## سناریوی آزمون

## قالب API

## قالب API خروجی (اختیاری)

## Swagger

## نمونه ورودی (توصیه‌شده)

## نمونه خروجی

### Status Codes

## نتیجه مورد انتظار

## روال صحت‌سنجی

## توضیحات

۴. قالب خالی (کپی برای ATP جدید)

۵. نکات کیفی و یکنواختی

۶. چک‌لیست قبل از merge

`# ATP - [عنوان]`

`## Endpoint` (توصیه‌شده)

`## هدف آزمون`

`## شرایط آزمون`

`## فرآیند آزمون`

`## معرفی ویژگی`

`## سناریوی آزمون`

`## قالب API`

`## قالب API خروجی` (اختیاری)

`## Swagger`

`## نمونه ورودی` (توصیه‌شده)

`## نمونه خروجی`

`### Status Codes`

`## نتیجه مورد انتظار`

`## روال صحت‌سنجی`

`## توضیحات`