Reactのキーボード操作をuser-eventでテストする方法
入力候補を ↓ キーで選んで 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 に戻りました。

Ctrl の組み合わせでも、押している間のイベントは ctrlKey が true になりました。値が aA(2文字)の入力欄で '{Control>}a{/Control}' を押すと、keypress と input は出ず、文字が全部選ばれた状態(選択範囲が 0〜2)になりました。別のテストで、文字の入った欄に '{Control>}a{/Control}{Backspace}' を押すと、全部選んだあとで消され、入力欄は空になりました。
オートコンプリートの候補を ↓ と Enter で選ぶ
テストするのは、果物の名前を入れる欄です。↓ と ↑ で候補を選び、Enter で決定し、Escape で候補を閉じます。
// 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() で描画した内容を片づけます。
// 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() で入力欄にフォーカスを移します。
// 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)で送信するメッセージ欄です。
// 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} を書けます。
// 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 でのフォーム操作
キーボードだけでログインできるかを、次のフォームで確かめます。
// 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)。
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}') を呼ぶと、候補の一覧は出ず、テストは失敗しました。
test('フォーカスしないで keyboard を呼ぶ', async () => {
const user = userEvent.setup();
render(<FruitCombobox />);
await user.keyboard('{ArrowDown}');
console.log('フォーカスがある要素:', document.activeElement?.tagName);
expect(screen.getByRole('listbox')).toBeInTheDocument();
});
出力の一部を抜き出しています。
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つだけ書くと、入力されずにエラーになりました。
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 は一度も呼ばれませんでした。
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 を使います。





