🎭 Playwright

الوثائق | مرجع API

Playwright هو إطار عمل لأتمتة الويب والاختبار. فهو يشغّل Chromium وFirefox وWebKit عبر واجهة برمجة تطبيقات واحدة — في اختباراتك، وفي نصوصك البرمجية، وكأداة لوكلاء الذكاء الاصطناعي.

البدء

اختر المسار الذي يناسب سير عملك:

Playwright Test

Playwright Test هو مشغّل اختبارات كامل المواصفات مبني لاختبارات End-to-End. يشغّل الاختبارات عبر Chromium وFirefox وWebKit مع عزل كامل للمتصفح، وانتظار تلقائي، وتأكيدات موجهة للويب أولاً.

التثبيت

npm init playwright@latest

أو أضِفه يدويًا:

npm i -D @playwright/test
npx playwright install

كتابة اختبار

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

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

تشغيل الاختبارات

npx playwright test

تُشغَّل الاختبارات بالتوازي عبر جميع المتصفحات المُهيأة، في وضع headless افتراضيًا. يحصل كل اختبار على سياق متصفح جديد — عزل كامل مع حمل إضافي شبه معدوم.

القدرات الأساسية

الانتظار التلقائي والتأكيدات الموجهة للويب أولاً. لا مهلات زمنية مصطنعة. ينتظر Playwright حتى تصبح العناصر قابلة للتفاعل، وتُعاد محاولة التأكيدات تلقائيًا حتى تتحقق الشروط.

المحددات (Locators). ابحث عن العناصر باستخدام محددات مرنة تعكس الطريقة التي يرى بها المستخدمون الصفحة:

page.getByRole('button', { name: 'Submit' })
page.getByLabel('Email')
page.getByPlaceholder('Search...')
page.getByTestId('login-form')

عزل الاختبارات. يعمل كل اختبار في سياق متصفح خاص به — أي ما يعادل ملف تعريف متصفح جديد. احفظ حالة المصادقة مرة واحدة وأعد استخدامها عبر الاختبارات:

// Save state after login
await page.context().storageState({ path: 'auth.json' });

// Reuse in other tests
test.use({ storageState: 'auth.json' });

التتبّع (Tracing). التقط آثار التنفيذ ولقطات الشاشة ومقاطع الفيديو عند الفشل. افحص كل إجراء ولقطة DOM وطلب شبكة ورسالة وحدة تحكم في عارض التتبّع:

// playwright.config.ts
export default defineConfig({
  use: {
    trace: 'on-first-retry',
  },
});

npx playwright show-trace trace.zip

التوازي. تُشغَّل الاختبارات بالتوازي افتراضيًا عبر جميع المتصفحات المُهيأة.

وثائق الاختبار الكاملة

Playwright CLI

Playwright CLI هي واجهة سطر أوامر لأتمتة المتصفح مصممة لوكلاء البرمجة. وهي أكثر كفاءة في استهلاك الرموز (tokens) من MCP — إذ تتجنب أوامرها تحميل مخططات الأدوات الكبيرة وأشجار إمكانية الوصول في سياق النموذج.

التثبيت

npm install -g @playwright/cli@latest

يمكنك اختياريًا تثبيت المهارات (skills) لتكامل أكثر ثراءً مع الوكلاء:

playwright-cli install --skills

الاستخدام

وجّه وكيل البرمجة الخاص بك إلى مهمة:

Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Take screenshots for all successful and failing scenarios.

أو شغّل الأوامر مباشرة:

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli screenshot

مراقبة الجلسات

استخدم playwright-cli show لفتح لوحة تحكم مرئية تتضمن معاينات بث مباشر لجميع جلسات المتصفح النشطة. انقر على أي جلسة لتكبيرها والتحكم بها عن بُعد.

playwright-cli show

وثائق CLI الكاملة | GitHub

Playwright MCP

يمنح خادم Playwright MCP وكلاء الذكاء الاصطناعي تحكمًا كاملاً في المتصفح عبر بروتوكول سياق النموذج. يتفاعل الوكلاء مع الصفحات باستخدام لقطات إمكانية وصول منظمة — دون الحاجة إلى نماذج رؤية أو لقطات شاشة.

