Reactのキーボード操作をuser-eventでテストする方法

​​React​React Testing Library,TypeScript,user-event,Vitest

入力候補を ↓ キーで選んで Enter で決めるオートコンプリートや、Ctrl+Enter で送信するメッセージ欄は、React Testing Library と一緒に使う user-event の user.keyboard() でテストできます。キーボードだけで操作できるか(アクセシビリティ)を Tab キーの移動順で確かめるには、user.tab() を使います。{Shift>}A{/Shift} のようなキーの書き方と、テストが通らないときによくある原因を、実際にテストを動かして確かめました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。使ったのは vitest 5.1.0、jsdom 31.0.0、@testing-library/react 16.3.3、@testing-library/dom 10.4.2、@testing-library/user-event 14.6.9、@testing-library/jest-dom 7.0.1、react / react-dom 19.3.1、typescript 7.0.2 です。日本語入力(IME)の変換中の操作、keyboardMap で別の配列のキーボードにする設定、実際のブラウザーでテストを動かすモードは試していません。

キーの書き方

user-event の keyboard() の説明にある書き方を、表にまとめます。文字はそのまま書き、Enter や矢印キーのような文字でないキーは {} で囲みます。

書き方 意味
'abc' a、b、c を順に押して離す
'{Enter}'、'{ArrowDown}' キーの名前(KeyboardEvent.key の値)で押す
'[KeyA]'、'[ShiftLeft]' キーの位置(KeyboardEvent.code の値)で押す
'{Shift>}' 押したままにする
'{/Shift}' 押したままのキーを離す
'{ArrowDown>3/}' 押したまま keydown を3回出し、最後に離す
'{{'、'[[' 文字の {、[ を入力する

組み合わせのキーは、「押したままにする」と「離す」で挟みます。Shift を押しながら A を押すなら '{Shift>}A{/Shift}'、Ctrl+Enter なら '{Control>}{Enter}{/Control}' です。

'{Shift>}A{/Shift}' で、入力欄にどんなイベントが届くかを記録すると、次の図のようになりました。Shift を押している間に出た A の keydown・keypress・keyup は、どれも shiftKey が true です。Shift の keyup では false に戻りました。

user.keyboard('{Shift>}A{/Shift}') で出たイベントの順番。Shift の keydown、A の keydown・keypress・keyup が shiftKey: true で出て、その間に beforeinput と input が出る。最後の Shift の keyup だけ shiftKey: false になる
{Shift>}A{/Shift} で入力欄に届いたイベントの順番

Ctrl の組み合わせでも、押している間のイベントは ctrlKey が true になりました。値が aA(2文字)の入力欄で '{Control>}a{/Control}' を押すと、keypress と input は出ず、文字が全部選ばれた状態(選択範囲が 0〜2)になりました。別のテストで、文字の入った欄に '{Control>}a{/Control}{Backspace}' を押すと、全部選んだあとで消され、入力欄は空になりました。

オートコンプリートの候補を ↓ と Enter で選ぶ

テストするのは、果物の名前を入れる欄です。↓ と ↑ で候補を選び、Enter で決定し、Escape で候補を閉じます。

tsx
// src/FruitCombobox.tsx
import { useState, type KeyboardEvent } from 'react';

const fruits = ['りんご', 'みかん', 'ぶどう'];

// ↓↑で候補を選び、Enterで決定、Escapeで閉じる入力欄
export function FruitCombobox() {
  const [value, setValue] = useState('');
  const [open, setOpen] = useState(false);
  const [active, setActive] = useState(-1);

  const onKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
    if (e.key === 'ArrowDown') {
      e.preventDefault();
      setOpen(true);
      setActive((i) => Math.min(i + 1, fruits.length - 1));
    } else if (e.key === 'ArrowUp') {
      e.preventDefault();
      setActive((i) => Math.max(i - 1, 0));
    } else if (e.key === 'Enter' && open && active >= 0) {
      e.preventDefault();
      setValue(fruits[active]);
      setOpen(false);
    } else if (e.key === 'Escape') {
      setOpen(false);
      setActive(-1);
    }
  };

  return (
    <div>
      <label htmlFor="fruit">果物</label>
      <input
        id="fruit"
        role="combobox"
        aria-expanded={open}
        aria-controls="fruit-list"
        aria-activedescendant={open && active >= 0 ? `fruit-${active}` : undefined}
        value={value}
        onChange={(e) => setValue(e.target.value)}
        onKeyDown={onKeyDown}
      />
      {open && (
        <ul id="fruit-list" role="listbox">
          {fruits.map((f, i) => (
            <li key={f} id={`fruit-${i}`} role="option" aria-selected={i === active}>
              {f}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Vitest の設定では、環境を jsdom にし、次の setup ファイルを読み込んでいます。toHaveFocus() などを使うために @testing-library/jest-dom/vitest を読み込み、テストごとに cleanup() を呼んで、render() で描画した内容を片づけます。

ts
// src/setup.ts
import '@testing-library/jest-dom/vitest';
import { cleanup } from '@testing-library/react';
import { afterEach } from 'vitest';

afterEach(() => {
  cleanup();
});

テストでは、まず userEvent.setup() で操作用の user を作ります。user.keyboard() は、いまフォーカスがある要素に向けてキーを押すので、先に user.click() で入力欄にフォーカスを移します。

tsx
// src/FruitCombobox.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { expect, test } from 'vitest';
import { FruitCombobox } from './FruitCombobox';

test('↓を2回押して Enter で「みかん」を選ぶ', async () => {
  const user = userEvent.setup();
  render(<FruitCombobox />);
  const input = screen.getByRole('combobox', { name: '果物' });

  await user.click(input);
  await user.keyboard('{ArrowDown}{ArrowDown}');
  expect(screen.getByRole('option', { name: 'みかん' })).toHaveAttribute('aria-selected', 'true');
  expect(input).toHaveAttribute('aria-activedescendant', 'fruit-1');

  await user.keyboard('{Enter}');
  expect(input).toHaveValue('みかん');
  expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
});

test('↓を押したままにして、3回分進める', async () => {
  const user = userEvent.setup();
  render(<FruitCombobox />);
  await user.click(screen.getByRole('combobox'));

  await user.keyboard('{ArrowDown>3/}');
  expect(screen.getByRole('option', { name: 'ぶどう' })).toHaveAttribute('aria-selected', 'true');
});

test('Escape で候補を閉じる', async () => {
  const user = userEvent.setup();
  render(<FruitCombobox />);
  await user.click(screen.getByRole('combobox'));
  await user.keyboard('{ArrowDown}');
  expect(screen.getByRole('listbox')).toBeInTheDocument();

  await user.keyboard('{Escape}');
  expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
  expect(screen.getByRole('combobox')).toHaveAttribute('aria-expanded', 'false');
});

3つとも通りました。{ArrowDown>3/} は、キーを押しっぱなしにして keydown が続けて出る様子をまねる書き方で、↓ を3回押したのと同じく「ぶどう」まで進みました。

Ctrl+Enter で送信するメッセージ欄

Enter だけなら改行し、Ctrl+Enter(Mac では ⌘+Enter)で送信するメッセージ欄です。

tsx
// src/MessageBox.tsx
import { useState } from 'react';

// Ctrl+Enter(Mac は ⌘+Enter)で送信し、Enter だけなら改行する
export function MessageBox({ onSend }: { onSend: (text: string) => void }) {
  const [text, setText] = useState('');

  return (
    <textarea
      aria-label="メッセージ"
      value={text}
      onChange={(e) => setText(e.target.value)}
      onKeyDown={(e) => {
        if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
          e.preventDefault();
          onSend(text);
          setText('');
        }
      }}
    />
  );
}

文字の入力には user.type() を使いました。type() は、要素をクリックしてから、2番目の引数を keyboard() と同じ書き方で入力します。そのため、文字の途中に {Enter} を書けます。

tsx
// src/MessageBox.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { expect, test, vi } from 'vitest';
import { MessageBox } from './MessageBox';

test('Enter だけなら改行し、Ctrl+Enter で送信する', async () => {
  const user = userEvent.setup();
  const onSend = vi.fn();
  render(<MessageBox onSend={onSend} />);
  const box = screen.getByRole('textbox', { name: 'メッセージ' });

  await user.type(box, 'こんにちは{Enter}またね');
  expect(box).toHaveValue('こんにちは\nまたね');
  expect(onSend).not.toHaveBeenCalled();

  await user.keyboard('{Control>}{Enter}{/Control}');
  expect(onSend).toHaveBeenCalledWith('こんにちは\nまたね');
  expect(box).toHaveValue('');
});

test('Mac の ⌘+Enter でも送信する', async () => {
  const user = userEvent.setup();
  const onSend = vi.fn();
  render(<MessageBox onSend={onSend} />);

  await user.type(screen.getByRole('textbox'), 'hi');
  await user.keyboard('{Meta>}{Enter}{/Meta}');
  expect(onSend).toHaveBeenCalledWith('hi');
});

どちらも通りました。⌘ キーを {Meta} で押したところ、送信されました。type() のあとはフォーカスがメッセージ欄に残っているので、続く keyboard() では、クリックし直さなくても Ctrl+Enter がメッセージ欄に届きました。

Tab キーでの移動順と、Enter・Space でのフォーム操作

キーボードだけでログインできるかを、次のフォームで確かめます。

tsx
// src/LoginForm.tsx
import { useState, type FormEvent } from 'react';

export function LoginForm({ onSubmit }: { onSubmit: (email: string) => void }) {
  const [email, setEmail] = useState('');

  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    onSubmit(email);
  };

  return (
    <form onSubmit={handleSubmit}>
      <label>
        メールアドレス
        <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
      </label>
      <label>
        パスワード
        <input type="password" />
      </label>
      <label>
        <input type="checkbox" />
        ログインしたままにする
      </label>
      <button type="submit">ログイン</button>
    </form>
  );
}

Tab キーは user.tab() で押します。user.tab({ shift: true }) は Shift+Tab です。フォーカスがどこにあるかは、jest-dom の toHaveFocus() で確かめます。import は前のテストと同じなので省きます(読み込むのは LoginForm)。

tsx
test('Tab で上から順にフォーカスが移り、Shift+Tab で戻る', async () => {
  const user = userEvent.setup();
  render(<LoginForm onSubmit={() => {}} />);

  await user.tab();
  expect(screen.getByLabelText('メールアドレス')).toHaveFocus();
  await user.tab();
  expect(screen.getByLabelText('パスワード')).toHaveFocus();
  await user.tab();
  expect(screen.getByRole('checkbox')).toHaveFocus();
  await user.tab();
  expect(screen.getByRole('button', { name: 'ログイン' })).toHaveFocus();

  await user.tab({ shift: true });
  expect(screen.getByRole('checkbox')).toHaveFocus();
});

test('チェックボックスは Space で切り替わる', async () => {
  const user = userEvent.setup();
  render(<LoginForm onSubmit={() => {}} />);
  await user.tab();
  await user.tab();
  await user.tab();
  await user.keyboard(' ');
  expect(screen.getByRole('checkbox')).toBeChecked();
});

test('入力欄で Enter を押すとフォームが送信される', async () => {
  const user = userEvent.setup();
  const onSubmit = vi.fn();
  render(<LoginForm onSubmit={onSubmit} />);

  await user.type(screen.getByLabelText('メールアドレス'), 'neko@example.com{Enter}');
  expect(onSubmit).toHaveBeenCalledWith('neko@example.com');
});

3つとも通りました。Space は、文字の半角スペース ' ' で押せます。チェックボックスにフォーカスがある状態で押すと、チェックが入りました。入力欄で Enter を押したときは、フォームが送信され、onSubmit が呼ばれました。

キーボードのテストが通らないときの原因

フォーカスを移していない

render() のあと、どこもクリックせずに user.keyboard('{ArrowDown}') を呼ぶと、候補の一覧は出ず、テストは失敗しました。

tsx
test('フォーカスしないで keyboard を呼ぶ', async () => {
  const user = userEvent.setup();
  render(<FruitCombobox />);
  await user.keyboard('{ArrowDown}');
  console.log('フォーカスがある要素:', document.activeElement?.tagName);
  expect(screen.getByRole('listbox')).toBeInTheDocument();
});

出力の一部を抜き出しています。

text
stdout | src/pitfall-no-focus.test.tsx > フォーカスしないで keyboard を呼ぶ
フォーカスがある要素: BODY

 FAIL  src/pitfall-no-focus.test.tsx > フォーカスしないで keyboard を呼ぶ
TestingLibraryElementError: Unable to find an accessible element with the role "listbox"

フォーカスは body にあり、↓ キーは入力欄の onKeyDown に届いていませんでした。keyboard() は要素を引数に取らないので、user.click() か user.tab() でフォーカスを移してから呼びます。

{ をそのまま書いた

{ と [ は、キーの名前を書き始める記号です。1つだけ書くと、入力されずにエラーになりました。

text
 FAIL  src/pitfall-brace.test.tsx > { を1つだけ書く
Error: Expected key descriptor but found "" in "{"
    See https://testing-library.com/docs/user-event/keyboard
    for more information about how userEvent parses your input.

文字として入れたいときは、'{{a[[' のように2つ重ねます。この書き方で入力欄の値は {a[ になりました。JSON の文字列のように { を含む値を type() で入れるときも、同じように重ねます。

fireEvent.keyDown では、ブラウザーの動きが起きない

fireEvent.keyDown() は、keydown イベントを1つ出すだけです(fireEvent は @testing-library/react から読み込みます)。入力欄やログインボタンに fireEvent.keyDown(要素, { key: 'Enter' }) を出しても、フォームは送信されず、onSubmit は一度も呼ばれませんでした。

tsx
test('fireEvent.keyDown の Enter では、フォームは送信されない', () => {
  const onSubmit = vi.fn();
  render(<LoginForm onSubmit={onSubmit} />);
  fireEvent.keyDown(screen.getByLabelText('メールアドレス'), { key: 'Enter', code: 'Enter' });
  const button = screen.getByRole('button', { name: 'ログイン' });
  button.focus();
  fireEvent.keyDown(button, { key: 'Enter', code: 'Enter' });
  expect(onSubmit).not.toHaveBeenCalled();
});

test('user.keyboard の Enter なら、フォームが送信される', async () => {
  const user = userEvent.setup();
  const onSubmit = vi.fn();
  render(<LoginForm onSubmit={onSubmit} />);
  screen.getByRole('button', { name: 'ログイン' }).focus();
  await user.keyboard('{Enter}');
  expect(onSubmit).toHaveBeenCalledTimes(1);
});

同じボタンにフォーカスして user.keyboard('{Enter}') を呼ぶと、フォームが送信されました。user-event の説明にある fireEvent との違いのとおり、fireEvent は DOM のイベントを1つ出すだけで、user-event は、ブラウザーでの操作と同じように、いくつものイベントを出したり DOM を変えたりします。Enter でのフォームの送信や、Space でのチェックボックスの切り替えまで確かめたいときは、fireEvent ではなく user-event を使います。

​Posted by 86