Konumlandırıcılar 2.1.0+

Konumlandırıcı, bir öğenin veya bir dizi öğenin temsilidir. Her konumlandırıcı, 'seçici' adı verilen bir dize ile tanımlanır. Vitest, arka planda bu seçicileri oluşturan kullanışlı yöntemler sağlayarak bu seçiciyi soyutlar.

Konumlandırıcı API'si, Playwright'ın konumlandırıcılarının Ivya adlı bir fork'unu kullanır. Ancak Vitest, bu API'yi tüm sağlayıcılara sunar.

getByRole

function getByRole(
  role: ARIARole | string,
  options?: LocatorByRoleOptions
): Locator;

Bir öğeyi ARIA rolü, ARIA öznitelikleri ve erişilebilir adı ile bulmak için bir konumlandırıcı oluşturur.

TIP

Yalnızca getByText('Adı') ile tek bir öğe sorguluyorsanız, genellikle getByRole(beklenenRol, { name: 'Adı' }) kullanmak daha iyi bir yaklaşımdır. Erişilebilir ad sorgusu, *ByAltText veya *ByTitle gibi diğer sorguların işlevini değiştirmez. Erişilebilir ad bu özniteliklere eşit olabilse de, bu özniteliklerin sağladığı işlevselliğin yerini almaz.

Aşağıdaki DOM yapısını göz önünde bulundurun.

<h3>Kaydol</h3>
<label>
  Giriş
  <input type="text" />
</label>
<label>
  Şifre
  <input type="password" />
</label>
<br />
<button>Gönder</button>

Her öğeyi örtük rolüne göre bulabilirsiniz:

await expect
  .element(page.getByRole('heading', { name: 'Kaydol' }))
  .toBeVisible();

await page.getByRole('textbox', { name: 'Giriş' }).fill('admin');
await page.getByRole('textbox', { name: 'Şifre' }).fill('admin');

await page.getByRole('button', { name: /gönder/i }).click();

WARNING

Roller, ARIA rol hiyerarşisinden bağımsız olarak dize eşitliğiyle eşleştirilir. Sonuç olarak, checkbox gibi bir üst sınıf rolünü sorgulamak, switch gibi bir alt sınıf rolüne sahip öğeleri içermez.

Varsayılan olarak, HTML'deki birçok anlamsal öğenin bir rolü bulunur; örneğin, <input type="radio"> "radio" rolüne sahiptir. HTML'deki anlamsal olmayan öğelerin bir rolü yoktur; ek semantik eklenmemiş <div> ve <span> null değeri döndürür. role özniteliği semantik sağlayabilir.

ARIA yönergeleri tarafından, zaten örtük bir role sahip yerleşik öğelere role veya aria-* öznitelikleri aracılığıyla roller atamak kesinlikle önerilmez.

Seçenekler

• exact: boolean

  name'in tam olarak eşleştirilip eşleştirilmediği: büyük/küçük harfe duyarlı ve tam dize. Varsayılan olarak kapalıdır. name bir düzenli ifade ise bu seçenek göz ardı edilir. Tam eşleşmenin yine de boşlukları kaldırdığını unutmayın.

  <button>Merhaba Dünya</button>;
  
  page.getByRole('button', { name: 'merhaba dünya' }); // ✅
  page.getByRole('button', { name: 'merhaba dünya', exact: true }); // ❌
  page.getByRole('button', { name: 'Merhaba Dünya', exact: true }); // ✅

• checked: boolean

  İşaretli öğelerin (aria-checked veya <input type="checkbox"/> ile ayarlanmış) dahil edilip edilmeyeceği. Varsayılan olarak, filtre aktif değildir.

  Daha fazla bilgi için aria-checked bölümüne bakın.

  <>
    <button role="checkbox" aria-checked="true" />
    <input type="checkbox" checked />
  </>;
  
  page.getByRole('checkbox', { checked: true }); // ✅
  page.getByRole('checkbox', { checked: false }); // ❌

