کوڈنگ ایجنٹ کو براؤزر میں اس کے کام کی تصدیق کیسے کی جائے۔

By /

میں کوڈنگ ایجنٹوں سے یہ کہہ کر تھک گیا ہوں کہ ان کا فرنٹ اینڈ کام اس وقت ہوتا ہے جب کسی نے فرنٹ اینڈ نہیں کھولا ہو۔

آپ نے شاید روٹین دیکھی ہوگی۔ ایجنٹ کچھ کوڈ تبدیل کرتا ہے اور فارمیٹرز، ٹائپ چیکرز اور ٹیسٹ چلاتا ہے۔ سب کچھ سبز ہو جائے گا اور آپ کو کچھ ورژن نظر آئے گا جس میں کہا گیا ہے کہ "عمل درآمد اور تصدیق شدہ”۔

لیکن اس کی تصدیق کیسے ہوئی؟ پاس کیے گئے ٹیسٹوں کا مجموعہ مفید ثبوت ہے، لیکن یہ ایپ کھولنے اور استعمال کرنے کے مترادف نہیں ہے جو ابھی تبدیل ہوا ہے۔

کوڈ میں بہت سی تبدیلیاں تھیں جہاں اس کا احساس ہوا اور ٹیسٹ پاس ہو گئے، لیکن UI میں اب بھی ایسے مسائل تھے جنہیں انسان تقریباً 3 سیکنڈ میں دیکھ سکتا ہے۔ ایک کنٹرول جو دوسرے کو اوور لیپ کرتا ہے۔ ایک منتخب حالت جو اسٹور میں موجود ہے لیکن اسکرین پر نمایاں نہیں ہوئی ہے۔ عمل کو ایک راستے کے لیے ری سیٹ کرتا ہے نہ کہ دوسرے راستے کے لیے۔ ایک فلٹر جو اسٹیٹس کو اپ ڈیٹ کرتا ہے لیکن صفحہ پر پرانا ڈیٹا چھوڑ دیتا ہے۔ کسی بھی چیز کو محفوظ کریں جب تک کہ آپ اسے تازہ نہ کر لیں۔ نقشے کی پرتیں غلط ترتیب میں کھینچی گئیں۔ یہ ایک ایسا ماڈل ہے جو تکنیکی طور پر کھلتا ہے، لیکن اسکرین پر فٹ نہیں ہوتا ہے۔

ایجنٹوں نے کوڈ کا تجربہ کیا، لیکن کسی نے بھی درخواست کی جانچ نہیں کی۔ اس لیے میں نے براؤزر کے جائزوں کو اپنے صارفین کے سامنے آنے والی ہر چیز کی تکمیل کی تعریف کا حصہ بنانا شروع کر دیا، اور چند ہفتوں کے بعد یہ عادت ایک ٹول میں بدل گئی۔ ہم اختتام کے قریب اس حصے کا احاطہ کریں گے۔

اس آرٹیکل میں، آپ سیکھیں گے کہ اپنے کوڈنگ ایجنٹ کو حقیقی براؤزر فراہم کرنے کے لیے پلے رائٹ MCP کا استعمال کیسے کریں، اور ہدایات کیسے لکھیں جو آپ کو صفحہ لوڈ کی جانچ کرنے کے بجائے آپ کی جانب سے ابھی کی گئی تبدیلیوں کی جانچ کرنے کی اجازت دیتی ہیں۔

آئیے دیکھتے ہیں کہ ایجنٹوں کو ایپ کو اس طریقے سے شروع کرنے کے لیے کیسے حاصل کیا جائے جیسا کہ پروجیکٹ پہلے ہی شروع ہو چکا ہے، اور ان ہدایات کو دو گروپوں کے درمیان کیسے تقسیم کیا جائے۔ AGENTS.md دوبارہ قابل استعمال تکنیکیں، الگ الگ جائزہ لینے والے ایجنٹ ایسے کیڑے کیوں پکڑتے ہیں جو مصنفین سے چھوٹ جاتے ہیں، اور یہ کیسے یقینی بنایا جائے کہ ایجنٹ صرف وہیں سے صاف کریں جہاں سے انہوں نے شروعات کی۔

آخری حصے میں، ہم اوپن سورس ٹول کیٹیلیپسس پر نظر ڈالیں گے، جس میں اس بات کا تعین کرنے کا طریقہ بھی شامل ہے کہ آیا واقعی چیک پاس ہوا ہے۔

انڈیکس

شرطیں

یہ ابتدائی ٹیوٹوریل نہیں ہے، یہ آپ کی مدد کرے گا:

  • ماڈل سیاق و سباق پروٹوکول (MCP) جیسے کلاڈ کوڈ، کوڈیکس، یا کرسر کو سپورٹ کرنے والے کوڈنگ ایجنٹوں کے لیے تجربہ اور رہنمائی فراہم کرنے کے بارے میں خیالات۔

  • ایک ویب ایپ جو JavaScript یا TypeScript میں لکھی ہوئی ڈویلپمنٹ اسکرپٹس کا استعمال کرتے ہوئے مقامی طور پر چلائی جا سکتی ہے۔ مثال نوڈ پروجیکٹ کا استعمال کرتی ہے۔ pnpmتاہم، کسی مخصوص فریم ورک پر کوئی انحصار نہیں ہے۔

  • ڈرامہ نگار کا بنیادی علم: ٹیسٹ، لوکیٹر، دلائل کس طرح کے نظر آتے ہیں۔ پہلے ہاف کی پیروی کرنے کے لیے آپ کو موجودہ ٹیسٹ سوٹ کی ضرورت نہیں ہے۔

  • Node.js 20 یا اس سے زیادہ پلے رائٹ MCP کے لیے، Node.js 22.12 یا اس سے زیادہ اگر آپ katalepsis، اور Git انسٹال کرنا چاہتے ہیں۔

  • ایجنٹ عمل شروع کرتا ہے اور اس کی تصدیق کرتا ہے، لہذا آپ ٹرمینل اور گٹ سے واقف ہیں۔ git status.

لوپ ایجنٹ غائب ہے۔

کوڈنگ ایجنٹس تیزی سے کارآمد ہو جاتے ہیں کیونکہ ان کے پاس پہلے سے ہی کوڈ کے لیے ایک اچھا فیڈ بیک لوپ ہوتا ہے۔ فارمیٹر اور ٹیسٹ پڑھیں، ان میں ترمیم کریں، انہیں چلائیں، ناکامیوں کو پڑھیں، اور دوبارہ کوشش کریں۔ کوئی بھی ایک بہادرانہ کوشش میں اسے درست نہیں کر سکتا۔

جب فرنٹ اینڈ کام کی بات آتی ہے تو واضح طور پر غائب ان پٹ خود فرنٹ اینڈ ہی ہوتا ہے۔ میں جو لوپ چاہتا ہوں وہ تھوڑا آگے جاتا ہے۔ اپنے کوڈ میں ترمیم کریں، اپنے ٹیسٹ چلائیں، ایپ شروع کریں، تبدیل شدہ فعالیت کا استعمال کریں، دیکھیں کہ کیا ہوا، کسی بھی وقفے کو ٹھیک کریں، اور اسے دوبارہ استعمال کریں۔

آخری مرحلہ آپ کے خیال سے کہیں زیادہ اہم ہے۔ ایجنٹ یہ کہہ کر بہت آرام سے ہے کہ اس کو "ابھی کام کرنا چاہیے” اور وہ چاہتا ہے کہ آپ صفحہ کو دوبارہ کھولیں۔

ڈرامہ نگار MCP انہیں یہ فراہم کرنے کا ایک بہترین طریقہ ہے۔ میں پہلے ہی E2E ٹیسٹنگ کے لیے پلے رائٹ استعمال کر چکا ہوں، لیکن MCP سرور دوسری وجوہات کے لیے مفید ہیں۔ یعنی یہ براؤزر کو براہ راست ایجنٹ تک پہنچاتا ہے۔ آپ لوکل ہوسٹ کھول سکتے ہیں، صفحات پڑھ سکتے ہیں، کنٹرولز تلاش کر سکتے ہیں، کلک اور ٹائپ کر سکتے ہیں، تبدیلیاں دیکھ سکتے ہیں اور اسکرین شاٹس لے سکتے ہیں۔

یہ کسی ایجنٹ سے کچھ کرنے کے لیے کہنے جیسا نہیں ہے۔ pnpm playwright test. ایک ٹیسٹ سویٹ آپ کو بتائے گا کہ کیا آپ نے پہلے سے لکھا ہوا کوئی منظرنامہ اب بھی گزرتا ہے۔ اپنے براؤزر کے جائزے میں، ہم پوچھتے ہیں اور دیکھتے ہیں کہ اس خاص تبدیلی کا کیا اثر ہو سکتا ہے۔

