Etkileşim API'si

Vitest, olayları taklit etmek yerine Chrome DevTools Protokolü veya webdriver kullanarak @testing-library/user-event API'lerinin bir alt kümesini uygular. Bu yaklaşım, tarayıcı davranışını daha güvenilir hale getirir ve kullanıcıların bir sayfayla etkileşim kurma şekliyle daha tutarlı olmasını sağlar.

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

await userEvent.click(document.querySelector('.button'));

Neredeyse her userEvent yöntemi, sağlayıcısının seçeneklerini devralır. IDE'nizde mevcut tüm seçenekleri görmek için, tsconfig.json dosyanıza webdriver veya playwright türlerini (sağlayıcınıza bağlı olarak) ekleyin:

playwright

{
  "compilerOptions": {
    "types": ["@vitest/browser/providers/playwright"]
  }
}

webdriverio

{
  "compilerOptions": {
    "types": ["@vitest/browser/providers/webdriverio"]
  }
}

userEvent.setup

function setup(): UserEvent;

Yeni bir user event örneği oluşturur. Bu, tuşlara doğru bir şekilde basıp bırakmak için klavye durumunu korumanız gerektiğinde faydalıdır.

WARNING

@testing-library/user-event'in aksine, @vitest/browser/context'ten gelen varsayılan userEvent örneği, yöntemleri her çağrıldığında değil, bir kez oluşturulur! Bu snippet'te nasıl çalıştığı arasındaki farkı görebilirsiniz:

import { userEvent as vitestUserEvent } from '@vitest/browser/context';
import { userEvent as originalUserEvent } from '@testing-library/user-event';

await vitestUserEvent.keyboard('{Shift}'); // Shift tuşuna basar, bırakmaz
await vitestUserEvent.keyboard('{/Shift}'); // Shift tuşunu bırakır

await originalUserEvent.keyboard('{Shift}'); // Shift tuşuna basar, bırakmaz
await originalUserEvent.keyboard('{/Shift}'); // Shift tuşunu BIRAKMADI çünkü durum farklı

Bu davranış daha kullanışlıdır çünkü klavyeyi taklit etmiyoruz; aslında Shift tuşuna basıyoruz. Bu nedenle, orijinal davranışı korumak, alana yazarken beklenmedik sorunlara yol açabilirdi.

userEvent.click

function click(
  element: Element | Locator,
  options?: UserEventClickOptions
): Promise<void>;

Bir öğeye tıklar. Sağlayıcısının seçeneklerini devralır. Bu yöntemin nasıl çalıştığına dair ayrıntılı bilgi için lütfen sağlayıcınızın belgelerine başvurun.

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

test('bir öğeye tıklar', async () => {
  const logo = page.getByRole('img', { name: /logo/ });

  await userEvent.click(logo);
  // veya doğrudan konum belirleyiciden erişebilirsiniz
  await logo.click();
});

Referanslar:

• Playwright locator.click API'si
• WebdriverIO element.click API'si
• testing-library click API'si

userEvent.dblClick

function dblClick(
  element: Element | Locator,
  options?: UserEventDoubleClickOptions
): Promise<void>;

Bir öğede çift tıklama olayını tetikler.

Bu yöntemin nasıl çalıştığına dair ayrıntılı bilgi için lütfen sağlayıcınızın belgelerine başvurun.

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

test('bir öğede çift tıklama tetikler', async () => {
  const logo = page.getByRole('img', { name: /logo/ });

  await userEvent.dblClick(logo);
  // veya doğrudan konum belirleyiciden erişebilirsiniz
  await logo.dblClick();
});

Referanslar:

• Playwright locator.dblclick API'si
• WebdriverIO element.doubleClick API'si
• testing-library dblClick API'si

userEvent.tripleClick

function tripleClick(
  element: Element | Locator,
  options?: UserEventTripleClickOptions
): Promise<void>;

Bir öğede üçlü tıklama olayını tetikler. Tarayıcı API'sinde tripleclick olmadığı için, bu yöntem art arda üç tıklama olayı tetikleyecektir. Bu nedenle, olayı filtrelemek için tıklama olayı ayrıntısını kontrol etmeniz gerekir: evt.detail === 3.

Bu yöntemin nasıl çalıştığına dair ayrıntılı bilgi için lütfen sağlayıcınızın belgelerine başvurun.

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

test('bir öğede üçlü tıklama tetikler', async () => {
  const logo = page.getByRole('img', { name: /logo/ });
  let tripleClickFired = false;
  logo.addEventListener('click', evt => {
    if (evt.detail === 3) {
      tripleClickFired = true;
    }
  });

  await userEvent.tripleClick(logo);
  // veya doğrudan konum belirleyiciden erişebilirsiniz
  await logo.tripleClick();

  expect(tripleClickFired).toBe(true);
});

Referanslar:

• Playwright locator.click API'si: clickCount: 3 ile click aracılığıyla uygulanır.
• WebdriverIO browser.action API'si: move artı art arda üç down + up + pause olayı ile eylemler API'si aracılığıyla uygulanır
• testing-library tripleClick API'si

userEvent.fill