• disabled: boolean

  Devre dışı bırakılmış öğelerin dahil edilip edilmeyeceği. Varsayılan olarak, filtre aktif değildir. Diğer özniteliklerin aksine, disabled durumunun miras alındığını unutmayın.

  Daha fazla bilgi için aria-disabled bölümüne bakın.

  <input type="text" disabled />;
  
  page.getByRole('textbox', { disabled: true }); // ✅
  page.getByRole('textbox', { disabled: false }); // ❌

• expanded: boolean

  Genişletilmiş öğelerin dahil edilip edilmeyeceği. Varsayılan olarak, filtre aktif değildir.

  Daha fazla bilgi için aria-expanded bölümüne bakın.

  <a aria-expanded="true" href="example.com">
    Bağlantı
  </a>;
  
  page.getByRole('link', { expanded: true }); // ✅
  page.getByRole('link', { expanded: false }); // ❌

• includeHidden: boolean

  Erişilebilirlik ağacından normalde hariç tutulan öğelerin sorgulanıp sorgulanmayacağı. Varsayılan olarak, yalnızca gizli olmayan öğeler rol seçici tarafından eşleştirilir.

  none ve presentation rollerinin her zaman dahil edildiğini unutmayın.

  <button style="display: none" />;
  
  page.getByRole('button'); // ❌
  page.getByRole('button', { includeHidden: false }); // ❌
  page.getByRole('button', { includeHidden: true }); // ✅

• level: number

  Genellikle heading, listitem, row, treeitem rolleri için <h1>-<h6> öğeleri için varsayılan değerlerle bulunan bir sayı özniteliği. Varsayılan olarak, filtre aktif değildir.

  Daha fazla bilgi için aria-level bölümüne bakın.

  <>
    <h1>Başlık Seviye Bir</h1>
    <div role="heading" aria-level="1">
      İkinci Başlık Seviye Bir
    </div>
  </>;
  
  page.getByRole('heading', { level: 1 }); // ✅
  page.getByRole('heading', { level: 2 }); // ❌

• name: string | RegExp

  Erişilebilir bir ad. Varsayılan olarak, eşleştirme büyük/küçük harfe duyarlı değildir ve bir alt dizeyi arar. Bu davranışı kontrol etmek için exact seçeneğini kullanın.

  <button>Bana Tıkla!</button>;
  
  page.getByRole('button', { name: 'Bana Tıkla!' }); // ✅
  page.getByRole('button', { name: 'bana tıkla!' }); // ✅
  page.getByRole('button', { name: 'Bana Tıkla?' }); // ❌

• pressed: boolean

  Basılı öğelerin dahil edilip edilmeyeceği. Varsayılan olarak, filtre aktif değildir.

  Daha fazla bilgi için aria-pressed bölümüne bakın.

  <button aria-pressed="true">👍</button>;
  
  page.getByRole('button', { pressed: true }); // ✅
  page.getByRole('button', { pressed: false }); // ❌

• selected: boolean

  Seçili öğelerin dahil edilip edilmeyeceği. Varsayılan olarak, filtre aktif değildir.

  Daha fazla bilgi için aria-selected bölümüne bakın.

  <button role="tab" aria-selected="true">
    Vue
  </button>;
  
  page.getByRole('button', { selected: true }); // ✅
  page.getByRole('button', { selected: false }); // ❌

Ayrıca bakınız

• MDN'deki ARIA rolleri listesi
• w3.org'daki ARIA rolleri listesi
• testing-library'nin ByRole

getByAltText

function getByAltText(text: string | RegExp, options?: LocatorOptions): Locator;

Belirtilen metinle eşleşen bir alt özniteliğine sahip bir öğeyi bulmak için bir konumlandırıcı oluşturur. testing-library'nin uygulamasının aksine, Vitest eşleşen bir alt özniteliğine sahip herhangi bir öğeyi eşleştirebilir.

<img alt="Incredibles 2 Poster" src="/incredibles-2.png" />;

page.getByAltText(/incredibles.*? poster/i); // ✅
page.getByAltText('olmayan alt metin'); // ❌

Seçenekler