الإعداد

أضِفه إلى عميل MCP لديك (مثل VS Code أو Cursor أو Claude Desktop أو Windsurf أو غيرها):

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

تثبيت بنقرة واحدة لـ VS Code:

لـ Claude Code:

claude mcp add playwright npx @playwright/mcp@latest

كيف يعمل

اطلب من مساعد الذكاء الاصطناعي التفاعل مع أي صفحة ويب:

Navigate to https://demo.playwright.dev/todomvc and add a few todo items.

يرى الوكيل الصفحة كشجرة إمكانية وصول منظمة:

- heading "todos" [level=1]
- textbox "What needs to be done?" [ref=e5]
- listitem:
  - checkbox "Toggle Todo" [ref=e10]
  - text: "Buy groceries"

يستخدم مراجع عناصر مثل e5 وe10 للنقر والكتابة والتفاعل — بشكل حتمي وبدون غموض بصري. تغطي الأدوات التنقل، وملء النماذج، ولقطات الشاشة، ومحاكاة الشبكة، وإدارة التخزين، والمزيد.

وثائق MCP الكاملة | GitHub

Playwright Library

استخدم playwright كمكتبة لنصوص أتمتة المتصفح — تجريف الويب، وإنشاء PDF، والتقاط لقطات الشاشة، وأي سير عمل يتطلب تحكمًا برمجيًا في المتصفح دون مشغّل اختبارات.

أمثلة

التقاط لقطة شاشة:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://playwright.dev/');
await page.screenshot({ path: 'screenshot.png' });
await browser.close();

إنشاء ملف PDF:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://playwright.dev/');
await page.pdf({ path: 'page.pdf', format: 'A4' });
await browser.close();

محاكاة جهاز محمول:

import { chromium, devices } from 'playwright';

const browser = await chromium.launch();
const context = await browser.newContext(devices['iPhone 15']);
const page = await context.newPage();
await page.goto('https://playwright.dev/');
await page.screenshot({ path: 'mobile.png' });
await browser.close();

اعتراض طلبات الشبكة:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.route('**/*.{png,jpg,jpeg}', route => route.abort());
await page.goto('https://playwright.dev/');
await browser.close();

وثائق المكتبة | مرجع API

إضافة VS Code

تتيح إضافة Playwright لـ VS Code تشغيل الاختبارات وتصحيح الأخطاء وتوليد الأكواد مباشرةً داخل محررك.

شغّل الاختبارات وصحّح أخطاءها من المحرر بنقرة واحدة. عيّن نقاط توقف، وافحص المتغيرات، وتنقّل خطوة بخطوة عبر تنفيذ الاختبار مع عرض مباشر للمتصفح.

أنشئ الاختبارات باستخدام CodeGen. انقر على "Record new" لفتح متصفح — تنقّل وتفاعل مع تطبيقك بينما يكتب Playwright كود الاختبار نيابةً عنك.

اختر المحددات (Locators). مرّر مؤشر الفأرة فوق أي عنصر في المتصفح لرؤية أفضل محدد متاح، ثم انقر لنسخه إلى الحافظة.

تكامل عارض التتبّع (Trace Viewer). فعّل خيار "Show Trace Viewer" في الشريط الجانبي للحصول على أثر تنفيذ كامل بعد كل تشغيل اختبار — لقطات DOM، وطلبات الشبكة، وسجلات وحدة التحكم، ولقطات شاشة في كل خطوة.

ثبّت الإضافة | دليل VS Code

دعم المتصفحات المتعددة

تنفيذ بوضع headless أو بواجهة رسومية على جميع المنصات. ¹ يستخدم Chrome for Testing افتراضيًا.

لغات أخرى

Playwright متاح أيضًا لـ Python و.NET وJava.

الموارد

• الوثائق
• مرجع API
• خادم MCP
• CLI لوكلاء البرمجة
• إضافة VS Code
• دليل المساهمة
• سجل التغييرات
• Discord