Setting up Jest with Next.js

Jest ve React Test Kütüphanesi, Birim Testi ve Snapshot Testi için sıklıkla birlikte kullanılır. Bu kılavuz size Next.js ile Jest'i nasıl kuracağınızı ve ilk testlerinizi nasıl yazacağınızı gösterecektir.

Bilmekte fayda var: async Sunucu Bileşenleri React ekosistemi için yeni olduğundan, Jest şu anda bunları desteklemiyor. Senkron Sunucu ve İstemci Bileşenleri için hala birim test leri çalıştırabilseniz de, async bileşenleri için bir E2E testleri kullanmanızı öneririz.

Quickstart

Hızlı bir şekilde başlamak için Next.js with-jest örneği ile create-next-app adresini kullanabilirsiniz:

Terminal

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

Manual setup

Next.js 12 sürümünden bu yana Next.js artık Jest için yerleşik yapılandırmaya sahiptir.

Jest'i kurmak için jest adresini ve aşağıdaki paketleri dev bağımlılıkları olarak yükleyin:

Terminal

npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom
# or
yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom
# or
pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom

Aşağıdaki komutu çalıştırarak temel bir Jest yapılandırma dosyası oluşturun:

Terminal

npm init jest@latest
# or
yarn create jest@latest
# or
pnpm create jest@latest

Bu, otomatik olarak bir jest.config.ts|js dosyası oluşturmak da dahil olmak üzere projeniz için Jest'i ayarlamak üzere sizi bir dizi komut istemine götürecektir.

Yapılandırma dosyanızı next/jest kullanmak için güncelleyin. Bu dönüştürücü, Jest'in Next.js ile çalışması için gerekli tüm yapılandırma seçeneklerine sahiptir:

jest.config.ts

import type { Config } from 'jest'
import nextJest from 'next/jest.js'
 
const createJestConfig = nextJest({
  // Provide the path to your Next.js app to load next.config.js and .env files in your test environment
  dir: './',
})
 
// Add any custom config to be passed to Jest
const config: Config = {
  coverageProvider: 'v8',
  testEnvironment: 'jsdom',
  // Add more setup options before each test is run
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
}
 
// createJestConfig is exported this way to ensure that next/jest can load the Next.js config which is async
export default createJestConfig(config)

Kaputun altında, next/jest Jest'i sizin için otomatik olarak yapılandırıyor:

Next.js Derleyicisinikullanarak transform 'u kurma
Otomatik alay stil sayfaları (.css, .module.css ve bunların scss varyantları), görüntü içe aktarma ve next/font
.env (ve tüm varyantları) içine yükleme process.env
Test çözümleme ve dönüşümlerden node_modules adresini yok sayma
Test çözümlemeden .next adresini yok sayma
SWC dönüşümlerini etkinleştiren bayraklar için next.config.js adresini yükleme

Bilmekte fayda var: Ortam değişkenlerini doğrudan test etmek için, bunları ayrı bir kurulum betiğine veya jest.config.ts dosyanıza manuel olarak yükleyin. Daha fazla bilgi için lütfen Ortam Değişkenlerini Test Etme bölümüne bakın.

Setting up Jest (with Babel)

Next.js Derleyicisinden vazgeçip bunun yerine Babel kullanırsanız, Jest'i manuel olarak yapılandırmanız ve yukarıdaki paketlere ek olarak babel-jest ve identity-obj-proxy adreslerini yüklemeniz gerekecektir.

Next.js için Jest'i yapılandırmak için önerilen seçenekler şunlardır:

jest.config.js

module.exports = {
  collectCoverage: true,
  // on node 14.x coverage provider v8 offers good speed and more or less good report
  coverageProvider: 'v8',
  collectCoverageFrom: [
    '**/*.{js,jsx,ts,tsx}',
    '!**/*.d.ts',
    '!**/node_modules/**',
    '!<rootDir>/out/**',
    '!<rootDir>/.next/**',
    '!<rootDir>/*.config.js',
    '!<rootDir>/coverage/**',
  ],
  moduleNameMapper: {
    // Handle CSS imports (with CSS modules)
    // https://jestjs.io/docs/webpack#mocking-css-modules
    '^.+\\.module\\.(css|sass|scss)$': 'identity-obj-proxy',
 
    // Handle CSS imports (without CSS modules)
    '^.+\\.(css|sass|scss)$': '<rootDir>/__mocks__/styleMock.js',
 
    // Handle image imports
    // https://jestjs.io/docs/webpack#handling-static-assets
    '^.+\\.(png|jpg|jpeg|gif|webp|avif|ico|bmp|svg)$/i': `<rootDir>/__mocks__/fileMock.js`,
 
    // Handle module aliases
    '^@/components/(.*)$': '<rootDir>/components/$1',
 
    // Handle @next/font
    '@next/font/(.*)': `<rootDir>/__mocks__/nextFontMock.js`,
    // Handle next/font
    'next/font/(.*)': `<rootDir>/__mocks__/nextFontMock.js`,
    // Disable server-only
    'server-only': `<rootDir>/__mocks__/empty.js`,
  },
  // Add more setup options before each test is run
  // setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  testPathIgnorePatterns: ['<rootDir>/node_modules/', '<rootDir>/.next/'],
  testEnvironment: 'jsdom',
  transform: {
    // Use babel-jest to transpile tests with the next/babel preset
    // https://jestjs.io/docs/configuration#transform-objectstring-pathtotransformer--pathtotransformer-object
    '^.+\\.(js|jsx|ts|tsx)$': ['babel-jest', { presets: ['next/babel'] }],
  },
  transformIgnorePatterns: [
    '/node_modules/',
    '^.+\\.module\\.(css|sass|scss)$',
  ],
}