• exact: boolean

  text'in tam olarak eşleştirilip eşleştirilmediği: büyük/küçük harfe duyarlı ve tam dize. Varsayılan olarak kapalıdır. text bir düzenli ifade ise bu seçenek göz ardı edilir. Tam eşleşmenin yine de boşlukları kaldırdığını unutmayın.

Ayrıca bakınız

• testing-library'nin ByAltText

getByLabelText

function getByLabelText(
  text: string | RegExp,
  options?: LocatorOptions
): Locator;

İlişkili bir etiketi bulunan bir öğeyi bulmak için bir konumlandırıcı oluşturur.

page.getByLabelText('Kullanıcı Adı') konumlandırıcısı, aşağıdaki örnekteki tüm girişleri bulacaktır:

<!-- etiket ve form öğesi kimliği arasındaki for/htmlFor ilişkisi -->
<label for="username-input">Kullanıcı Adı</label>
<input id="username-input" />

<!-- Form öğeleriyle aria-labelledby özniteliği -->
<label id="username-label">Kullanıcı Adı</label>
<input aria-labelledby="username-label" />

<!-- Sarmalayıcı etiketler -->
<label>Kullanıcı Adı <input /></label>

<!-- Etiket metninin başka bir alt öğede olduğu sarmalayıcı etiketler -->
<label>
  <span>Kullanıcı Adı</span>
  <input />
</label>

<!-- aria-label attributes -->
<!-- Take care because this is not a label that users can see on the page, -->
<!-- so the purpose of your input must be obvious to visual users. -->
<input aria-label="Kullanıcı Adı" />

Seçenekler

• exact: boolean

  text'in tam olarak eşleştirilip eşleştirilmediği: büyük/küçük harfe duyarlı ve tam dize. Varsayılan olarak kapalıdır. text bir düzenli ifade ise bu seçenek göz ardı edilir. Tam eşleşmenin yine de boşlukları kaldırdığını unutmayın.

Ayrıca bakınız

• testing-library'nin ByLabelText

getByPlaceholder

function getByPlaceholder(
  text: string | RegExp,
  options?: LocatorOptions
): Locator;

Belirtilen placeholder özniteliğine sahip bir öğeyi bulmak için bir konumlandırıcı oluşturur. Vitest, yalnızca input değil, eşleşen bir placeholder özniteliğine sahip herhangi bir öğeyi eşleştirebilir.

<input placeholder="Kullanıcı Adı" />;

page.getByPlaceholder('Kullanıcı Adı'); // ✅
page.getByPlaceholder('bulunamadı'); // ❌

WARNING

Genellikle bir yer tutucudan ziyade getByLabelText kullanarak bir etikete güvenmek daha iyi bir yaklaşımdır.

Seçenekler

• exact: boolean

  text'in tam olarak eşleştirilip eşleştirilmediği: büyük/küçük harfe duyarlı ve tam dize. Varsayılan olarak kapalıdır. text bir düzenli ifade ise bu seçenek göz ardı edilir. Tam eşleşmenin yine de boşlukları kaldırdığını unutmayın.

Ayrıca bakınız

• testing-library'nin ByPlaceholderText

getByText

function getByText(text: string | RegExp, options?: LocatorOptions): Locator;

Belirtilen metni içeren bir öğeyi bulmak için bir konumlandırıcı oluşturur. Metin, TextNode'un nodeValue'suna veya türü button veya reset ise girişin değerine göre eşleştirilecektir. Metne göre eşleştirme, tam eşleşme olsa bile boşlukları her zaman normalleştirir. Örneğin, birden fazla boşluğu tek bir boşluğa dönüştürür, satır sonlarını boşluklara dönüştürür ve baştaki ve sondaki boşlukları göz ardı eder.

<a href="/about">Hakkında ℹ️</a>;

page.getByText(/hakkında/i); // ✅
page.getByText('hakkında', { exact: true }); // ❌

TIP