اگر آپ کا ایجنٹ کچھ مشترکہ نقشہ کی تہہ کی افادیت کو ریفیکٹر کرتا ہے، تو آپ کے ٹیسٹ میں چند مددگار شامل ہو سکتے ہیں۔ تاہم، فرق کوڈ کو ابتدائی رینڈرنگ، سلیکشن، فلٹرنگ، اور ری سیٹ کرنے اور ہر ایک کو آزمانے کے دوران چلنے کی بھی اجازت دیتا ہے۔ یہ اس سے بہت قریب ہے کہ میں اپنے سامنے والے کام کا کیسے جائزہ لیتا ہوں۔

ترتیبات چھوٹی ہیں۔ نوڈ 20 یا اس سے زیادہ اور ایک MCP- فعال کلائنٹ کی ضرورت ہے۔

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

فوری صحت کی جانچ یہ ہے کہ ایجنٹ سے پلے رائٹ ٹوڈو ایم وی سی ڈیمو کھولنے کے لیے کہے، "براؤزر QA” نامی ٹوڈو شامل کریں، اور دیکھیں کہ آیا یہ ظاہر ہوتا ہے۔ اگر آپ اس کا انتظام کرتے ہیں تو آپ کے پاس ایک براؤزر ہے۔ یہ کیا کرتا ہے مشکل حصہ ہے.

براؤزر میں ہی کیوں کمی ہے۔

ایجنٹوں کو براؤزر دینے سے انہیں صرف دیکھنے کی صلاحیت ملتی ہے۔ یہ ایجنٹ کو یہ نہیں بتاتا کہ کیا تلاش کرنا ہے، کتنی دور جانا ہے، یا ثبوت کے طور پر کیا شمار ہوتا ہے، اور اس کے بغیر، یہ تکنیکی طور پر سب سے سستی چیز پر واپس آتا ہے جو براؤزر سے متعلق ہے۔ ڈرامہ نگار کے ایجنٹ اب بھی ہنستے ہوئے کمزور QA کر سکتے ہیں۔ ہمیں درج ذیل رپورٹس موصول ہوئی ہیں:

Opened /route.
Page loaded successfully.
Browser verification complete.

یہ صفحہ کھلنے پر ایک رپورٹ ہے، تبدیلیوں کا امتحان نہیں۔ اس مضمون کے آغاز سے اب تک کوئی کیڑے نہیں ملے ہوں گے۔

لہذا براؤزر کو اس بارے میں رہنمائی کی ضرورت تھی۔ یہ کچھ اصول ہیں جو میں نے اس کے لیے لکھے ہیں کہ ایجنٹ اپنے فرنٹ اینڈ کام کا جائزہ کیسے لیتے ہیں: کیا جانچنا ہے، کیا چیک کرنا ہے، اور کیا ثبوت کھینچنا ہے۔ یہ تکنیک چند سطروں کے ساتھ شروع ہوئی جسے میں نے پرامپٹ میں بار بار دہرایا، اور بعد میں براؤزر کے جائزے کی تکنیک بن گئی جسے ہم اگلے حصے میں دیکھیں گے۔

پہلا اصول جو میں نے سیٹ کیا ہے وہ یہ ہے کہ آپ کو تبدیلیوں کا جائزہ لینا چاہیے۔ اگر فلٹر بدل گیا ہے تو اس فلٹر کو استعمال کریں۔ اگر آپ کی ری سیٹ کی منطق بدل گئی ہے تو پہلے کچھ حالت تبدیل کریں اور پھر اسے دوبارہ ترتیب دیں۔ اگر آپ مستقل مزاجی کے ساتھ گڑبڑ کرتے ہیں تو براہ کرم صفحہ کو ریفریش کریں۔ موڈل تبدیل ہونے پر موڈلز کو کھولیں اور بند کریں، اور جوابی لے آؤٹ تبدیل ہونے پر ویو پورٹ کا سائز تبدیل کریں۔

جب کوئی انسان یہ کہتا ہے تو یہ سب واضح نظر آتا ہے، لیکن اگر ایجنٹ کی ہدایات صرف یہ کہتی ہیں کہ "یقینی بنائیں کہ ایپ کام کرتی ہے” تو یہ بالکل واضح نہیں ہے۔

عملی طور پر، اس کا مطلب ہے کہ ایجنٹ فرق کو پڑھتا ہے اور اسے براؤزر تک پہنچنے سے پہلے ایک مختصر ٹیسٹ پلان میں بدل دیتا ہے۔ فلٹر بار کو تبدیل کرتے وقت آپ اس کی توقع کر سکتے ہیں:

Changed: src/features/projects/FilterBar.tsx, src/features/projects/useFilters.ts

Plan:
1. Open /projects and note how many rows are showing.
2. Filter by Status: Active. Every row should say Active.
3. Add Owner: me on top. The list should narrow again.
4. Clear filters. The original row count should come back.
5. Apply a filter and refresh. The filter lives in the URL, so it should survive.

اس کے بعد آپ پلے رائٹ MCP کے فراہم کردہ براؤزر ٹولز کے ذریعے اس منصوبہ بندی کو انجام دیتے ہیں۔ پہلے چند مراحل کے لیے کالز کا ایک چھوٹا ورژن یہ ہے:

browser_navigate   { "url": "http://localhost:5173/projects" }
browser_snapshot   {}                      → table with 40 rows
browser_click      { "element": "Status filter", "ref": "e14" }
browser_click      { "element": "Active option", "ref": "e31" }
browser_snapshot   {}                      → table with 12 rows, all "Active"
browser_click      { "element": "Clear filters", "ref": "e15" }
browser_snapshot   {}                      → table with 40 rows

کہ ref قدریں قابل رسائی اسنیپ شاٹ سے لی گئی ہیں۔ اس طرح ایجنٹ CSS سلیکٹرز کا اندازہ لگائے بغیر کنٹرولز تلاش کرتا ہے۔

یہ PR میں ادا ہوا، جس نے ایک مسئلہ حل کر دیا جہاں کرسر انٹرایکٹو نقشوں میں ہوور پر پھنس جائے گا۔ PR کے نئے یونٹ ٹیسٹ بھی پرانے کوڈ کے خلاف گزرے، اس لیے یہ ثابت نہیں ہوا کہ فکس نے کچھ کیا ہے۔ یہ ظاہر کیا گیا کہ ایجنٹ نے ایپ کو کھولا، انٹرایکٹو پرت کے ذریعے آگے پیچھے چلا گیا، اور بالکل مشاہدہ کیا کہ کرسر کو کب تبدیل ہونا چاہیے اور اسے دوبارہ ترتیب دینا چاہیے۔

دوسرا اصول یہ ہے کہ تعامل کے بجائے حتمی نتیجہ کو دیکھیں۔ "میں نے ری سیٹ پر کلک کیا اور اس نے کچھ نہیں پھینکا” آپ کو زیادہ نہیں بتاتا۔ آپ کو واقعی جس چیز کی پرواہ ہے وہ یہ ہے کہ ری سیٹ ہر چیز کو اسی طرح واپس رکھتا ہے۔ محفوظ کرنے کی طرح۔ اصل دلیل یہ ہے کہ آپ سیٹنگز کو تبدیل کر سکتے ہیں، انہیں محفوظ کر سکتے ہیں، اور ان کو ریفریش کر سکتے ہیں، اور وہ اب بھی وہی رہیں گے۔

پلے رائٹ کے ٹیسٹ کے ساتھ لکھی گئی دلیل درج ذیل ہے: اہم لائن وہ آخری لائن ہے جسے دوبارہ لوڈ کرنے کے بعد عمل میں لایا جاتا ہے۔

import { test, expect } from "@playwright/test";

test("weekly digest setting survives a reload", async ({ page }) => {
  await page.goto("/settings/notifications");
  await page.getByRole("switch", { name: "Weekly digest" }).click();
  await page.getByRole("button", { name: "Save" }).click();

  await page.reload();

  await expect(page.getByRole("switch", { name: "Weekly digest" })).toBeChecked();
});

ایجنٹوں کو قواعد پر عمل کرنے کے لیے یہ ٹیسٹ لکھنے کی ضرورت نہیں ہے۔ وہی کام دستی طور پر MCP کے ذریعے کریں۔ کلک کریں، محفوظ کریں، browser_navigate اسی URL پر جائیں اور نئے اسنیپ شاٹ سے سوئچ کی حالت پڑھیں۔

سوال پر منحصر ہے، دیگر ثبوتوں کی بھی درخواست کی جا سکتی ہے۔ آیا یو آر ایل بدل گیا ہے، بٹن غیر فعال کر دیا گیا ہے، یا ڈائیلاگ کھولا گیا ہے، یہ DOM اور براؤزر کی حالت کے بارے میں سوال ہے، اسکرین شاٹ نہیں۔ اسکرین شاٹس مفید ہیں کیونکہ یہ بصری سوالات ہیں، چاہے ایک ڈائیلاگ باکس کٹ گیا ہو، دو چیزیں اوورلیپ ہو جائیں، یا فون پر ٹیکسٹ کو غلط طریقے سے تبدیل کیا گیا ہو۔ کچھ صورتوں میں، آپ کو دونوں کی ضرورت ہو سکتی ہے، کیونکہ موڈل کو سکرین پر استعمال نہیں کیا جا سکتا لیکن DOM میں تسلی بخش استعمال کیا جا سکتا ہے۔

