Etkileşim API'si

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

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

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

Hemen hemen her userEvent yöntemi, sağlayıcı seçeneklerini devralır. IDE'nizde mevcut tüm seçenekleri görmek için, kurulum dosyanıza veya bir yapılandırma dosyanıza ( tsconfig.json dosyanızın included bölümündeki içeriğe bağlı olarak) webdriver veya playwright türlerini (sağlayıcınıza bağlı olarak) ekleyin:

playwright

/// <reference types="@vitest/browser/providers/playwright" />

webdriverio

/// <reference types="@vitest/browser/providers/webdriverio" />

userEvent.setup

function setup(): UserEvent;

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

WARNING

@testing-library/user-event'ın 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 kod parçasında nasıl çalıştığının farkını 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, serbest bırakmaz
await vitestUserEvent.keyboard('{/Shift}'); // Shift'i serbest bırakır

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

Bu davranış daha kullanışlıdır çünkü klavyeyi taklit etmiyoruz; aslında Shift'e basıyoruz. Bu nedenle, orijinal davranışı sürdürmek, alana yazım sırasında beklenmedik sorunlara yol açabilir.

userEvent.click

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

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

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

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

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

Referanslar:

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

userEvent.dblClick

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

Bir öğede çift tıklama etkinliğini tetikler.

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

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 belirleyici üzerinden erişebilirsiniz
  await logo.dblClick();
});

Referanslar:

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

userEvent.tripleClick

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

Bir öğede üçlü tıklama olayını tetikler. Tarayıcı API'sında tripleclick (üçlü tıklama) bulunmadığından, bu yöntem art arda üç tıklama olayı tetikleyecektir ve 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ı açıklama için lütfen sağlayıcınızın belgelerine bakın.

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 belirleyici üzerinden erişebilirsiniz
  await logo.tripleClick();

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

Referanslar:

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

userEvent.fill

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

input/textarea/contenteditable alanına bir değer ayarlar. Bu, yeni değeri ayarlamadan önce giriş alanındaki mevcut metni kaldıracaktır.

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

test('girişi güncelle', 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 belirleyici üzerinden erişebilirsiniz
  await input.fill('foo'); // input.value == foo
});

Bu yöntem öğeyi odaklar, doldurur ve doldurduktan sonra bir input (giriş) olayı 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'ın keyboard sözdizimini (örn. {Shift}{selectall}) desteklemez.

Özel karakterler girmeniz veya tuş basma olayları üzerinde ayrıntılı kontrole ihtiyacınız olmadığında bu API'yi userEvent.type yerine kullanmanızı öneririz.

Referanslar:

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

userEvent.keyboard

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

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

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

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

test('tuş basışlarını tetikle', async () => {
  await userEvent.keyboard('foo'); // yani: f, o, o
  await userEvent.keyboard('{{a[['); // yani: {, a, [
  await userEvent.keyboard('{Shift}{f}{o}{o}'); // yani: Shift, f, o, o
  await userEvent.keyboard('{a>5}'); // a'ya basar, serbest bırakmaz ve 5 kez tuş basma (keydown) olayı tetikler
  await userEvent.keyboard('{a>5/}'); // a'ya 5 kez tuş basma (keydown) olayı uygular ve sonra bırakır
});

Referanslar:

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

userEvent.tab

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

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

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

test('sekme tuşu çalışıyor', 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
• WebdriverIO action('key') API
• testing-library tab API

userEvent.type

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

WARNING

Özel karakterlere (örn. {shift} veya {selectall}) ihtiyaç duymuyorsanız, daha iyi performans için bunun yerine userEvent.fill kullanmanız önerilir.

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

Bu işlev, bir input/textarea/contenteditable öğesine karakterler yazmanızı sağlar. User-event'ın keyboard sözdizimini destekler.

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

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

test('girişi güncelle', 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 açığa çıkarmaz çü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
• WebdriverIO action('key') API
• testing-library type API

userEvent.clear

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

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

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

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

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

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

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

Referanslar:

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

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'ı desteklemiyor, ancak gelecekte destek eklemeyi planlıyoruz.

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

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

  await userEvent.selectOptions(select, 'Option 1');
  // veya doğrudan konum belirleyici üzerinden 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 API sağlamadığı için birden fazla öğe seçmeyi desteklemez.

Referanslar:

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

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ığına dair ayrıntılı açıklama için lütfen sağlayıcınızın belgelerine bakın.

WARNING

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

playwright sağlayıcısını kullanıyorsanız, imleç öğenin "görünür" bir 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 belirleyici üzerinden erişebilirsiniz
  await logo.hover();
});

Referanslar:

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

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 "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 belirleyici üzerinden erişebilirsiniz
  await logo.unhover();
});

Referanslar:

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

userEvent.upload

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

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

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

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

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

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

  // ayrıca projenin köküne göre 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
• WebdriverIO browser.uploadFile API
• testing-library upload API

userEvent.dragAndDrop

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

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

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

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

  await userEvent.dragAndDrop(source, target);
  // veya doğrudan konum belirleyici üzerinden 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
• WebdriverIO element.dragAndDrop API

userEvent.copy

function copy(): Promise<void>;

Seçili metni panoya kopyalar.

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

test('kopyala ve yapıştır', async () => {
  // 'kaynak'a yaz
  await userEvent.click(page.getByPlaceholder('kaynak'));
  await userEvent.keyboard('merhaba');

  // 'kaynak'ı seç ve kopyala
  await userEvent.dblClick(page.getByPlaceholder('kaynak'));
  await userEvent.copy();

  // 'hedef'e yapıştır
  await userEvent.click(page.getByPlaceholder('hedef'));
  await userEvent.paste();

  await expect
    .element(page.getByPlaceholder('kaynak'))
    .toHaveTextContent('merhaba');
  await expect
    .element(page.getByPlaceholder('hedef'))
    .toHaveTextContent('merhaba');
});

Referanslar:

• testing-library copy API

userEvent.cut

function cut(): Promise<void>;

Seçili metni panoya keser.

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

test('kopyala ve yapıştır', async () => {
  // 'kaynak'a yaz
  await userEvent.click(page.getByPlaceholder('kaynak'));
  await userEvent.keyboard('merhaba');

  // 'kaynak'ı seç ve kes
  await userEvent.dblClick(page.getByPlaceholder('kaynak'));
  await userEvent.cut();

  // 'hedef'e yapıştır
  await userEvent.click(page.getByPlaceholder('hedef'));
  await userEvent.paste();

  await expect.element(page.getByPlaceholder('kaynak')).toHaveTextContent('');
  await expect
    .element(page.getByPlaceholder('hedef'))
    .toHaveTextContent('merhaba');
});

Referanslar:

• testing-library cut API

userEvent.paste

function paste(): Promise<void>;

Metni panodan yapıştırır. Kullanım örnekleri için userEvent.copy ve userEvent.cut bölümlerine bakın.

Referanslar:

• testing-library paste API