Bu konumlandırıcı, etkileşimli olmayan öğeleri bulmak için kullanışlıdır. Eğer bir düğme veya giriş gibi etkileşimli bir öğeyi bulmanız gerekiyorsa, getByRole'u tercih etmelisiniz.

Seçenekler

• exact: boolean

  text'in tam olarak eşleştirilip eşleştirilmediği: büyük/küçük harfe duyarlı ve tam dize. Varsayılan olarak kapalıdır. text bir düzenli ifade ise bu seçenek göz ardı edilir. Tam eşleşmenin yine de boşlukları kaldırdığını unutmayın.

Ayrıca bakınız

• testing-library'nin ByText

getByTitle

function getByTitle(text: string | RegExp, options?: LocatorOptions): Locator;

Belirtilen title özniteliğine sahip bir öğeyi bulmak için bir konumlandırıcı oluşturur. testing-library'nin getByTitle'ının aksine, Vitest bir SVG içindeki title öğelerini bulamaz.

<span title="Sil" id="2"></span>;

page.getByTitle('Sil'); // ✅
page.getByTitle('Oluştur'); // ❌

Seçenekler

• exact: boolean

  text'in tam olarak eşleştirilip eşleştirilmediği: büyük/küçük harfe duyarlı ve tam dize. Varsayılan olarak kapalıdır. text bir düzenli ifade ise bu seçenek göz ardı edilir. Tam eşleşmenin yine de boşlukları kaldırdığını unutmayın.

Ayrıca bakınız

• testing-library'nin ByTitle

getByTestId

function getByTestId(text: string | RegExp): Locator;

Belirtilen test kimliği özniteliğiyle eşleşen bir öğeyi bulmak için bir konumlandırıcı oluşturur. Öznitelik adını browser.locators.testIdAttribute ile yapılandırabilirsiniz.

<div data-testid="özel-öğe" />;

page.getByTestId('özel-öğe'); // ✅
page.getByTestId('mevcut-olmayan-öğe'); // ❌

WARNING

Bunu yalnızca diğer konumlandırıcılar kullanım durumunuz için yeterli olmadığında kullanmanız önerilir. data-testid özniteliklerini kullanmak, yazılımınızın gerçek kullanım senaryolarını yansıtmaz ve mümkünse kaçınılmalıdır.

Seçenekler

• exact: boolean

  text'in tam olarak eşleştirilip eşleştirilmediği: büyük/küçük harfe duyarlı ve tam dize. Varsayılan olarak kapalıdır. text bir düzenli ifade ise bu seçenek göz ardı edilir. Tam eşleşmenin yine de boşlukları kaldırdığını unutmayın.

Ayrıca bakınız

• testing-library'nin ByTestId

Yöntemler

Tüm yöntemler eşzamansızdır ve beklenmelidir (await kullanılmalıdır). Vitest 2.2'den itibaren, bir yöntem beklenmezse testler başarısız olacaktır.

click

function click(options?: UserEventClickOptions): Promise<void>;

Bir öğeye tıklar. İmleç konumunu ayarlamak için seçenekleri kullanabilirsiniz.

import { page } from '@vitest/browser/context';

await page.getByRole('img', { name: 'Rose' }).click();

• Daha fazla bilgi için userEvent.click bölümüne bakın

dblClick

function dblClick(options?: UserEventDoubleClickOptions): Promise<void>;

Bir öğede çift tıklama olayını tetikler. İmleç konumunu ayarlamak için seçenekleri kullanabilirsiniz.

import { page } from '@vitest/browser/context';

await page.getByRole('img', { name: 'Rose' }).dblClick();

• Daha fazla bilgi için userEvent.dblClick bölümüne bakın

tripleClick

function tripleClick(options?: UserEventTripleClickOptions): Promise<void>;

Bir öğede üçlü tıklama olayını tetikler. Tarayıcı API'sinde tripleclick olayı bulunmadığı için, bu yöntem art arda üç tıklama olayı tetikleyecektir.

import { page } from '@vitest/browser/context';

await page.getByRole('img', { name: 'Rose' }).tripleClick();

• Daha fazla bilgi için userEvent.tripleClick bölümüne bakın

clear

function clear(): Promise<void>;

Giriş öğesinin içeriğini temizler.

import { page } from '@vitest/browser/context';

await page.getByRole('textbox', { name: 'Tam Adı' }).clear();

• Daha fazla bilgi için userEvent.clear bölümüne bakın

hover

function hover(options?: UserEventHoverOptions): Promise<void>;

İmleç konumunu seçilen öğenin üzerine taşır.

import { page } from '@vitest/browser/context';

await page.getByRole('img', { name: 'Rose' }).hover();

• Daha fazla bilgi için userEvent.hover bölümüne bakın

unhover

function unhover(options?: UserEventHoverOptions): Promise<void>;

Bu, locator.hover ile aynı şekilde çalışır, ancak imleci bunun yerine document.body öğesine taşır.

import { page } from '@vitest/browser/context';

await page.getByRole('img', { name: 'Rose' }).unhover();

• Daha fazla bilgi için userEvent.unhover bölümüne bakın

fill

function fill(text: string, options?: UserEventFillOptions): Promise<void>;

Geçerli input, textarea veya contenteditable öğesinin değerini ayarlar.

import { page } from '@vitest/browser/context';

await page.getByRole('input', { name: 'Tam Adı' }).fill('Mr. Bean');

• Daha fazla bilgi için userEvent.fill bölümüne bakın

dropTo

function dropTo(
  target: Locator,
  options?: UserEventDragAndDropOptions
): Promise<void>;

Geçerli öğeyi hedef konuma sürükler.

import { page } from '@vitest/browser/context';

const paris = page.getByText('Paris');
const france = page.getByText('France');

await paris.dropTo(france);

• Daha fazla bilgi için userEvent.dragAndDrop bölümüne bakın

selectOptions

function selectOptions(
  values: HTMLElement | HTMLElement[] | Locator | Locator[] | string | string[],
  options?: UserEventSelectOptions
): Promise<void>;

Bir <select> öğesinden bir veya daha fazla değer seçer.

import { page } from '@vitest/browser/context';

const languages = page.getByRole('select', { name: 'Diller' });

await languages.selectOptions('EN');
await languages.selectOptions(['ES', 'FR']);
await languages.selectOptions([
  languages.getByRole('option', { name: 'İspanyolca' }),
  languages.getByRole('option', { name: 'Fransızca' }),
]);

• Daha fazla bilgi için userEvent.selectOptions bölümüne bakın

screenshot

function screenshot(
  options: LocatorScreenshotOptions & { base64: true }
): Promise<{
  path: string;
  base64: string;
}>;
function screenshot(
  options?: LocatorScreenshotOptions & { base64?: false }
): Promise<string>;

Konumlandırıcının seçicisiyle eşleşen öğenin ekran görüntüsünü oluşturur.

Ekran görüntüsünün kaydedileceği konumu, geçerli test dosyasına göreli olan path seçeneğini kullanarak belirtebilirsiniz. path seçeneği ayarlanmazsa, Vitest varsayılan olarak browser.screenshotDirectory (__screenshot__ varsayılan olarak) ile birlikte dosya ve test adlarını kullanarak ekran görüntüsünün dosya yolunu belirleyecektir.

Ekran görüntüsünün içeriğine de ihtiyacınız varsa, ekran görüntüsünün kaydedildiği dosya yoluyla birlikte döndürmek için base64: true seçeneğini belirtebilirsiniz.

import { page } from '@vitest/browser/context';

const button = page.getByRole('button', { name: 'Bana Tıkla!' });

const path = await button.screenshot();

const { path, base64 } = await button.screenshot({
  path: './button-click-me.png',
  base64: true, // base64 dizesini de döndür
});
// path - ekran görüntüsünün tam yolu
// bas64 - ekran görüntüsünün base64 kodlu dizesi

query

function query(): Element | null;

Bu yöntem, konumlandırıcının seçicisiyle eşleşen tek bir öğeyi döndürür veya hiçbir öğe bulunamazsa null döndürür.

Seçiciyle birden fazla öğe eşleşirse, bu yöntem bir hata fırlatır. Tüm eşleşen DOM Öğelerine ihtiyacınız olduğunda .elements()'i veya seçiciyle eşleşen konumlandırıcı dizisine ihtiyacınız olduğunda .all()'u kullanın.

Aşağıdaki DOM yapısını göz önünde bulundurun:

<div>Merhaba <span>Dünya</span></div>
<div>Merhaba</div>

Bu konumlandırıcılar hata fırlatmaz:

page.getByText('Merhaba Dünya').query(); // ✅ HTMLDivElement
page.getByText('Merhaba Almanya').query(); // ✅ null
page.getByText('Dünya').query(); // ✅ HTMLSpanElement
page.getByText('Merhaba', { exact: true }).query(); // ✅ HTMLSpanElement

Bu konumlandırıcılar hata fırlatır:

// Birden fazla öğe döndürür
page.getByText('Merhaba').query(); // ❌
page.getByText(/^Merhaba/).query(); // ❌

element

function element(): Element;

Bu yöntem, konumlandırıcının seçicisiyle eşleşen tek bir öğeyi döndürür.

Seçiciyle hiçbir öğe eşleşmezse, bir hata fırlatılır. Öğenin var olup olmadığını kontrol etmeniz gerektiğinde .query()'yi kullanmayı düşünün.

Seçiciyle birden fazla öğe eşleşirse, bir hata fırlatılır. Tüm eşleşen DOM Öğelerine ihtiyacınız olduğunda .elements()'i veya seçiciyle eşleşen konumlandırıcı dizisine ihtiyacınız olduğunda .all()'u kullanın.

TIP

Bu yöntem, harici bir kütüphaneye geçirmeniz gerektiğinde kullanışlı olabilir. Konumlandırıcı expect.element ile her kullanıldığında, onay yeniden denendiğinde otomatik olarak çağrılır:

await expect.element(page.getByRole('button')).toBeDisabled();

Aşağıdaki DOM yapısını göz önünde bulundurun:

<div>Merhaba <span>Dünya</span></div>
<div>Merhaba Almanya</div>
<div>Merhaba</div>

Bu konumlandırıcılar hata fırlatmaz:

page.getByText('Merhaba Dünya').element(); // ✅
page.getByText('Merhaba Almanya').element(); // ✅
page.getByText('Dünya').element(); // ✅
page.getByText('Merhaba', { exact: true }).element(); // ✅

Bu konumlandırıcılar hata fırlatır:

// Birden fazla öğe döndürür
page.getByText('Merhaba').element(); // ❌
page.getByText(/^Merhaba/).element(); // ❌

// Hiçbir öğe döndürmez
page.getByText('Merhaba ABD').element(); // ❌

elements

function elements(): Element[];

Bu yöntem, konumlandırıcının seçicisiyle eşleşen bir öğe dizisi döndürür.

Bu fonksiyon asla hata fırlatmaz. Seçiciyle eşleşen hiçbir öğe yoksa, bu yöntem boş bir dizi döndürür.

Aşağıdaki DOM yapısını göz önünde bulundurun:

<div>Merhaba <span>Dünya</span></div>
<div>Merhaba</div>

Bu konumlandırıcılar her zaman başarılı olacaktır:

page.getByText('Merhaba Dünya').elements(); // ✅ [HTMLElement]
page.getByText('Dünya').elements(); // ✅ [HTMLElement]
page.getByText('Merhaba', { exact: true }).elements(); // ✅ [HTMLElement]
page.getByText('Merhaba').elements(); // ✅ [HTMLElement, HTMLElement]
page.getByText('Merhaba ABD').elements(); // ✅ []

all

function all(): Locator[];

Bu yöntem, seçiciyle eşleşen yeni konumlandırıcıların bir dizisini döndürür.

Dahili olarak, bu yöntem .elements'i çağırır ve her öğeyi page.elementLocator kullanarak sarmalar.

• [Daha fazlası için locator.elements() bölümüne bakın](#elements)