لے آؤٹ تبدیلیوں کے لیے، اس کا مطلب ہے سائز تبدیل کرنا اور اس مواد کو کیپچر کرنا جسے کوئی شخص حقیقت میں دیکھ سکتا ہے۔

browser_resize            { "width": 375, "height": 812 }
browser_click             { "element": "Export button", "ref": "e22" }
browser_take_screenshot   { "filename": "export-dialog-375.png" }
browser_resize            { "width": 1440, "height": 900 }
browser_take_screenshot   { "filename": "export-dialog-1440.png" }

وہاں رہتے ہوئے، ایجنٹ کنسول کو بھی دیکھ سکتا ہے اور، اگر اس کی فعالیت API کالز پر منحصر ہے، تو یہ نیٹ ورک کو بھی دیکھ سکتا ہے۔ لیکن میں صرف تبدیلیوں کی وجہ سے ہونے والی غلطیوں میں دلچسپی رکھتا ہوں۔ انتباہ جو جاری رہتا ہے۔ main تمام جائزوں کو چھ ماہ کے لیے روکا نہیں جانا چاہیے، اور صرف کلائنٹ کی منتقلی کے لیے نیٹ ورک آڈٹ کی ضرورت نہیں ہے۔ وہ بچت جس نے اصل میں "کام کیا” 500میں اس کے بارے میں سننا چاہوں گا۔

browser_console_messages اور browser_network_requests یہاں تک کہ اگر UI ٹھیک لگ رہا ہے کیونکہ صفحہ ریکارڈ کر رہا ہے اور جس چیز کی درخواست کی گئی تھی اسے واپس کر رہا ہے، ایک ناکام سیو اس طرح کی لائن کے ساتھ دکھایا جائے گا:

[PUT] http://localhost:5173/api/settings => [500] Internal Server Error

ایک ساتھ لے کر، قواعد اس حصے کے شروع میں کمزور رپورٹ کو کسی ایسی چیز میں بدل دیتے ہیں جس کی حقیقت میں تصدیق کی جا سکتی ہے۔

Route: /settings/notifications
Did: turned on "Weekly digest", clicked Save, reloaded the page.
Checked: switch still on after reload (aria-checked="true");
  PUT /api/settings returned 200; no new console errors.
Screenshots: settings-375.png, settings-1440.png (label wraps cleanly on mobile)
Tests: pnpm test settings (14 passed)
Found and fixed: Save stayed disabled after the first save. Fixed in
  SettingsForm.tsx, then went through the flow again.

اصل ایپ کو کیسے شروع کریں۔

ایجنٹ اس وقت تک کسی چیز کی جانچ نہیں کر سکتا جب تک کہ ایپ نہیں چلتی، اور شارٹ کٹس کا استعمال سب سے زیادہ پرکشش حصہ ہے۔

میں "رن” نہیں لکھنا چاہتا تھا pnpm dev"تمام ذخیروں میں، لہذا طریقہ کار ایجنٹ کو یہ فیصلہ کرنے کی ہدایت کرتا ہے کہ پروجیکٹ کیسے شروع کیا جائے۔ dev سکرپٹ package.json پہلے README دستاویز پر کچھ بھی لگائیں، اور صرف موجودہ Docker سیٹنگز پر واپس جائیں اگر آپ کی ایپ معقول طریقے سے نہیں چل سکتی۔

یہاں کا طریقہ کار براؤزر ریویو ٹیکنیک کے "ایپلی کیشن کا آغاز” سیکشن سے ہے، اور اگلے حصے میں مکمل پایا جا سکتا ہے۔ ایک عام Vite یا Next.js پروجیکٹ میں، یہ ہوگا:

# 1. How does this project start?
jq .scripts package.json
# {
#   "dev": "vite",
#   "build": "vite build",
#   "test": "vitest run",
#   "e2e": "playwright test"
# }

# 2. Start the dev server in the background, in a temp folder the agent owns,
#    and record the PID so it can stop exactly this process later.
QA_DIR=$(mktemp -d)
pnpm dev --port 5173 > "$QA_DIR/dev.log" 2>&1 &
echo $! > "$QA_DIR/dev.pid"

# 3. Wait until the server answers before opening a browser.
until curl -sf http://localhost:5173 > /dev/null; do sleep 1; done

اگر نہیں dev اسکرپٹ کے بعد README ہے۔ اگر README کہتا ہے کہ آپ کی ایپ کو Postgres اور Redis کی ضرورت ہے۔ docker compose upایجنٹ اس کمپوز فائل کا استعمال کرتا ہے اور ریکارڈ کرتا ہے کہ کون سے کنٹینرز شروع کیے گئے ہیں۔ میں کچھ نیا نہیں لکھ رہا ہوں۔

میں واقعی میں نہیں چاہتا کہ ایجنٹ ایپ کو تبدیل کرے تاکہ جانچ میں آسانی ہو۔ بائی پاس عارضی تصدیق، کوئی جعلی سرور، کوئی ترمیم نہیں۔ .envیہاں کوئی واحد راستہ موجود نہیں ہے کیونکہ وہ اصل سیٹ اپ کو حل نہیں کرسکتے ہیں۔ نقطہ اس سافٹ ویئر کو چلانے کا ہے جو میں اصل میں بھیجتا ہوں۔

یہ اس قسم کی تبدیلی ہے جس کے بارے میں میں بات کر رہا ہوں، اور ایجنٹ دراصل اس سے رجوع کرتے ہیں جب لاگ ان صفحہ دخل اندازی کرتا ہے۔

- if (!session) redirect("/login");
+ if (!session && process.env.NODE_ENV !== "development") redirect("/login");

اگر ایجنٹ آپ کے پروجیکٹ کے دستاویزی ٹیسٹ اکاؤنٹ یا بیج کے ڈیٹا کے ساتھ توثیق پاس کرنے سے قاصر ہے، تو درست کارروائی یہ ہے کہ براؤزر کے جائزے کو بلاک کیا گیا ہے اور اس کی وجہ کو روک کر رپورٹ کریں۔ بلاک شدہ جائزے ایماندار ہیں۔ توثیق بند ایپس کے جائزے آپ کی ایپ کے جائزے نہیں ہیں۔

جہاں ہدایت ہے

میری پہلی جبلت یہ تھی کہ مواد شامل کرتے رہیں۔ AGENTS.md. ہمارے پاس پہلے سے ہی ایسے قواعد موجود ہیں جن کے بارے میں ہر ایجنٹ کو جاننا ضروری ہے: ساخت، قواعد، ٹیسٹنگ فلسفہ، تبدیلیوں کی جراحی کی دیکھ بھال، بے ہودہ وضاحتیں۔

میں نے ایپ کو شروع کرنے، براؤزر کی ترتیبات، کس چیز پر کلک کرنا ہے، اسکرین شاٹس، کنسول کی غلطیاں اور ٹیر ڈاؤن کے بارے میں مزید سو لائنیں شامل کرنے کی کوشش کی، لیکن کسی وقت فائل ہدایات کے بجائے چھوٹے مذہبی متن میں بدل جاتی ہے۔

یہ جاننا مددگار ہے کہ ان فائلوں میں سے ہر ایک کو اصل میں کس طرح استعمال کیا جاتا ہے۔ AGENTS.md یہ ایک باقاعدہ مارک ڈاؤن فائل ہے جسے کوڈیکس جیسا کوڈنگ ایجنٹ خود بخود پڑھتا ہے جب اس ریپوزٹری پر ہر سیشن شروع ہوتا ہے، اور کلاڈ کوڈ وہی کام کرتا ہے: CLAUDE.md. اس میں موجود ہر چیز کسی بھی آپریشن کے لیے ایجنٹ کے سیاق و سباق سے تعلق رکھتی ہے، چاہے آپریشن CSS میں ترمیم کر رہا ہو یا ڈیٹا بیس کو منتقل کر رہا ہو۔ لہذا جب بھی آپ اسے چلاتے ہیں تو اسے سیاق و سباق کی ضرورت ہوتی ہے اور ہر جگہ لاگو ہوتا ہے۔

مہارتیں مختلف طریقے سے کام کرتی ہیں۔ اس طرح کے فولڈرز ہیں: SKILL.md مختصر حروف سے شروع ہونے والی فائلیں۔ name اور description. جب سیشن شروع ہوتا ہے، ایجنٹ صرف نام اور تفصیل دیکھتا ہے (ایک یا دو سطریں فی مہارت)۔ اگر کام تفصیل سے میل کھاتا ہے یا دیگر ہدایات اس مہارت کی طرف اشارہ کرتی ہیں، تو ایجنٹ باقی فائل کو پڑھتا ہے اور اس کی پیروی کرتا ہے۔ یہ آپ کو طویل، تفصیلی طریقہ کار کو عملی طور پر بغیر کسی قیمت کے انجام دینے کی اجازت دیتا ہے جب تک کہ آپ کو ان کی ضرورت نہ ہو۔