function fill(element: Element | Locator, text: string): Promise<void>;

input, textarea veya conteneditable alanına bir değer ayarlayın. Bu, yeni değeri ayarlamadan önce girişteki mevcut metni kaldırır.

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

test('girişi günceller', async () => {
  const input = page.getByRole('input');

  await userEvent.fill(input, 'foo'); // input.value == foo
  await userEvent.fill(input, '{{a[['); // input.value == {{a[[
  await userEvent.fill(input, '{Shift}'); // input.value == {Shift}

  // veya doğrudan konum belirleyiciden erişebilirsiniz
  await input.fill('foo'); // input.value == foo
});

Bu yöntem, öğeye odaklanır, doldurur ve doldurma işleminden sonra bir input olayını tetikler. Alanı temizlemek için boş bir dize kullanabilirsiniz.

TIP

Bu API, userEvent.type veya userEvent.keyboard kullanmaktan daha hızlıdır, ancak user-event keyboard sözdizimini (örneğin, {Shift}{selectall}) desteklemez.

Özel karakterler girmeniz veya tuş basma olayları üzerinde ayrıntılı kontrole sahip olmanız gerekmediğinde, userEvent.type yerine bu API'yi kullanmanızı öneririz.

Referanslar:

• Playwright locator.fill API'si
• WebdriverIO element.setValue API'si
• testing-library type API'si

userEvent.keyboard

function keyboard(text: string): Promise<void>;

userEvent.keyboard, klavye vuruşlarını tetiklemenizi sağlar. Herhangi bir giriş odaklanmışsa, o girişe karakterleri yazar. Aksi takdirde, şu anda odaklanmış öğede (odaklanmış öğe yoksa document.body) klavye olaylarını tetikler.

Bu API, user-event keyboard sözdizimini destekler.

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

test('tuş vuruşlarını tetikler', async () => {
  await userEvent.keyboard('foo'); // şuna çevrilir: f, o, o
  await userEvent.keyboard('{{a[['); // şuna çevrilir: {, a, [
  await userEvent.keyboard('{Shift}{f}{o}{o}'); // şuna çevrilir: Shift, f, o, o
  await userEvent.keyboard('{a>5}'); // a tuşuna basar, bırakmaz ve 5 `keydown` olayı tetikler
  await userEvent.keyboard('{a>5/}'); // a tuşuna 5 `keydown` olayı basar ve sonra bırakır
});

Referanslar:

• Playwright Keyboard API'si
• WebdriverIO action('key') API'si
• testing-library type API'si

userEvent.tab

function tab(options?: UserEventTabOptions): Promise<void>;

Bir Tab tuşu olayı gönderir. Bu, userEvent.keyboard('{tab}') için bir kısaltmadır.

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

test('Tab tuşu çalışır', async () => {
  const [input1, input2] = page.getByRole('input').elements();

  expect(input1).toHaveFocus();

  await userEvent.tab();

  expect(input2).toHaveFocus();

  await userEvent.tab({ shift: true });

  expect(input1).toHaveFocus();
});

Referanslar:

• Playwright Keyboard API'si
• WebdriverIO action('key') API'si
• testing-library tab API'si

userEvent.type

function type(
  element: Element | Locator,
  text: string,
  options?: UserEventTypeOptions
): Promise<void>;

WARNING

Özel karakterlere (örneğin, {shift} veya {selectall}) ihtiyacınız yoksa, daha iyi performans için bunun yerine userEvent.fill kullanılması önerilir.

type yöntemi, keyboard API'si üzerine kurulu @testing-library/user-event'in type yardımcı programını uygular.

Bu fonksiyon, bir input, textarea veya conteneditable öğesine karakterleri yazmanızı sağlar. user-event keyboard sözdizimini destekler.

Sadece bir giriş olmadan karakterlere basmanız gerekiyorsa, userEvent.keyboard API'sini kullanın.

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

test('girişi günceller', async () => {
  const input = page.getByRole('input');

  await userEvent.type(input, 'foo'); // input.value == foo
  await userEvent.type(input, '{{a[['); // input.value == foo{a[
  await userEvent.type(input, '{Shift}'); // input.value == foo{a[
});

INFO

Vitest, input.type gibi konum belirleyicide .type yöntemini kullanıma sunmaz çünkü bu yalnızca userEvent kitaplığıyla uyumluluk için mevcuttur. Bunun yerine daha hızlı olduğu için .fill kullanmayı düşünün.

Referanslar:

• Playwright locator.press API'si
• WebdriverIO action('key') API'si
• testing-library type API'si

userEvent.clear

function clear(element: Element | Locator): Promise<void>;

Bu yöntem, giriş öğesinin içeriğini temizler.

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

test('girişi temizler', async () => {
  const input = page.getByRole('input');

  await userEvent.fill(input, 'foo');
  expect(input).toHaveValue('foo');

  await userEvent.clear(input);
  // veya doğrudan konum belirleyiciden erişebilirsiniz
  await input.clear();

  expect(input).toHaveValue('');
});

Referanslar:

• Playwright locator.clear API'si
• WebdriverIO element.clearValue API'si
• testing-library clear API'si

userEvent.selectOptions

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