Her bir yapılandırma seçeneği hakkında daha fazla bilgiyi adresindeki Jest dokümanlarından edinebilirsiniz. Next.js'nin Jest'i nasıl yapılandırdığını görmek için next/jest yapılandır masını incelemenizi de öneririz.

Handling stylesheets and image imports

Stil sayfaları ve resimler testlerde kullanılmaz, ancak bunları içe aktarmak hatalara neden olabilir, bu nedenle taklit edilmeleri gerekecektir.

Yukarıdaki yapılandırmada başvurulan sahte dosyaları - fileMock.js ve styleMock.js - bir __mocks__ dizini içinde oluşturun:

__mocks__/fileMock.js

module.exports = 'test-file-stub'

__mocks__/styleMock.js

module.exports = {}

Statik varlıkların işlenmesi hakkında daha fazla bilgi için lütfen Jest Docs adresine bakın.

Handling Fonts

Yazı tiplerini işlemek için __mocks__ dizini içinde nextFontMock.js dosyasını oluşturun ve aşağıdaki yapılandırmayı ekleyin:

__mocks__/nextFontMock.js

module.exports = new Proxy(
  {},
  {
    get: function getter() {
      return () => ({
        className: 'className',
        variable: 'variable',
        style: { fontFamily: 'fontFamily' },
      })
    },
  }
)

Optional: Handling Absolute Imports and Module Path Aliases

Projeniz Modül Yolu Takma Adlarını kullanıyorsa, jsconfig.json dosyasındaki paths seçeneğini jest.config.js dosyasındaki moduleNameMapper seçeneğiyle eşleştirerek içe aktarmaları çözmek için Jest'i yapılandırmanız gerekecektir. Örneğin:

tsconfig.json or jsconfig.json

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

jest.config.js

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

Optional: Extend Jest with custom matchers

@testing-library/jest-dom test yazmayı kolaylaştıran .toBeInTheDocument() gibi bir dizi kullanışlı özel eş leştirici içerir. Jest yapılandırma dosyasına aşağıdaki seçeneği ekleyerek her test için özel eşleştiricileri içe aktarabilirsiniz:

jest.config.ts

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

Ardından, jest.setup.ts içine aşağıdaki içe aktarmayı ekleyin:

jest.setup.ts

import '@testing-library/jest-dom'

Bilmekte fayda var:extend-expect , v6.0 içinde kaldırıldı, bu nedenle sürüm 6'dan önce @testing-library/jest-dom kullanıyorsanız, bunun yerine @testing-library/jest-dom/extend-expect içe aktarmanız gerekecektir.

Her testten önce daha fazla kurulum seçeneği eklemeniz gerekiyorsa, bunları yukarıdaki jest.setup.js dosyasına ekleyebilirsiniz.

Add a test script to `package.json`:

Son olarak, package.json dosyanıza bir Jest test betiği ekleyin:

package.json

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

jest --watch bir dosya değiştirildiğinde testleri yeniden çalıştıracaktır. Daha fazla Jest CLI seçeneği için lütfen Jest Docs adresine bakın.

Creating your first test:

Projeniz artık testleri çalıştırmaya hazır. Projenizin kök dizininde __tests__ adında bir klasör oluşturun.

Örneğin, <Home /> bileşeninin bir başlığı başarıyla oluşturup oluşturmadığını kontrol etmek için bir test ekleyebiliriz:

export default function Home() {
  return <h1>Home</h1>
}

__tests__/index.test.js

import '@testing-library/jest-dom'
import { render, screen } from '@testing-library/react'
import Home from '../pages/index'
 
describe('Home', () => {
  it('renders a heading', () => {
    render(<Home />)
 
    const heading = screen.getByRole('heading', { level: 1 })
 
    expect(heading).toBeInTheDocument()
  })
})

İsteğe bağlı olarak, bileşeninizdeki beklenmedik değişiklikleri takip etmek için bir anlık görüntü testi ekleyin:

__tests__/snapshot.js

import { render } from '@testing-library/react'
import Home from '../pages/index'
 
it('renders homepage unchanged', () => {
  const { container } = render(<Home />)
  expect(container).toMatchSnapshot()
})

Bilmekte fayda var: Pages Router içindeki tüm dosyalar rota olarak kabul edildiğinden, test dosyaları Pages Router içine dahil edilmemelidir.

Running your tests

Ardından, testlerinizi çalıştırmak için aşağıdaki komutu çalıştırın:

Terminal

npm run test
# or
yarn test
# or
pnpm test

Additional Resources

Daha fazla okuma için bu kaynakları faydalı bulabilirsiniz: