كيفية إعداد Jest مع Next.js

يتم استخدام Jest و React Testing Library معًا بشكل متكرر لإجراء اختبارات الوحدة واختبارات اللقطات. سيوضح لك هذا الدليل كيفية إعداد Jest مع Next.js وكتابة أول اختباراتك.

معلومة مفيدة: نظرًا لأن مكونات الخادم (Server Components) غير المتزامنة (async) جديدة في نظام React البيئي، فإن Jest لا يدعمها حاليًا. بينما يمكنك إجراء اختبارات الوحدة لمكونات الخادم والعميل المتزامنة، نوصي باستخدام اختبارات من النهاية إلى النهاية (E2E) للمكونات غير المتزامنة (async).

البدء السريع

يمكنك استخدام create-next-app مع مثال Next.js with-jest للبدء بسرعة:

npx create-next-app@latest --example with-jest with-jest-app

الإعداد اليدوي

منذ إصدار Next.js 12، أصبح لدى Next.js تكوين مدمج لـ Jest.

لإعداد Jest، قم بتثبيت jest والحزم التالية كتبعيات تطوير:

npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest
# أو
yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest
# أو
pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom ts-node @types/jest

قم بإنشاء ملف تكوين أساسي لـ Jest عن طريق تشغيل الأمر التالي:

npm init jest@latest
# أو
yarn create jest@latest
# أو
pnpm create jest@latest

سيأخذك هذا عبر سلسلة من الخطوات لإعداد Jest لمشروعك، بما في ذلك إنشاء ملف jest.config.ts|js تلقائيًا.

قم بتحديث ملف التكوين لاستخدام next/jest. يحتوي هذا المحول على جميع خيارات التكوين اللازمة ليعمل Jest مع Next.js:

import type { Config } from 'jest'
import nextJest from 'next/jest.js'

const createJestConfig = nextJest({
  // حدد مسار تطبيق Next.js لتحميل next.config.js وملفات .env في بيئة الاختبار
  dir: './',
})

// أضف أي تكوين مخصص لتمريره إلى Jest
const config: Config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
  // أضف المزيد من خيارات الإعداد قبل تشغيل كل اختبار
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
}

// يتم تصدير createJestConfig بهذه الطريقة لضمان أن next/jest يمكنه تحميل تكوين Next.js غير المتزامن
export default createJestConfig(config)

const nextJest = require('next/jest')

/** @type {import('jest').Config} */
const createJestConfig = nextJest({
  // حدد مسار تطبيق Next.js لتحميل next.config.js وملفات .env في بيئة الاختبار
  dir: './',
})

// أضف أي تكوين مخصص لتمريره إلى Jest
const config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
  // أضف المزيد من خيارات الإعداد قبل تشغيل كل اختبار
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
}

// يتم تصدير createJestConfig بهذه الطريقة لضمان أن next/jest يمكنه تحميل تكوين Next.js غير المتزامن
module.exports = createJestConfig(config)

تحت الغطاء، يقوم next/jest بتكوين Jest تلقائيًا لك، بما في ذلك:

• إعداد transform باستخدام Next.js Compiler.
• المحاكاة التلقائية لملفات الأنماط (.css, .module.css، ومتغيرات scss الخاصة بها)، واستيراد الصور وnext/font.
• تحميل .env (وجميع المتغيرات) إلى process.env.
• تجاهل node_modules من تحويلات وحل الاختبارات.
• تجاهل .next من حل الاختبارات.
• تحميل next.config.js للإشارات التي تمكن تحويلات SWC.

معلومة مفيدة: لاختبار متغيرات البيئة مباشرة، قم بتحميلها يدويًا في سيناريو إعداد منفصل أو في ملف jest.config.ts. لمزيد من المعلومات، راجع متغيرات بيئة الاختبار.

اختياري: التعامل مع الاستيراد المطلق وأسماء مسارات الوحدات

إذا كان مشروعك يستخدم أسماء مسارات الوحدات، فستحتاج إلى تكوين Jest لحل عمليات الاستيراد عن طريق مطابقة خيار paths في ملف jsconfig.json مع خيار moduleNameMapper في ملف jest.config.js. على سبيل المثال:

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",
    "baseUrl": "./",
    "paths": {
      "@/components/*": ["components/*"]
    }
  }
}

moduleNameMapper: {
  // ...
  '^@/components/(.*)$': '<rootDir>/components/$1',
}

اختياري: توسيع Jest مع مطابقات مخصصة

يتضمن @testing-library/jest-dom مجموعة من المطابقات المخصصة الملائمة مثل .toBeInTheDocument() مما يجعل كتابة الاختبارات أسهل. يمكنك استيراد المطابقات المخصصة لكل اختبار عن طريق إضافة الخيار التالي إلى ملف تكوين Jest:

setupFilesAfterEnv: ['<rootDir>/jest.setup.ts']

setupFilesAfterEnv: ['<rootDir>/jest.setup.js']

ثم، داخل jest.setup، أضف الاستيراد التالي:

import '@testing-library/jest-dom'

import '@testing-library/jest-dom'

معلومة مفيدة: تمت إزالة extend-expect في الإصدار v6.0، لذا إذا كنت تستخدم @testing-library/jest-dom قبل الإصدار 6، فستحتاج إلى استيراد @testing-library/jest-dom/extend-expect بدلاً من ذلك.

إذا كنت بحاجة إلى إضافة المزيد من خيارات الإعداد قبل كل اختبار، يمكنك إضافتها إلى ملف jest.setup أعلاه.

إضافة سيناريو اختبار إلى package.json

أخيرًا، أضف سيناريو test لـ Jest إلى ملف package.json الخاص بك:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "test": "jest",
    "test:watch": "jest --watch"
  }
}

سيقوم jest --watch بإعادة تشغيل الاختبارات عند تغيير ملف. لمزيد من خيارات واجهة سطر أوامر Jest، راجع وثائق Jest.

إنشاء أول اختبار لك

مشروعك جاهز الآن لتشغيل الاختبارات. قم بإنشاء مجلد يسمى __tests__ في الدليل الجذري لمشروعك.

على سبيل المثال، يمكننا إضافة اختبار للتحقق مما إذا كان مكون <Page /> يعرض عنوانًا بنجاح:

import Link from 'next/link'

export default function Page() {
  return (
    <div>
      <h1>Home</h1>
      <Link href="/about">About</Link>
    </div>
  )
}

import '@testing-library/jest-dom'
import { render, screen } from '@testing-library/react'
import Page from '../app/page'

describe('Page', () => {
  it('يعرض عنوانًا', () => {
    render(<Page />)

    const heading = screen.getByRole('heading', { level: 1 })

    expect(heading).toBeInTheDocument()
  })
})

اختياريًا، أضف اختبار لقطة لتتبع أي تغييرات غير متوقعة في مكونك:

import { render } from '@testing-library/react'
import Page from '../app/page'

it('يعرض الصفحة الرئيسية دون تغيير', () => {
  const { container } = render(<Page />)
  expect(container).toMatchSnapshot()
})

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

ثم، قم بتشغيل الأمر التالي لتشغيل اختباراتك:

npm run test
# أو
yarn test
# أو
pnpm test

موارد إضافية

لمزيد من القراءة، قد تجد هذه الموارد مفيدة:

• مثال Next.js مع Jest
• وثائق Jest
• وثائق React Testing Library
• Testing Playground - استخدم ممارسات اختبار جيدة لمطابقة العناصر.