جس چیز پر میں اترا وہ شفا تھا۔ AGENTS.md پلے بک کی طرح آئین اور مہارت کے ساتھ۔ آئین مختصر ہے، ہر چیز پر لاگو ہوتا ہے، اور یہ کہتا ہے کہ کیا سچ ہونا چاہیے یہ بتائے بغیر کہ اسے کیسے کیا جانا چاہیے۔ ایک پلے بک ایک قسم کی صورت حال کے لیے ایک مرحلہ وار طریقہ کار ہے، اور آپ اسے صرف اس وقت نکالتے ہیں جب آپ خود کو اس صورت حال میں پاتے ہیں۔

اس ترتیب میں AGENTS.md صارف کو دکھائی دینے والا عمل اس وقت تک مکمل نہیں ہوتا جب تک کہ براؤزر سے اس کی تصدیق نہ ہو جائے، اور براؤزر ریویو ٹیکنالوجی آپ کو بتاتی ہے کہ ایسا کیسے کیا جائے۔

/
├── AGENTS.md
└── .agents/
    └── skills/
        ├── browser-review/
        │   └── SKILL.md
        ├── pr-review/
        │   └── SKILL.md
        └── grill-me/
            └── SKILL.md

حکمرانی AGENTS.md اسے مختصر رکھیں اور ہمیشہ دکھائی دیں۔

## Browser Verification

User-visible work is not complete until the affected behavior has been
verified in the running application.

For user-visible changes, follow `.agents/skills/browser-review/SKILL.md`.

A successful build, type check, unit test suite, or E2E test suite does
not replace browser verification.

Do not commit browser-verification artifacts. Stop anything you started
for verification and clean up before hand-off.

ہنر طریقہ کار کو برقرار رکھتا ہے اور صرف ضرورت کے وقت لوڈ کیا جاتا ہے۔ میں Codex اور Claude Code استعمال کرتا ہوں، اس لیے میرے پاس ایک عالمی ہے۔ AGENTS.md وہ کلاڈ CLAUDE.md دونوں سے درآمد اور پڑھنے کے لیے ایک مشترکہ ٹیکنالوجی فولڈر۔ اس سے کوئی فرق نہیں پڑتا ہے کہ میں اس دن کس ایجنٹ کے ساتھ ہوں، یہ اسی پلے بک کی پیروی کرتا ہے۔

کلاڈ کوڈ میں، درآمد ایک لائن میں کی جاتی ہے: CLAUDE.md استعمال کرتے ہوئے ایک اور فائل درآمد کریں: @:

@~/.codex/AGENTS.md

جو میں نے پہلے لکھا تھا اس کا مختصر ورژن یہ ہے:

---
name: browser-review
description: Verify user-visible changes in the running application with Playwright MCP.
---

# Browser Review

## Before verification

Run `git status --short` and remember what was already there. Don't touch
pre-existing work.

Read the task and the diff. Work out the affected routes, the changed flow,
the loading, empty, error, selected and disabled states that matter,
whether anything needs to survive a refresh, and what nearby behavior
could regress.

## Start the application

Use the repository's dev script, then its documented local setup, then its
existing Docker setup. Don't invent a new startup config and don't change
app behavior to make QA easier. Record every process and container you start.

## Exercise the change

Don't stop once the page loads. Go through the whole changed flow and check
the final result. Use browser or DOM state for functional claims and
screenshots for visual ones. Report new relevant console errors and failed
requests, not old warnings.

If something is broken, fix the smallest cause, rerun the affected tests
and go through the flow again. Don't assume the fix works.

## Cleanup

Teardown is required even when verification fails. Close browsers, stop
servers and containers, and delete screenshots, traces and other artifacts,
but only the ones you created. Run `git status --short` again before
hand-off. Never run `git add`, `git commit` or `git push`.

## Report

Say which routes you tested, what you did, which states you checked, what
tests you ran and what you found and fixed. If you couldn't finish, say why.

اس میں سے کوئی بھی ہوشیار نہیں ہے۔ قدر یہ ہے کہ یہ پہلے سے طے شدہ توقع ہے، اس لیے یہ ایجنٹ پر انحصار نہیں کرتا کہ وہ خود فیصلہ کرے کہ آیا اسے براؤزر کھولنا چاہیے۔

جائزہ لینے والوں کو آزادانہ طور پر کام کرنے کی ضرورت کیوں ہے۔

ایک واضح کمزوری یہ ہے کہ وہ ایجنٹ جو فیصلہ کرتا ہے کہ آیا کوئی کام مکمل ہوا ہے وہی ایجنٹ ہے جس نے اس کام کو تخلیق کیا ہے۔ یہ اب بھی قیمتی ہے کیونکہ یہ میرے کوڈ کی بھی جانچ کرتا ہے، لیکن اس کا آغاز اس نظریہ سے ہوتا ہے کہ عمل درآمد کیسے ہوتا ہے۔

نظریہ سے، میری مراد مصنف کا اپنا ذہنی تبدیلی ہے۔ اہم بات یہ ہے کہ یہ کس کوڈ کو متاثر کرتا ہے، کس کوڈ پر اثر انداز ہوتا ہے، اور کون سا کوڈ متاثر نہیں ہوتا ہے۔ ٹیسٹ پلان براہ راست اس ماڈل سے آتا ہے۔ لہذا آپ جس راستے کو تبدیل کرنا چاہتے ہیں اس کی جانچ کرتے ہیں، یہ کام کرتا ہے، اور یہ ان راستوں کو نہیں دیکھتا جن کو یہ نہیں پہچانتا کہ وہ متعلقہ ہیں۔ یہ وہی نابینا دھبے ہیں جو لوگ اپنے کوڈ کی جانچ کرتے وقت تجربہ کرتے ہیں، اور یہ وہ کیڑے ہیں جو جائزے سے بچ جاتے ہیں۔

لہذا، جب دوسرا ایجنٹ برانچ کا جائزہ لیتا ہے، تو وہ اسے خود ٹیسٹ کوریج کا تعین کرنے کی ہدایت کرتا ہے۔ میرے عالمی قوانین کو اب ایک نئے جائزہ لینے والے کی ضرورت ہے جس میں بات چیت کی کوئی تاریخ نہیں ہے۔ آپ کو اصل درخواست، اختلافات، اور جائزے کی تکنیک ملتی ہے، اور مصنف کے خیال میں یہ کیوں کام کرتا ہے اس کے بارے میں کچھ نہیں ملتا۔ مصنف کے اسکرین شاٹس، QA نوٹس، یا گرین ٹیسٹ رنز پر انحصار کیے بغیر اس بات کا تعین اور جانچ کریں کہ آپ کا کوڈ کیا اثر انداز ہو سکتا ہے۔

ان جائزہ لینے والوں کے لیے اشارہ جان بوجھ کر مختصر ہے۔

You are reviewing a branch you did not write.

Original request:
  Make the E2E app URL configurable through E2E_BASE_URL so the
  tests can run against any port.

Run `git diff main...HEAD` to see the change. Follow the browser-review
skill. Work out for yourself what this change could affect, test that,
and report what you checked with evidence.

اب تک کی سب سے اچھی چیز ایک PR سے آئی ہے جس نے اینڈ ٹو اینڈ ٹیسٹ سیٹ اپ کے لیے ایپ یو آر ایل کو قابل ترتیب بنا دیا۔ جائزہ لینے والے نے دریافت کیا کہ سیڈڈ ٹیسٹ ڈیٹا اب بھی پرانی پورٹ میں تصویری یو آر ایل کو ہارڈ کوڈ کر رہا تھا، اور اس نے ایپ کو کسی مختلف پورٹ پر چلا کر اس کی تصدیق کی۔ تین تصویری درخواستیں ناکام ہوئیں کیونکہ وہ غلط پورٹ پر گئی تھیں، اور صفحہ نے خاموشی سے ایک متبادل کارڈ پیش کیا جہاں تصاویر ہونی چاہئیں تھیں۔ کچھ نہیں پھینکا گیا۔

تبدیلیوں کے بعد آسان عالمی ترتیبات اس طرح نظر آئیں گی:

// e2e/global-setup.ts
const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:8080";

await seedDatabase({
  media: [
    { id: "m1", url: "http://localhost:8080/test-media/cover-1.jpg" },
    { id: "m2", url: "http://localhost:8080/test-media/cover-2.jpg" },
    { id: "m3", url: "http://localhost:8080/test-media/cover-3.jpg" },
  ],
});

