الاختبار الشامل باستخدام Playwright و Next.js: من الصفر إلى خط أنابيب CI

npx create-next-app@latest my-app --typescript --app --tailwind
cd my-app

npm init playwright@latest

import { defineConfig, devices } from '@playwright/test';
 
export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: process.env.CI
    ? [['html'], ['github']]
    : [['html'], ['list']],
 
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'on-first-retry',
  },
 
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    {
      name: 'mobile-chrome',
      use: { ...devices['Pixel 7'] },
    },
  ],
 
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },
});

import { test, expect } from '@playwright/test';
 
test.describe('Home Page', () => {
  test('should display the hero section', async ({ page }) => {
    await page.goto('/');
 
    // التحقق من تحميل الصفحة
    await expect(page).toHaveTitle(/My App/);
 
    // التحقق من ظهور عنوان القسم الرئيسي
    const heading = page.getByRole('heading', { level: 1 });
    await expect(heading).toBeVisible();
  });
 
  test('should navigate to the about page', async ({ page }) => {
    await page.goto('/');
 
    // النقر على رابط التنقل
    await page.getByRole('link', { name: /about/i }).click();
 
    // التحقق من تغيّر عنوان URL
    await expect(page).toHaveURL(/\/about/);
  });
 
  test('should be responsive on mobile', async ({ page }) => {
    await page.setViewportSize({ width: 375, height: 667 });
    await page.goto('/');
 
    // زر القائمة في الهاتف يجب أن يكون مرئيًا
    const menuButton = page.getByRole('button', { name: /menu/i });
    await expect(menuButton).toBeVisible();
  });
});

npx playwright test

npx playwright test --project=chromium

npx playwright test --headed --project=chromium

import { test, expect } from '@playwright/test';
 
test.describe('Contact Form', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/contact');
  });
 
  test('should submit the form successfully', async ({ page }) => {
    // ملء حقول النموذج
    await page.getByLabel('Name').fill('Jane Developer');
    await page.getByLabel('Email').fill('jane@example.com');
    await page.getByLabel('Message').fill('Hello, I have a question about your services.');
 
    // إرسال النموذج
    await page.getByRole('button', { name: /send|submit/i }).click();
 
    // التحقق من رسالة النجاح
    await expect(
      page.getByText(/thank you|message sent/i)
    ).toBeVisible();
  });
 
  test('should show validation errors for empty fields', async ({ page }) => {
    // الإرسال بدون ملء أي شيء
    await page.getByRole('button', { name: /send|submit/i }).click();
 
    // التحقق من رسائل التحقق
    await expect(page.getByText(/name is required/i)).toBeVisible();
    await expect(page.getByText(/email is required/i)).toBeVisible();
  });
 
  test('should validate email format', async ({ page }) => {
    await page.getByLabel('Name').fill('Jane');
    await page.getByLabel('Email').fill('not-an-email');
    await page.getByLabel('Message').fill('Test message');
 
    await page.getByRole('button', { name: /send|submit/i }).click();
 
    await expect(
      page.getByText(/valid email/i)
    ).toBeVisible();
  });
});

import { type Locator, type Page, expect } from '@playwright/test';
 
export class ContactPage {
  readonly page: Page;
  readonly nameInput: Locator;
  readonly emailInput: Locator;
  readonly messageInput: Locator;
  readonly submitButton: Locator;
  readonly successMessage: Locator;
 
  constructor(page: Page) {
    this.page = page;
    this.nameInput = page.getByLabel('Name');
    this.emailInput = page.getByLabel('Email');
    this.messageInput = page.getByLabel('Message');
    this.submitButton = page.getByRole('button', { name: /send|submit/i });
    this.successMessage = page.getByText(/thank you|message sent/i);
  }
 
  async goto() {
    await this.page.goto('/contact');
  }
 
  async fillForm(name: string, email: string, message: string) {
    await this.nameInput.fill(name);
    await this.emailInput.fill(email);
    await this.messageInput.fill(message);
  }
 
  async submit() {
    await this.submitButton.click();
  }
 
  async expectSuccess() {
    await expect(this.successMessage).toBeVisible();
  }
}

import { test } from '@playwright/test';
import { ContactPage } from './pages/contact-page';
 
test.describe('Contact Form', () => {
  test('should submit successfully', async ({ page }) => {
    const contactPage = new ContactPage(page);
    await contactPage.goto();
    await contactPage.fillForm('Jane', 'jane@example.com', 'Hello!');
    await contactPage.submit();
    await contactPage.expectSuccess();
  });
});

import { test, expect } from '@playwright/test';
import { ContactPage } from './pages/contact-page';
 
test('should handle API errors gracefully', async ({ page }) => {
  // اعتراض استدعاء API وإرجاع خطأ
  await page.route('**/api/contact', (route) => {
    route.fulfill({
      status: 500,
      contentType: 'application/json',
      body: JSON.stringify({ error: 'Internal server error' }),
    });
  });
 
  const contactPage = new ContactPage(page);
  await contactPage.goto();
  await contactPage.fillForm('Jane', 'jane@example.com', 'Hello!');
  await contactPage.submit();
 
  // التحقق من عرض الخطأ للمستخدم
  await expect(
    page.getByText(/something went wrong|try again/i)
  ).toBeVisible();
});
 
