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

این سند قالب استاندارد و راهنمای نگارش فایل‌های ATP پروژه Patent Genie (ai-workflow) است. هر 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`

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

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

`## توضیحات`