مصنف کا نظریہ ہے، "اب ایپ یو آر ایل ہے۔ E2E_BASE_URL"، اور چلائے جانے والے تمام ٹیسٹوں میں پہلے سے طے شدہ پورٹ کا استعمال کیا گیا جہاں ہارڈ کوڈ شدہ URL درست تھا۔ جائزہ لینے والے کے پاس ایسا کوئی نظریہ نہیں تھا۔ Diff نے پورٹ 8081 پر ایپ کو چھونے اور چلانے والی پوری کنفگ فائل کو پڑھنے کے بعد، یہ اس کے ساتھ واپس آیا:

Found: seeded media URLs in e2e/global-setup.ts still point at :8080.
Ran the app with E2E_BASE_URL=http://localhost:8081.
Network: 3 requests to http://localhost:8080/test-media/... failed
  (net::ERR_CONNECTION_REFUSED).
Screen: the gallery rendered 3 fallback cards instead of images
  (gallery-8081.png).
Suggested fix: build the seeded URLs from E2E_BASE_URL, or make them
  relative.

فکس فی یو آر ایل ایک لائن تھی۔

{ id: "m1", url: new URL("/test-media/cover-1.jpg", baseURL).href },

چونکہ متبادل کارڈ اب بھی ایک کارڈ ہے، اس لیے یہ دیکھنے کے لیے کہ آیا کارڈ موجود ہے یا نہیں، کسی بھی طرح سے گزر جائے گا۔ یہ جاننے کے لیے آپ کو صرف صفحات اور نیٹ ورک کے ٹیبز کو دیکھنا ہوگا، لیکن یہ ایک مسئلے کے بارے میں اس مضمون کی پوری دلیل ہے۔

اپنے آپ کو اور صرف اپنے آپ کو صاف کریں۔

ایک بار جب ایجنٹ سرورز اور براؤزر شروع کر سکتا ہے، صفائی ڈیزائن کا حصہ بن جاتی ہے۔ بصورت دیگر، ہر سیشن ایگزٹ نوڈ پروسیس، کرومیم ونڈوز، اسکرین شاٹس، پلے رائٹ ٹریس، عارضی تصدیقی فائلز، یا ڈوکر کنٹینرز کی تہوں کو پیچھے چھوڑ دیتا ہے۔

لیکن "ہر چیز کو صاف کرنا” غلط فکس ہے۔ pkill node یہ کوئی صفائی نہیں ہے، یہ صرف ایجنٹ ہے جو تھوڑا سا اموک چلا رہا ہے، لہذا یہ خوشی سے اس ڈویلپمنٹ سرور کو بند کر دے گا جسے میں نے دوسرے ٹرمینل سے شروع کیا تھا۔ git clean -fd غیر ٹریک شدہ فائلوں کو حذف کریں جو ایجنٹ سے متعلق نہیں ہیں۔

قاعدہ یہ ہے کہ آپ نے جو کچھ بنایا ہے اسے صاف کریں اور باقی سب کچھ اسی طرح چھوڑ دیں۔ git status اس سے پہلے اور بعد میں ہے، لہذا براؤزر QA خاموشی سے اگلی کمٹ پر ختم نہیں ہوتا ہے۔

یہی وجہ ہے کہ یہ ابتدائی مرحلے کے دوران PID کو ایک عارضی فولڈر میں ریکارڈ کرتا ہے۔ تب نظریہ درست ہو سکتا ہے۔

# Not cleanup
pkill node
git clean -fd

# Cleanup
kill "$(cat "$QA_DIR/dev.pid")"
rm -rf "$QA_DIR"

جائزہ کے اختتام تک میں اس کی توقع کرتا ہوں:

Cleanup
- Stopped the dev server I started (pid 48213, pnpm dev --port 5173).
- Closed the Playwright MCP browser.
- Deleted export-dialog-375.png and export-dialog-1440.png.
- Left running: pid 39102 (pnpm dev on :3000). It was already running
  before I started, so it isn't mine.

git status --short before review:
 M src/features/export/ExportDialog.tsx
?? notes/todo.md

git status --short after cleanup:
 M src/features/export/ExportDialog.tsx
?? notes/todo.md

دو git status چونکہ بلاکس مماثل ہیں، جائزے میں سے کچھ بھی ورکنگ ٹری میں نہیں نکلتا، اور کوئی بھی غیر ٹریک شدہ نوٹ فائلیں جو آپ کے پاس پہلے سے موجود تھیں وہ اب بھی باقی رہیں گی۔

میں نے ان اصولوں کو خلاصہ نہیں بنایا۔ اس ٹول کی تعمیر کے دوران جس کی میں وضاحت کروں گا، اس کی جانچ کرنے والے ایجنٹ نے ایک کلین اپ کمانڈ چلائی جس نے میرے کمپیوٹر پر تمام پلے رائٹ براؤزرز کو بند کر دیا، نہ صرف اس کا اپنا براؤزر۔ منصفانہ ہونے کے لئے، اس نے سمری میں اپنا ہی رکھا۔

جب ٹیکنالوجی کافی نہیں ہے۔

ٹیکنالوجی نے اس معنی میں کام کیا کہ ایجنٹوں نے دراصل ایپ کھولنا شروع کردی۔ لیکن جو مجھے واپس ملا وہ اب بھی نثر تھا۔ ایجنٹ نے کہا کہ اگر میں نے صفحہ کھولا اور بہاؤ کے ذریعے کلک کیا تو سب کچھ درست نظر آیا، اس لیے مجھے اس کی بات ماننی چاہیے۔

یہ وہی مسئلہ ہے جس کے ساتھ میں نے شروع کیا تھا۔ آپ صرف ایک درجے اوپر گئے ہیں۔ میں براؤزر کے لیے اس سے بہتر جملہ نہیں مانگ سکتا تھا۔ مجھے ثبوت چاہیے تھا۔ میں چاہتا تھا کہ میں نے کیا چیک کیا، کیا پاس ہوا، کیا ناکام ہوا، اور اس کا بیک اپ لینے کے لیے اسکرین شاٹس اور نشانات، اس فارمیٹ میں جو میں اس کا جائزہ لینے والے کے لیے PR میں ڈال سکتا ہوں۔

لہذا میں نے ایک تعمیراتی منصوبہ لکھا اور اسے ہفتے کے دن بنایا، جس میں سنگ میل اور آزادانہ جائزہ راؤنڈز کے ذریعے کلاڈ کوڈ کے ساتھ جوڑا بنایا گیا۔ اسے کٹالیپسس کہا جاتا ہے، ایک سٹوک لفظ ہے جس کا مطلب ہے کہ آپ کچھ اس قدر واضح طور پر دیکھتے ہیں کہ آپ غلط نہیں ہو سکتے، اور یہ پل کی درخواست کے لیے ایک مناسب معیار کی طرح محسوس ہوتا ہے۔

صرف پیش نظارہ URL کی طرف اشارہ کریں اور یہ ایک رپورٹ بنائے گا (HTML، Markdown جسے آپ اپنے PR، یا JSON مینی فیسٹ میں پیسٹ کر سکتے ہیں)۔

یہ دو کام کرتا ہے۔ katalepsis run ہم پیش نظارہ کے خلاف موجودہ پلے رائٹ ٹیسٹ چلاتے ہیں، اور پلے رائٹ کے نتائج حتمی ہیں۔ katalepsis ان کو ترتیب دیتا ہے، ان پر نظر ثانی کرتا ہے، ان کو آپس میں جوڑتا ہے، اور کبھی بھی دلائل کی دوبارہ تشریح نہیں کرتا ہے۔

katalepsis verify یہ ان طرز عمل کے لیے سادہ انگریزی چیک کرتا ہے جن کے لیے کسی نے ٹیسٹ نہیں کیا ہے، اور ماڈل آپ کی اپنی Anthropic، OpenAI، یا OpenRouter کیز کا استعمال کرتے ہوئے ایک حقیقی براؤزر چلاتا ہے۔ ایک MCP سرور بھی ہے، لہذا ہم نے جس ایجنٹ کو تبدیل کیا ہے وہ خود سرور چلا سکتا ہے اور رپورٹس کو واپس پڑھ سکتا ہے۔

Catalepsis کو کیسے آزمائیں

katalepsis ابھی npm پر نہیں ہے، لہذا انسٹالر ریپوزٹری کو کلون کرے گا اور اسے بنائے گا۔ Node 22.12 یا اس سے زیادہ، Git، اور pnpm 10 (یا corepack جو Node کے ساتھ آتا ہے) کی ضرورت ہوتی ہے۔

curl -fsSL https://www.katalepsis.glamboyosa.xyz/install.sh | sh

دو لانچر شامل ہیں، katalepsis اور katalepsis-mcpمیں ~/.local/bin.

پیش نظارہ کے خلاف موجودہ ٹیسٹ چلانے کے لیے، آپ کو اپنی پلے رائٹ کنفیگریشن میں katalepsis کے پاس کردہ URL کا استعمال کرنا چاہیے۔ ناکامی کے ثبوت کو آن کرنا بھی اچھا خیال ہے تاکہ آپ کے پاس اپنی رپورٹس میں دکھانے کے لیے کچھ ہو۔

// playwright.config.ts
use: {
  baseURL: process.env.KATALEPSIS_BASE_URL ?? "http://localhost:3000",
  screenshot: "only-on-failure",
  video: "retain-on-failure",
  trace: "retain-on-failure",
},

ذخیرہ میں ایک چھوٹی ڈیمو ایپ اور جان بوجھ کر چھوٹی چھوٹی سائن اپ فارم شامل ہے۔ جب میں ایک خالی فارم جمع کرتا ہوں تو غلطی دکھانے کے بجائے کچھ نہیں ہوتا۔ ڈرامہ نگار کے تین ٹیسٹ ہیں۔ یہاں اس کا اصل نفاذ ہے:

$ katalepsis run --cwd apps/demo-form --url http://127.0.0.1:4173
katalepsis: FAILED
  2 passed, 1 failed, 0 blocked, 0 not tested
  Preview commit: not reported, so unconfirmed
  Report: artifacts/katalepsis/2026-10-19T08-21-25-288Z-3dba5a/report.html
  Markdown: artifacts/katalepsis/2026-10-19T08-21-25-288Z-3dba5a/report.md

مارک ڈاؤن رپورٹس کا مقصد PRs میں چسپاں کرنا ہے۔ یہاں یہ ہے کہ سب سے اوپر کیسا لگتا ہے:

# katalepsis report: Failed

**2 passed, 1 failed, 0 blocked** out of 3 checks run.

- Preview: http://127.0.0.1:4173/
- Preview commit: not reported, so unconfirmed
- Runner: katalepsis 0.1.0, Playwright 1.63.0, Node 22.22.0

## Checks

| Status | Check | Project | Location | Duration |
| --- | --- | --- | --- | --- |
| Failed | signup form › empty submission shows a required-field error | chromium | signup.spec.ts:8 | 3.2 s |
| Passed | signup form › valid submission shows a confirmation | chromium | signup.spec.ts:13 | 418 ms |
| Passed | signup form › malformed email shows an email error and does not submit | chromium | signup.spec.ts:20 | 449 ms |

### Failed: signup form › empty submission shows a required-field error

- Failure type: assertion
- Evidence: screenshot, video, log, trace

اس کے نیچے ڈرامہ نگار کا اپنا ناکامی کا پیغام شامل ہے (getByRole('alert') اس میں حدود کی ایک فہرست ہے، جیسے پیش نظارہ بالکل ظاہر نہیں ہو رہا ہے) اور پیش نظارہ بلٹ کمٹ کی رپورٹنگ نہیں کرتے ہیں۔

بغیر جانچ کے اعمال کے لیے سادہ انگریزی میں چیک مارکس لکھیں۔ ہر ایک کا ایک ارادہ ہے، جو عمل کرنا ہے، اور گزرنے والی شرط ہے جو آخر میں درست ہونی چاہیے۔

{
  "checks": [
    {
      "id": "empty-form",
      "name": "Empty form validation",
      "intent": "Submit the signup form without filling it",
      "passCondition": "A required-field error is visible"
    },
    {
      "id": "invalid-email",
      "name": "Invalid email",
      "intent": "Fill the name, enter an invalid email address and submit",
      "passCondition": "An email validation error is visible and the success confirmation is not shown"
    }
  ]
}

پھر katalepsis کی چابی دیں اور اسے چلائیں۔ چابیاں OS کیچین میں محفوظ کی جاتی ہیں یا ماحولیاتی متغیرات سے پڑھی جاتی ہیں اور کمانڈ لائن سے نہیں گزرتی ہیں۔

$ katalepsis auth set openrouter
$ katalepsis verify --cwd apps/demo-form --url http://127.0.0.1:4173 --checks checks.json \
    --provider openrouter --model anthropic/claude-haiku-5.5
katalepsis: FAILED (openrouter/anthropic/claude-haiku-5.5)
  2 passed, 1 failed, 0 blocked
  Preview commit: not reported, so unconfirmed
  Report: artifacts/katalepsis/2026-10-10T12-45-05-343Z-b51a0a/report.html

ڈیمو بھرا ہوا ہے۔ checks.json تین چیک ہیں، اور ایجنٹ چیک میں وہی خالی قسم کے کیڑے ملتے ہیں جو پلے رائٹ ٹیسٹ بغیر کسی کے ٹیسٹ لکھے کرتا ہے۔

آخر میں، ہم MCP سرور کو رجسٹر کرتے ہیں تاکہ کوڈنگ ایجنٹ یہ سب کچھ خود کر سکے۔ کوڈیکس کا استعمال:

codex mcp add katalepsis -- katalepsis-mcp --root /path/to/your-app

سرور تین ٹولز کو بے نقاب کرتا ہے: verification_run_tests, verification_check_browserاور verification_get_reportیہ صرف صارف کے فراہم کردہ فولڈرز میں کام کرتا ہے۔ درحقیقت، ایجنٹ کی ہدایات یہ تھیں کہ "سائن اپ فارم کو تبدیل کریں اور پھر درج ذیل کو چلائیں: verification_check_browser اپنی تبدیلیوں کی تصدیق کریں اور مارک ڈاؤن رپورٹ کو اپنے خلاصے میں چسپاں کریں۔”

کیٹیلپسس اندرونی طور پر کیسے کام کرتا ہے۔

کچھ فیصلے اس مضمون میں براہ راست مسائل سے آئے ہیں۔ یہاں یہ ہے کہ یہ کوڈ میں کیسے کام کرتا ہے:

katalepsis ایک TypeScript واحد ذخیرہ ہے جس میں 5 پیکجز ہیں۔

  • core (نتیجہ دینے والا سکیما، ڈرامہ نگار اور رپورٹ پیش کرنے والا)

  • agent (براؤزر ٹولز اور ثبوت کے اصول verify)

  • credentials (کلیدیں اور ترجیحات)

  • mcp (MCP سرور)

  • cli

ان حصوں کے لیے اثرات کا استعمال کریں جہاں غلطیاں، منسوخی، اور انحصار اہم ہیں، جیسے کہ پلے رائٹ کا عمل درآمد اور پیش نظارہ بازیافت، اور رپورٹ فارمیٹنگ کے لیے ایفیکٹ سکیما۔ ماڈل لوپ verify ہم Vercel AI SDK استعمال کرتے ہیں، لہذا یہی کوڈ Anthropic، OpenAI، اور OpenRouter کے ساتھ کام کرتا ہے۔

رپورٹیں اسکیما ہیں، لاگز نہیں۔

تمام پھانسیاں، قطع نظر اس کے کہ وہ پلے رائٹ کی طرف سے آتی ہیں یا کسی ماڈل کی، ایک ہی مواد پر ڈی کوڈ کی جاتی ہیں۔ VerificationRun کچھ بھی لکھنے سے پہلے یہ ایک ڈھانچہ ہے۔ یہاں ایک واحد چیک کا ایک چھوٹا ورژن ہے:

export const CheckStatus = Schema.Literals(["passed", "failed", "blocked"]);

export const VerificationCheck = Schema.Struct({
  id: Schema.String,
  source: Schema.Literals(["playwright-test", "agent"]),
  title: Schema.String,
  status: CheckStatus,
  flaky: Schema.Boolean,
  failure: Schema.NullOr(Schema.Struct({ code: FailureCode, message: Schema.String })),
  attempts: Schema.Array(Attempt),
  evidence: Schema.Array(BundlePath),
});

غیر چلائے جانے والے ٹیسٹوں کو الگ الگ ٹیسٹوں میں منتقل کیا جاتا ہے۔ notTested وجوہات درج کرنے کے نتیجے میں چار نتائج برآمد ہوں گے: پاس، ناکام، مسدود، یا ٹیسٹ نہیں کیا گیا۔ تمام ثبوت فائلیں SHA-256 ہیش کے ساتھ محفوظ ہیں۔ BundlePath مطلق راستوں کو مسترد کریں۔ ..لہذا، ایک رپورٹ اپنے فولڈر کے باہر اشارہ نہیں کر سکتا.

بلاک کرنا ناکامی نہیں ہے۔

اگر پیش نظارہ میں خلل پڑتا ہے، تو آپ کو ایک ایسے مسئلے کو تلاش کرنے کی کوشش کرنے کی کوشش کرنے والے تین ناکام ٹیسٹوں کے بجائے ایک بلاک شدہ رن کا سامنا کرنا پڑے گا جو موجود نہیں ہے۔ پلے رائٹ شروع کرنے سے پہلے، کٹالیپسس ایک بار پیش نظارہ URL کے لیے پوچھتا ہے۔ یہ اس تحقیقات کی کلید ہے۔

const UNAVAILABLE_STATUSES = new Set([502, 503, 504]);

const response = await fetch(url, {
  redirect: "manual",
  signal: AbortSignal.any([signal, AbortSignal.timeout(30_000)]),
});
if (UNAVAILABLE_STATUSES.has(response.status)) {
  return { reachable: false, reason: `the preview answered with HTTP ${response.status}` };
}

