اجرای Playwright در Jupyter برای وب اسکریپینگ

مقدمه

این راهنما نشان می‌دهد چگونه از Playwright داخل یک محیط تعاملی Jupyter Notebook برای وب اسکریپینگ استفاده کنید. هدف این مقاله ارائهٔ روش‌های کاربردی، مثال‌های کدنویسی و نکات عملی برای توسعه‌دهندگان پایتون/Node.js است تا بتوانند سریع پروتوتایپ بزنند، داده‌ها را بررسی و اشکال‌زدایی کنند و اسکریپ‌های پایدار بسازند.

پس از خواندن این مقاله، شما یاد می‌گیرید چگونه محیط را نصب کنید، کرنل مناسب را فعال کنید، مرورگر را از سلول‌های نوت‌بوک مدیریت کنید، و نکات مربوط به پایداری، امنیت و اشکال‌زدایی را اعمال کنید.

خلاصهٔ سریع (TLDR)

برای اجرای Playwright در Jupyter معمولاً از کرنل ijavascript-await (کرنل Node.js با پشتیبانی از await در سطح سلول) استفاده می‌کنیم. پس از نصب و راه‌اندازی کرنل، می‌توانید بلوک اول را برای راه‌اندازی مرورگر اجرا کرده و در سلول‌های بعدی page و browser را برای ناوبری، اسکرین‌شات و استخراج داده‌ها به‌کار ببرید.

راه‌اندازی محیط

مراحل کلی نصب و آماده‌سازی:

• نصب Jupyter Notebook (یا JupyterLab) با pip یا با توزیع مورد علاقه‌تان.
• نصب کرنل مخصوص Node.js که از await در سطح سلول پشتیبانی کند، مثل ijavascript-await.
• اجرا و انتخاب کرنل «JavaScript (Node.js)» هنگام ساخت نوت‌بوک جدید.

نمونهٔ دستورات نصب (در خط فرمان):

pip install notebook
npm install -g ijavascript-await
ijsnotebook

ایجاد نوت‌بوک و شروع به کار

پس از باز شدن رابط وب Jupyter، یک نوت‌بوک جدید بسازید و کرنل Node.js را انتخاب کنید. در اولین سلول، مرورگر را راه‌اندازی کنید تا متغیرهای browser، context و page در دسترس بمانند:

const playwright = require("playwright");
const browser = await playwright.chromium.launch();
const context = await browser.newContext();
const page = await context.newPage();

توضیح ورودی/خروجی کد بالا:

• ورودی: هیچ پارامتر خارجی خاصی لازم نیست (فقط کتابخانهٔ Playwright باید نصب شده باشد).
• خروجی: سه شیء کاربردی در همین کرنل ساخته می‌شود: browser (کنترل مرورگر)، context (محیط ایزوله مانند یک پروفایل) و page (برگهٔ مجازی برای تعامل با صفحات).
• نکتهٔ مهم: اگر می‌خواهید مرورگر را برای چند سلول نگه دارید، سلول راه‌اندازی را اجرا کنید و سپس سلول‌های بعدی را اجرا کنید—ترتیب اجرا مهم است.

مثال ناوبری و جمع‌آوری عنوان صفحه

یک سلول جدید ایجاد کنید و برای رفتن به یک آدرس و گرفتن عنوان از این کد استفاده کنید:

await page.goto("https://example.com");
console.log(await page.title());
await browser.close();

گام‌به‌گام:

• page.goto: آدرس را باز می‌کند؛ اگر نیاز است می‌توانید { timeout: 30000 } یا گزینه‌های دیگر را اضافه کنید.
• page.title: عنوان صفحه را برمی‌گرداند—مناسب برای بررسی سریع DOM بارگذاری‌شده.
• browser.close: منابع مرورگر را آزاد می‌کند؛ در نوت‌بوک‌های طولانی حتماً به‌صورت دوره‌ای مرورگر را ببندید تا حافظه آزاد شود.

نمای بصری و اشکال‌زدایی

برای دیدن عملکرد صفحه در یک مرورگر واقعی (نه headless)، هنگام راه‌اندازی مرورگر گزینهٔ headless را غیرفعال کنید:

const browser = await playwright.chromium.launch({ headless: false });

به‌کارگیری این حالت در نوت‌بوک مفید است چون مرورگر باز می‌ماند و می‌توانید سلول‌ها را تغییر داده و دوباره اجرا کنید بدون اینکه بارها پنجره باز و بسته شود.

گرفتن اسکرین‌شات و نمایش در نوت‌بوک

می‌توانید تصویر صفحه را ذخیره کنید و سپس آن را در یک سلول Markdown نمایش دهید (یا از خروجی نوت‌بوک برای نمایش تصویر استفاده کنید):

await page.screenshot({ path: "test.png" });

ورودی: مسیر فایل خروجی؛ خروجی: فایلی روی دیسک با عکس از صفحه. در نوت‌بوک، با ایجاد یک سلول Markdown ساده می‌توانید تصویر را ببینید (نوت‌بوک خودتان تصویر را رندر می‌کند).

اشکال‌زدایی تعاملی