test('should show loading state during submission', async ({ page }) => {
  // تأخير استجابة API لملاحظة حالة التحميل
  await page.route('**/api/contact', async (route) => {
    await new Promise((resolve) => setTimeout(resolve, 2000));
    route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ success: true }),
    });
  });
 
  const contactPage = new ContactPage(page);
  await contactPage.goto();
  await contactPage.fillForm('Jane', 'jane@example.com', 'Hello!');
  await contactPage.submit();
 
  // الزر يجب أن يُظهر مؤشر تحميل
  await expect(
    page.getByRole('button', { name: /sending|loading/i })
  ).toBeVisible();
});

import { test, expect } from '@playwright/test';
 
test.describe('Visual Regression', () => {
  test('home page matches snapshot', async ({ page }) => {
    await page.goto('/');
    // الانتظار حتى تستقر الخطوط والصور والرسوم المتحركة
    await page.waitForLoadState('networkidle');
 
    await expect(page).toHaveScreenshot('home-page.png', {
      maxDiffPixelRatio: 0.01,
    });
  });
 
  test('contact form matches snapshot', async ({ page }) => {
    await page.goto('/contact');
    await page.waitForLoadState('networkidle');
 
    await expect(page).toHaveScreenshot('contact-form.png', {
      maxDiffPixelRatio: 0.01,
    });
  });
 
  test('dashboard cards layout', async ({ page }) => {
    await page.goto('/dashboard');
    await page.waitForLoadState('networkidle');
 
    // لقطة شاشة لعنصر محدد
    const cardsSection = page.getByTestId('dashboard-cards');
    await expect(cardsSection).toHaveScreenshot('dashboard-cards.png');
  });
});

npx playwright test --update-snapshots

npm install -D @axe-core/playwright

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
 
test.describe('Accessibility', () => {
  test('home page has no critical violations', async ({ page }) => {
    await page.goto('/');
 
    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
      .analyze();
 
    expect(results.violations).toEqual([]);
  });
 
  test('contact form is accessible', async ({ page }) => {
    await page.goto('/contact');
 
    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa'])
      .analyze();
 
    // طباعة الانتهاكات لأغراض التصحيح
    if (results.violations.length > 0) {
      console.log('Accessibility violations:');
      results.violations.forEach((v) => {
        console.log(`  [${v.impact}] ${v.id}: ${v.description}`);
        v.nodes.forEach((n) => {
          console.log(`    - ${n.html}`);
        });
      });
    }
 
    expect(results.violations).toEqual([]);
  });
 
  test('navigation is keyboard accessible', async ({ page }) => {
    await page.goto('/');
 
    // التنقل بالضغط على Tab عبر شريط التنقل
    await page.keyboard.press('Tab');
    const firstFocused = await page.evaluate(() =>
      document.activeElement?.tagName.toLowerCase()
    );
    expect(firstFocused).toBe('a');
 
    // التحقق من أن التركيز مرئي (غير مخفي بـ CSS)
    const focusedElement = page.locator(':focus');
    await expect(focusedElement).toBeVisible();
    await expect(focusedElement).toHaveCSS('outline-style', /(solid|auto)/);
  });
});

import { test as setup, expect } from '@playwright/test';
import path from 'node:path';
 
const authFile = path.join(__dirname, '../.playwright/.auth/user.json');
 
setup('authenticate', async ({ page }) => {
  await page.goto('/login');
 
  await page.getByLabel('Email').fill('test@example.com');
  await page.getByLabel('Password').fill('test-password');
  await page.getByRole('button', { name: /sign in/i }).click();
 
  // الانتظار لإعادة التوجيه بعد تسجيل الدخول
  await page.waitForURL('/dashboard');
 
  // حفظ حالة المصادقة
  await page.context().storageState({ path: authFile });
});

export default defineConfig({
  // ... الإعداد الحالي
 
  projects: [
    // مشروع الإعداد - يُشغّل أولاً
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
 
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        storageState: '.playwright/.auth/user.json',
      },
      dependencies: ['setup'],
    },
    // ... مشاريع المتصفحات الأخرى بنفس storageState
  ],
});

npx playwright test --ui

npx playwright show-trace test-results/home-page-chromium/trace.zip

npx playwright codegen localhost:3000

// e2e/fixtures/test-data.ts
import { test as base } from '@playwright/test';
import { ContactPage } from '../pages/contact-page';
 
type Fixtures = {
  contactPage: ContactPage;
};
 
export const test = base.extend<Fixtures>({
  contactPage: async ({ page }, use) => {
    const contactPage = new ContactPage(page);
    await contactPage.goto();
    await use(contactPage);
  },
});
 
export { expect } from '@playwright/test';

import { test, expect } from '../fixtures/test-data';
 
test('should submit form', async ({ contactPage }) => {
  await contactPage.fillForm('Jane', 'jane@example.com', 'Hello!');
  await contactPage.submit();
  await contactPage.expectSuccess();
});

name: Playwright Tests
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  test:
    timeout-minutes: 15
    runs-on: ubuntu-latest
 
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
 
      - name: Install dependencies
        run: npm ci
 
      - name: Install Playwright browsers
        run: npx playwright install --with-deps
 
      - name: Build the application
        run: npm run build
 
      - name: Run Playwright tests
        run: npx playwright test
        env:
          CI: true
 
      - name: Upload test report
        uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30
 
      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: test-results
          path: test-results/
          retention-days: 7

webServer: {
  command: process.env.CI ? 'npm run start' : 'npm run dev',
  url: 'http://localhost:3000',
  reuseExistingServer: !process.env.CI,
  timeout: 120_000,
},

await expect(page).toHaveScreenshot('page.png', {
  mask: [page.getByTestId('timestamp')],
});