نیٹ ورک کی خرابی یا گیٹ وے کی حالت تمام منتخب ٹیسٹوں کو روکتی ہے اور پلے رائٹ کو شروع ہونے سے روکتی ہے۔ ڈیمو کو خالی بندرگاہ پر اشارہ کرنا دیتا ہے:

$ katalepsis run --cwd apps/demo-form --url http://127.0.0.1:4999
katalepsis: BLOCKED
  0 passed, 0 failed, 3 blocked, 0 not tested
  preview-unavailable: http://127.0.0.1:4999/ did not respond (connect ECONNREFUSED 127.0.0.1:4999). Playwright was not run.

ڈرامہ نگار کا فیصلہ حتمی ہے۔

run منصوبے کا آغاز اس کے اپنے ڈرامہ نگار سے ہوتا ہے۔ --reporter=json کسی بھی چیز کو دوبارہ لاگو کیے بغیر نتیجے میں فائل کو پڑھیں۔ ڈرامہ نگار نے ان ٹیسٹوں کو نشان زد کیا جو پہلے ہی دوبارہ کوشش میں کامیاب ہو چکے تھے: flakyلہذا کیٹیلپسس اس جھنڈے کو برقرار رکھے گا اور تمام کوششوں کی فہرست بنائے گا۔

یہ جو اضافہ کرتا ہے وہ درجہ بندی ہے۔ یہ بتانے والی خرابیاں کہ پیش منظر میں ماخذ ناقابل رسائی ہے بلاک کر دیا جائے گا، لیکن غیر فعال تیسرے فریق APIs ناکام حالت میں رہیں گے۔ کیونکہ یہ ایپ کے ساتھ ایک حقیقی مسئلہ ہے۔ جن براؤزرز کو لانچ نہیں کیا جا سکتا وہ بھی مسدود ہیں۔ یہ بالکل وہی ہے جو میں نے دیکھا جب میں نے پہلی بار غلط براؤزر کی تعمیر والے کمپیوٹر پر اس مضمون کا ڈیمو چلایا۔

ماڈل کسی چیز کو پاس نہیں کہتے ہیں۔

ماڈل ہے۔ verify آپ صفحات پر کلک، ٹائپ اور پڑھ سکتے ہیں، لیکن ہم اسے پاس نہیں کہتے ہیں۔ چیک صرف اس صورت میں پاس ہو گا جب ماڈل براؤزر کے دعوے کی طرف اشارہ کرتا ہے کہ katalepsis بھاگ گیا، گزر گیا، اور ایسا مواد دکھایا گیا جو ماڈل کے چلنے سے پہلے صفحہ پر نہیں تھا۔ ورنہ آپ کو دوبارہ بلاک کر دیا جائے گا۔

یہاں یہ ہے کہ یہ کیسے کام کرتا ہے: ماڈل ٹولز کے صرف ایک چھوٹے سیٹ کے ساتھ آتا ہے: navigate, snapshot, click, fill, press, assertاور finish. assert یہ ماڈل کی طرف سے کوئی تبصرہ واپس نہیں کرتا ہے۔ katalepsis براؤزر میں ہی اسکین چلاتا ہے، اسکرین شاٹ لیتا ہے، اور درج ذیل ID کے ساتھ نتائج کو لاگ کرتا ہے: a3. جب ماڈل کال کرتا ہے۔ finishآپ کو اس آئی ڈی کا حوالہ دینا چاہیے۔

finish: tool({
  description: "Report the verdict once, citing assertion IDs such as a1.",
  inputSchema: schema(
    Schema.Struct({
      verdict: Schema.Literals(["passed", "failed", "blocked"]),
      summary: Schema.String,
      assertionIds: Schema.Array(Schema.String),
    }),
  ),
  execute: (verdict) => {
    onFinish(verdict);
    return "Recorded.";
  },
}),

پھر باقاعدہ تقریب، decideOutcomeدعووں اور شواہد کا موازنہ کریں۔ گزرنے والے اصول کا پالش ورژن:

if (!cited.every((assertion) => assertion.passed)) {
  return "The agent reported a pass, but a cited assertion failed.";
}
const shown = cited.filter((assertion) => assertion.expectation === "visible");
if (shown.length === 0) {
  return "The agent reported a pass citing only hidden or URL assertions.";
}
if (!observeOnly && shown.every((assertion) => assertion.trueAtStart === true)) {
  return "The agent reported a pass, but everything it cited was already on the page before it acted.";
}

ان پیغامات میں سے کسی ایک کے نتیجے میں اس کوڈ کے ساتھ چیک بلاک ہو جائے گا۔ no-evidence. دعویٰ کرنے والی آئی ڈیز کا حوالہ دینا جن پر کبھی عمل نہیں ہوا وہ بھی مسدود ہے۔ یہ فنکشن گزرنے کو بھی روکتا ہے اگر آخری حوالہ دیا گیا دعویٰ کے بعد کوئی غیر نقل شدہ دعویٰ ناکام ہوجاتا ہے۔ کیونکہ تازہ ترین شواہد فیصلے سے متفق نہیں ہیں۔

کہ trueAtStart شرط کے موجود ہونے کی وجہ یہ ہے کہ میں نے جن ماڈلز کا تجربہ کیا اس میں سے ایک نے یہ ثابت کرنے کی کوشش کی کہ فارم ای میل فیلڈ کے لیبل کا حوالہ دے کر کام کرتا ہے، جو ہمیشہ موجود تھا۔ چائے

o پکڑے جانے پر، ہر اسکین آغاز کے صفحے کی دو کاپیاں الگ براؤزر سیاق و سباق میں کھولتا ہے۔ ایک ماڈل کام کرتا ہے جبکہ دوسرا وہی رہتا ہے۔ اگر ماڈل اس بات پر زور دیتا ہے کہ کوئی چیز نظر آ رہی ہے، تو کٹالیپسس اسی عنصر کو اچھوتی کاپی میں تلاش کرتا ہے، اور اگر وہ عنصر بھی موجود ہے، تو دعویٰ حاصل ہوتا ہے: trueAtStart: true اور آپ خود پاس نہیں رکھ سکتے۔

ایک وقت میں ایک کام

پہلی لائیو رن کیپچر شدہ متوازی ٹول کالز ایک دوسرے پر قدم رکھتی ہیں اور نام ای میل فیلڈ میں داخل کیے جا رہے ہیں۔ ماڈل ایک ساتھ ایک سے زیادہ ٹول کالز بھیجنا پسند کرتا ہے، اور بیک وقت دو ٹول کالز بھیجتا ہے۔ fill وہ ایک دوسرے سے مقابلہ کرتے ہیں کہ وہ اس فیلڈ کو کہے جس میں فوکس ہو۔ فکس ایک وعدہ کی قطار ہے جس سے براؤزر کے تمام آپریشن گزرتے ہیں۔

private exclusive(action: () => Promise): Promise {
  const next = this.queue.then(action, action);
  this.queue = next.catch(() => undefined);
  return next;
}

ہر کام پچھلے کام کے حل ہونے کا انتظار کرتا ہے، چاہے کامیاب ہو یا نہ ہو، اور اس کی ناکامی اگلے کام کے لیے قطار کو آلودہ نہیں کرتی۔

بجٹ اور حدود

ہر ایجنٹ کی جانچ ایک ٹریس کے ساتھ اپنے براؤزر کے سیاق و سباق میں چلتی ہے، لہذا آپ کی رپورٹس میں ہمیشہ ایک ٹریس موجود ہوتا ہے۔ نیویگیشن پیش نظارہ کی اصل تک محدود ہے اور جو بھی اشیاء کی اجازت ہے۔ --allow-origin. ماڈل میں مرحلہ وار پابندیاں ہیں (--max-steps15 بذریعہ ڈیفالٹ)، ٹوکن کی حد (--max-tokens200,000) اور وقت کی حد (--check-timeout120 سیکنڈ)، اگر ان میں سے کوئی بھی مختصر ہے، تو اسے ناکامی کے علاوہ دیگر وجوہات کی بنا پر بلاک کے طور پر رپورٹ کیا جائے گا۔ رپورٹ کے یو آر ایل سے استفسار کے اسٹرنگ میں ترمیم کی گئی ہے۔

یہ کیسے بنایا گیا تھا

کسی بھی کوڈ کو لکھنے سے پہلے، ہم نے سنگ میلوں میں تقسیم ایک تعمیراتی منصوبہ بنایا۔ M0 اس بات کا جائزہ ہے کہ ہمارے دو پچھلے پروجیکٹوں نے اسناد اور فراہم کنندگان کے ساتھ ساتھ ہمارے پہلے تعمیراتی فیصلے کی تاریخ اور monorepo ٹول کو کیسے ہینڈل کیا۔ M1 ڈرامہ نگار اور رپورٹ تھا، M2 ایجنٹ تھا جس کی چابیاں چیک کی جاتی تھیں، اور M3 MCP سرور تھا۔ ہر سنگ میل ایک نئے ایجنٹ کے ساتھ ختم ہوتا ہے جس میں منصوبے کے خلاف کام کا جائزہ لینے کا کوئی ریکارڈ نہیں ہوتا، وہی آزاد جائزہ لینے والے کے اصول جیسے پہلے اس مضمون میں تھے۔

