Sorgular

Temel kural

Elemanları kullanıcının bulduğu gibi bulun. Kullanıcı elemanları rol, label ve metin ile bulur. Kullanıcı state adlarını veya CSS class'larını görmez.

İç yapıya bağlı testler küçük bir refactoring işleminde kırılır. Davranışa bağlı testler kırılmaz.¹

Sorgu önceliği

Listede yukarıdaki sorgu, aşağıdakinden daha iyidir. Her zaman ilk uygun sorguyu seçin.

Tam sıra şöyledir: getByRole, getByLabelText, getByPlaceholderText, getByText, getByDisplayValue, ardından getByAltText, getByTitle ve en sonda getByTestId.²

Örnek sayfa

Bu adımdaki testler ürün listesini kullanır. Component'in tam kodunu Ürün Listesi projesinde görürsünüz. Liste şu HTML'i üretir:

<section aria-label="Ürünler">
  <label htmlFor="product-search">Ürün ara</label>
  <input id="product-search" type="search" />
  <ul>
    <li>
      <article aria-labelledby="product-2-title">
        <h2 id="product-2-title">Mekanik Klavye</h2>
        <p>₺2.199,00</p>
        <button type="button">Sepete ekle</button>
      </article>
    </li>
    {/* ... diğer ürünler */}
  </ul>
</section>

Liste veriyi sonradan yükler. Bu yüzden her testin ilk satırı await screen.findAllByRole("article") olur. Bekleme konusunu Asenkron Testler adımında öğrenirsiniz.

import { render, screen } from "@testing-library/react";
import { ProductList } from "./ProductList";

const products = [
  { id: 1, name: "Kablosuz Kulaklık", price: 1299, inStock: true },
  { id: 2, name: "Mekanik Klavye", price: 2199, inStock: true },
  { id: 3, name: "Oyuncu Faresi", price: 899, inStock: false },
];

async function renderList() {
  render(
    <ProductList
      loadProducts={() => Promise.resolve(products)}
      onAddToCart={vi.fn()}
    />,
  );

  await screen.findAllByRole("article");
}

test("ürünü rol, label ve metin ile bulur", async () => {
  await renderList();

  expect(
    screen.getByRole("heading", { name: "Mekanik Klavye" }),
  ).toBeInTheDocument();
  expect(screen.getByLabelText("Ürün ara")).toBeInTheDocument();
  expect(screen.getByText("₺2.199,00")).toBeInTheDocument();
});

getByRole kullanımı

getByRole, elemanın ARIA rolünü ve erişilebilir adını kullanır. HTML elemanları otomatik bir role sahiptir.⁵⁶

name seçeneği erişilebilir adı belirtir. Aynı roldeki elemanları ayırmak için bunu kullanın:⁵

screen.getByRole("button", { name: "Sepete ekle" });
screen.getByRole("heading", { name: "Mekanik Klavye", level: 2 });
screen.getByRole("article", { name: "Mekanik Klavye" });
screen.getByRole("region", { name: "Ürünler" });

getByRole, erişilebilirlik ağacından çıkarılan elemanları (hidden, display: none, visibility: hidden, aria-hidden="true") varsayılan olarak yoksayar. Bu elemanları bulmak için hidden: true ekleyin.⁵

Sorgu ailesi

Her sorgunun üç ön eki vardır. Ön ek, elemanın şu anda DOM'da olup olmadığını belirler.²

Birden fazla eleman bekliyorsanız All sürümünü kullanın: getAllBy, queryAllBy, findAllBy. Tekil sorgular birden fazla eşleşmede hata fırlatır.

test("sorgu ailesi", async () => {
  await renderList();

  expect(screen.getAllByRole("article")).toHaveLength(3);

  expect(screen.queryByText("Ürün bulunamadı.")).not.toBeInTheDocument();
});

Metin eşleştirme

Metin sorguları varsayılan olarak tam eşleşme ve büyük/küçük harf duyarlı çalışır.²⁷

Metin sık değişiyorsa /sepete ekle/i gibi regex kullanabilirsiniz. Regex büyük/küçük harf farkından doğan kırılmaları azaltır. Çok geniş bir regex ise yanlış elemanı da yakalayabilir. Rol sorgusuyla birlikte kullanıp name ile daraltın.

Alan daraltma: within

Listede üç Sepete ekle butonu vardır. getByRole("button", { name: "Sepete ekle" }) hata verir. Aramayı bir kartla sınırlayın:⁸

import { screen, within } from "@testing-library/react";

test("klavye kartındaki butonu bulur", async () => {
  await renderList();

  const card = screen.getByRole("article", { name: "Mekanik Klavye" });

  expect(
    within(card).getByRole("button", { name: "Sepete ekle" }),
  ).toBeEnabled();
});

Testing Playground

HTML'iniz için en uygun sorguyu bu araç önerir. Aşağıdaki örnek bu dersteki ürün kartıdır. Önizlemede bir elemana tıklayın. Önerilen sorguyu okuyun. Sorguyu değiştirip sonucu görün.

Kendin dene

• Oyuncu Faresi kartını getByRole("article", ...) ile bulun.

• within ile kartın içindeki Stokta yok yazısının görünür olduğunu test edin.

• Mekanik Klavye kartında Stokta yok yazısının bulunmadığını queryByText ile test edin.