نوت‌بوک وب‌اینترفیسی امکانات breakpoint سنتی را ندارد؛ برای اشکال‌زدایی عمیق‌تر از JupyterLab یا IDEهایی مثل VSCode استفاده کنید که قابلیت Debug در سلول‌ها را فراهم می‌کنند.

خطاهای رایج و راه‌حل‌ها (Troubleshooting)

در نوت‌بوک بعضی مشکلات رایج مرتبط با حالت بلندمدت (long-running) وجود دارد. راه‌حل‌های پیشنهادی:

• Session timeouts: مقدار timeout را برای ناوبری‌ها کاهش/افزایش دهید و قسمت‌های بحرانی را با منطق retry پوشش دهید.

• Memory usage: مرورگر را مرتباً ببندید، تب‌های اضافی را ببندید یا از contextهای جدید استفاده کنید و صفحات غیرضروری را حذف کنید.

• Frozen execution: اگر اجرای کد هنگ می‌کند، کرنل را ری‌استارت کنید و علت احتمالی (حلقهٔ بی‌نهایت، promise ناتمام) را بررسی کنید.

• Unhandled promises: حتماً از try/catch برای awaitها استفاده کنید یا از Promise.allSettled برای جمع‌آوری نتایج چند promise بهره ببرید.

الگوهای مقاوم (Retry و مدیریت خطا)

نمونهٔ سادهٔ تابع retry که برای قدم‌های حساس استفاده می‌کنیم:

async function retry(fn, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === retries - 1) throw e;
      await new Promise(r => setTimeout(r, 1000));
    }
  }
}

این الگو برای شبکه‌های ناپایدار یا عملیات‌هایی که گاهی شکست می‌خورند مناسب است. ورودی fn باید یک تابع async باشد و خروجی نتیجهٔ موفق یا در نهایت خطا خواهد بود.

امنیت و مدیریت اعتبارنامه‌ها

در نوت‌بوک‌ها مراقب ذخیرهٔ اعتبارنامه‌ها باشید. چند توصیه عملی:

• از قرار دادن مستقیم یوزرنیم/پسورد در سلول خودداری کنید؛ به جای آن از process.env یا فایل‌های پیکربندی ایمن استفاده کنید.
• به محض استفاده، متغیرهای حساس را حذف یا کرنل را ری‌استارت کنید تا داده‌ها از حافظه پاک شوند.
• در محیط‌های اشتراکی دسترسی نوت‌بوک را محدود کنید و هر نوع رمز عبور یا توکن را خارج از نوت‌بوک ذخیره کنید.

نمونهٔ استفاده از متغیرهای محیطی:

const username = process.env.PLAY_USER;
const password = process.env.PLAY_PASS;
// استفاده از مقادیر در اسکریپت
// پاک‌سازی
delete process.env.PLAY_PASS;

نمونه‌های کاربردی (Use Cases)

• آزمایش‌های سریع اسکریپ: تست سلکتورها و رفتارهای صفحه قبل از انتقال به اسکریپ نهایی.
• تحلیل داده: پاک‌سازی و مصورسازی داده‌های استخراج‌شده در همان نوت‌بوک.
• تست اتوماسیون: بررسی عناصر UI و سناریوهای end-to-end به‌صورت گام‌به‌گام.
• اسکریپ‌های ادهوک: ابزارهای یک‌باره برای استخراج داده یا آماده‌سازی دیتاست.

محدودیت‌ها و چالش‌ها

• Statefulness: نگهداری وضعیت بین سلول‌ها می‌تواند منجر به ناسازگاری شود؛ ترتیب اجرا را مستندسازی کنید.
• Memory: تمام نوت‌بوک در حافظه اجرا می‌شود؛ برای کار با دادهٔ بزرگ از ذخیره‌سازی مرحله‌ای استفاده کنید.
• Debugging: ابزارهای دیباگ کامل در نوت‌بوک محدود است؛ برای باگ‌های پیچیده از IDEها کمک بگیرید.
• Stability: قطع یا timeout سرویس میزبان می‌تواند باعث از دست رفتن وضعیت نوت‌بوک شود؛ از ذخیرهٔ منظم خروجی‌ها غافل نشوید.

بهترین روش‌ها و نکات نهایی

• سلول راه‌اندازی مرورگر را جدا نگه دارید و سلول‌های کاری را روی آن بنا کنید.
• برای مراحل حساس از الگوهای retry و محدود کردن timeout استفاده کنید.
• بعد از عملیات سنگین browser.close() را فراخوانی کنید یا کرنل را ری‌استارت کنید تا حافظه آزاد شود.
• اعتبارنامه‌ها را بیرون از نوت‌بوک نگه دارید و پس از استفاده پاک کنید.

جمع‌بندی

اجرای Playwright داخل Jupyter Notebook ترکیبی عالی از توسعهٔ تعاملی و تست سریع فراهم می‌کند: می‌توانید سلکتورها را آزمایش کنید، داده‌ها را مصور کنید و پروتوتایپ بسازید. در عین حال باید به محدودیت‌های حافظه، مدیریت وضعیت و امنیت اعتبارنامه‌ها توجه داشته باشید. با رعایت الگوهای retry، بستن مرورگرها و مدیریت متغیرهای حساس، می‌توانید تجربهٔ پایدارتری از وب اسکریپینگ در نوت‌بوک داشته باشید.

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