userEvent.selectOptions, bir <select> öğesinde bir değer seçmenizi sağlar.

WARNING

Seçim öğesinde multiple özniteliği yoksa, Vitest dizideki yalnızca ilk öğeyi seçecektir.

@testing-library'nin aksine, Vitest şu anda listbox'u desteklemiyor, ancak gelecekte destek eklemeyi planlıyoruz.

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

test('girişi temizler', async () => {
  const select = page.getByRole('select');

  await userEvent.selectOptions(select, 'Option 1');
  // veya doğrudan konum belirleyiciden erişebilirsiniz
  await select.selectOptions('Option 1');

  expect(select).toHaveValue('option-1');

  await userEvent.selectOptions(select, 'option-1');
  expect(select).toHaveValue('option-1');

  await userEvent.selectOptions(select, [
    page.getByRole('option', { name: 'Option 1' }),
    page.getByRole('option', { name: 'Option 2' }),
  ]);
  expect(select).toHaveValue(['option-1', 'option-2']);
});

WARNING

webdriverio sağlayıcısı, bunu yapmak için bir API sağlamadığı için birden çok öğe seçmeyi desteklemez.

Referanslar:

• Playwright locator.selectOption API'si
• WebdriverIO element.selectByIndex API'si
• testing-library selectOptions API'si

userEvent.hover

function hover(
  element: Element | Locator,
  options?: UserEventHoverOptions
): Promise<void>;

Bu yöntem, imleç konumunu seçilen öğeye taşır. Bu yöntemin nasıl çalıştığı hakkında ayrıntılı bilgi için lütfen sağlayıcınızın belgelerine başvurun.

WARNING

webdriverio sağlayıcısını kullanıyorsanız, imleç varsayılan olarak öğenin merkezine hareket eder.

playwright sağlayıcısını kullanıyorsanız, imleç öğenin "bazı" görünür noktasına hareket eder.

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

test('logo öğesinin üzerine gelir', async () => {
  const logo = page.getByRole('img', { name: /logo/ });

  await userEvent.hover(logo);
  // veya doğrudan konum belirleyiciden erişebilirsiniz
  await logo.hover();
});

Referanslar:

• Playwright locator.hover API'si
• WebdriverIO element.moveTo API'si
• testing-library hover API'si

userEvent.unhover

function unhover(
  element: Element | Locator,
  options?: UserEventHoverOptions
): Promise<void>;

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

WARNING

Varsayılan olarak, imleç konumu "bazı" görünür bir yerdedir (playwright sağlayıcısında) veya gövde öğesinin merkezindedir (webdriverio sağlayıcısında). Bu nedenle, şu anda üzerine gelinen öğe zaten aynı konumdaysa, bu yöntemin hiçbir etkisi olmayacaktır.

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

test('logo öğesinin üzerine gelmeyi bırakır', async () => {
  const logo = page.getByRole('img', { name: /logo/ });

  await userEvent.unhover(logo);
  // veya doğrudan konum belirleyiciden erişebilirsiniz
  await logo.unhover();
});

Referanslar:

• Playwright locator.hover API'si
• WebdriverIO element.moveTo API'si
• testing-library hover API'si

userEvent.upload

function upload(
  element: Element | Locator,
  files: string[] | string | File[] | File
): Promise<void>;

Bir dosya giriş öğesini belirtilen dosyalara sahip olacak şekilde değiştirir.

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

test('bir dosya yükleyebilir', async () => {
  const input = page.getByRole('button', { name: /Dosya yükle/ });

  const file = new File(['file'], 'file.png', { type: 'image/png' });

  await userEvent.upload(input, file);
  // veya doğrudan konum belirleyiciden erişebilirsiniz
  await input.upload(file);

  // test dosyasına göreceli dosya yollarını da kullanabilirsiniz
  await userEvent.upload(input, '../fixtures/file.png');
});

WARNING

webdriverio sağlayıcısı bu komutu yalnızca chrome ve edge tarayıcılarında destekler. Ayrıca şu anda yalnızca dize türlerini destekler.

Referanslar:

• Playwright locator.setInputFiles API'si
• WebdriverIO browser.uploadFile API'si
• testing-library upload API'si

userEvent.dragAndDrop

function dragAndDrop(
  source: Element | Locator,
  target: Element | Locator,
  options?: UserEventDragAndDropOptions
): Promise<void>;

Kaynak öğeyi hedef öğenin üzerine sürükler. Kaynak öğesinin draggable özniteliğinin true olarak ayarlanması gerektiğini unutmayın.

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

test('sürükle-bırak çalışır', async () => {
  const source = page.getByRole('img', { name: /logo/ });
  const target = page.getByTestId('logo-target');

  await userEvent.dragAndDrop(source, target);
  // veya doğrudan konum belirleyiciden erişebilirsiniz
  await source.dropTo(target);

  await expect.element(target).toHaveTextContent('Logo işlendi');
});

WARNING

Bu API, varsayılan preview sağlayıcısı tarafından desteklenmemektedir.

Referanslar:

• Playwright frame.dragAndDrop API'si
• WebdriverIO element.dragAndDrop API'si