ان جائزوں نے منصوبے سے زیادہ ٹول کو شکل دی۔ پہلے ٹیسٹ کے 15 نتائج برآمد ہوئے، جس میں ایک اصول بھی شامل ہے کہ صرف ناقابل رسائی پیش نظاروں کو ہی بلاک سمجھا جاتا تھا، جبکہ دیگر میزبان ناکام رہے۔ M2 جائزے سے معلوم ہوا کہ ماڈلز ایسے دعووں کا حوالہ دے کر گزر سکتے ہیں جو کچھ بھی ثابت نہیں کرتے۔ اس کے نتیجے میں پاسنگ کے سخت قوانین اور صفحات کی غیر تبدیل شدہ کاپیاں ہوئیں۔ M3 جائزے سے پتہ چلا کہ اگر کلائنٹ وقت سے پہلے ختم ہوجاتا ہے تو پلے رائٹ اور اس کا براؤزر چلتا رہتا ہے، اور تیار کردہ علامتی لنکس رپورٹ ٹول کو پروجیکٹ سے باہر فائلوں کو پڑھنے کی اجازت دیتے ہیں۔ تمام مسائل کو اب طے کر لیا گیا ہے اور جانچ میں شامل کیا گیا ہے۔

جب میں نے اسے استعمال کیا تو کیا ہوا۔

اس کے بارے میں کسی کو بتانے سے پہلے میں نے اسے اپنے دو پروجیکٹس پر چلایا۔ Conclave’s Suite واپس آ گیا ہے، 95 پاس کر کے۔ بڑی ایپ 137 پاس اور 1 فیل کے ساتھ واپس آئی (زوم لیول سے تھوڑا سا دور ہونے کا دعویٰ کرتے ہوئے)۔

یہ ایک ایسا ٹیسٹ تھا جو میں نے پہلے ہی کر لیا تھا اور میں نے اس میں ناکامی محسوس نہیں کی تھی، اس لیے کیٹیلیپسس کو کوئی ایسا بگ نہیں ملا جسے میں یاد نہیں کر سکتا تھا۔ دونوں منصوبے ہارڈ کوڈ شدہ ہیں۔ baseURLاس کا مطلب ہے کہ ان کی جانچ کا میرے پاس کردہ URL پر بالکل کوئی اثر نہیں ہوا۔ katalepsis اب اس کے بارے میں خبردار کرتا ہے. کیونکہ غلط سرور پر سبز چلنا بالکل نہ چلانے سے بدتر ہے۔

LinkedIn پر پوسٹ کرنے کے بعد، کسی نے تبصرے میں نشاندہی کی کہ چیک آؤٹ کیے گئے کمٹز ضروری نہیں کہ وہ پیش نظارہ کیے گئے ہوں۔ وہ درست تھے، اس لیے اب رپورٹ دونوں کو لاگ کرے گی اور انہیں تصدیق شدہ، غیر مماثل یا نامعلوم کے بطور نشان زد کرے گی، اور پرانے پیش نظارہ کے خلاف گرین رن آپ کو اختلافات کے بارے میں کچھ نہیں بتائے گا، اس لیے مماثلت رن کو گزرنے سے روک دے گی۔

پیش نظارہ کمٹ کی رپورٹ درج ذیل ہے: x-commit-sha ردعمل ہیڈر یا ٹیگز اسی تحقیقات کے ذریعہ پڑھے جاتے ہیں جو دستیابی کی جانچ کرتا ہے۔ اگر میزبان دونوں بھی نہیں کر سکتا ہے، تو یہ گزر سکتا ہے۔ --preview-commit اپنے آپ کو

میں اس مضمون میں بیان کردہ انہی ہدایات کا استعمال کرتے ہوئے اسے dogfood کر رہا ہوں۔ اب براؤزر ریویو ٹیکنالوجی میرے ایجنٹوں سے کہتی ہے کہ پہلے کٹالیپسس چلائیں اور فیلڈ ویلیوز کے لیے باقاعدہ براؤزر آٹومیشن پر فال بیک کریں جو ابھی تک حل نہیں ہوسکے ہیں، استقامت، کنسول اور نیٹ ورک، اور ویو پورٹس میں لے آؤٹ۔

پہلا کوڈیکس سیشن جس میں میں نے اسے اٹھایا، میں نے اس لائن کو بیان کرنے کے طریقے کی وجہ سے "کیٹلیپسس اسکل” کی تلاش کی۔ AGENTS.mdمجھے ایک نہیں مل سکا اور میں اپنے پچھلے براؤزر کے جائزے پر واپس چلا گیا۔ یہ کسی احمقانہ وجہ سے غلط تھا، لیکن فال بیک نے بالکل توقع کے مطابق کارکردگی کا مظاہرہ کیا اور درستگی واضح طور پر کہہ رہی تھی کہ کیٹیلیپسس ایک CLI ہے اور براؤزر کا جائزہ ایک تکنیک ہے۔

کچھ دنوں بعد میں نے اسے لائیو ورکنگ برانچ میں استعمال کیا، جس نے GeoJSON کو ڈیفالٹ ڈاؤن لوڈ بٹن میں تبدیل کر دیا اور CSV اور KML کو ڈراپ ڈاؤن میں منتقل کر دیا۔ ایجنٹ کچھ چلانے سے پہلے ہی رک گیا۔ verify میں صفحہ کا مواد ماڈل فراہم کنندہ کو بھیج رہا ہوں اور میرے قواعد کے مطابق ایپ پر کچھ کرنے سے پہلے تصدیق کی ضرورت ہے۔ یہی سلوک میں چاہتا ہوں۔

چیک بیج شدہ مصنوعی ڈیٹا اور واضح تصدیق کے ساتھ پاس ہوا۔ ایک ڈیفالٹ بٹن ظاہر ہوگا اور ایک ڈراپ ڈاؤن کھلے گا، پھر رپورٹ میں اسکرین شاٹس اور نشانات کے ساتھ مختلف فارمیٹس نظر آئیں گے۔ یہ تکنیک حقیقی ڈیٹا پر مشتمل صفحات کو متبادل راستے میں رکھتی ہے۔

جہاں میں اترا تھا۔

تمام کاموں کو اس کی ضرورت نہیں ہے۔ آپ کو یہ یقینی بنانے کے لیے پلے رائٹ کی ضرورت نہیں ہے کہ مارک ڈاؤن ٹائپ کی غلطیوں کو درست کیا گیا ہے، اور آپ کو کسی بیک اینڈ ری فیکٹرنگ کی ضرورت نہیں ہے جو اس رینڈرنگ کو تبدیل نہ کر سکے جس کی Chromium کو ضرورت نہیں ہے۔ یہ اجزاء، فارم، نیویگیشن، ڈائیلاگ، کلائنٹ اسٹیٹ، نقشے، فلٹرنگ، ریسپانسیو لے آؤٹ، استقامت، اور صارف کو نظر آنے والے کسی بھی کیڑے کو ٹھیک کرنے کے لیے ضروری ہے۔

میرا تجربہ یہ ہے کہ اگر آپ یہ دعویٰ کر رہے ہیں کہ رن ٹائم پر UI کس طرح برتاؤ کرتا ہے، تو رن ٹائم UI ثبوت کا حصہ ہونا چاہیے۔

اس میں سے کوئی بھی اچھی جانچ، کوڈ کے جائزے، یا اہم تبدیلیوں کو دیکھ کر میری جگہ نہیں لے سکتا۔ یہ صرف ایک لاپتہ فیڈ بیک لوپ کا اضافہ کرتا ہے۔ ایجنٹ کے پاس پہلے سے ہی ایک ذخیرہ اور خول ہے اور وہ جانتا ہے کہ کیا بدلا ہے۔ براؤزر آپ کو اس بارے میں سوالات کا جواب دینا شروع کرنے کی اجازت دیتے ہیں کہ آیا آپ نے جو بنایا ہے وہ حقیقت میں کام کرتا ہے، اور رپورٹیں آپ کو بتانے کے بجائے انہیں دکھانے کی اجازت دیتی ہیں۔ اگر میں بٹن استعمال کر سکتا ہوں تو میں دکھا سکتا ہوں کہ بٹن پر کلک کرنے اور کہنے سے پہلے کیا ہوا تھا۔

katalepsis MIT لائسنس یافتہ ہے اور GitHub پر ہے۔ اگر آپ کے ایجنٹ کی جانچ کے نتائج ایسے دکھاتے ہیں جو ناقابل یقین نہیں ہیں، تو ہم اس کے بارے میں سننا چاہتے ہیں۔

Related Posts

Scroll to Top