目次
ある一箇所の挙動だけ直しているのに、毎回プロジェクト全体のテストが走るのは集中力を削がれます。先日、メモリ不足対策でVitestの並列度を絞った[1]ものの、デバッグ中はそもそも実行範囲を狭めたいと思い至り、自分が使っている絞り込み方を一度まとめておくことにしました。
ファイルパスで絞り込む
CLI引数にパス断片を渡すと、その文字列を含むテストファイルだけが対象になります。
vitest auth
これで tests/auth.test.ts や src/features/auth/handler.test.ts のように、パスのどこかに auth を含むファイルだけが実行されます。完全なパスを覚えていなくても、機能名や対象ディレクトリ名のキーワードだけで指定できる手軽さが利点です[2]。
複数指定したい場合はスペース区切りで並べます。
vitest auth user/profile
auth か user/profile のどちらかにヒットするファイルがすべて対象になります。
テスト名で絞り込む
ファイル単位だと粗いときは -t（--testNamePattern）でテスト名を正規表現として照合します。
vitest -t "logs in with email"
照合対象は describe のラベルと it（test）のラベルを連結したフルネームです。たとえば次のようなテストがあるとき、
describe('auth', () => {
it('logs in with email', () => { /* ... */ });
it('logs in with sso', () => { /* ... */ });
});
-t "logs in" で両方ヒット、-t "with email" なら片方だけ通ります。describe 側でも当たるので、機能単位でまとめて走らせたいときは -t "auth" のように親側のラベルで指定すると楽です。
CLIで指定するメリット
.only をコードに書くと、コミット前にうっかり残してしまう事故が起きがちです。-t はファイルを編集しないので、CIの実行コマンドに渡すような使い方にも向きます。
行番号で絞り込む
Vitest 3 以降は、ファイルパスの末尾に :行番号 を付けることで、その行を含むテストだけを実行できます[3]。
vitest basic/foo.test.ts:10
注意点として、行番号付きで指定するときは 省略形ではなくフルファイル名 を渡す必要があります。vitest foo:10 のようなパス断片＋行番号は通らないので、エディタから「現在のファイル名 + カーソル行」を渡すスクリプトを組むときに引っかかりがちです。
複数の行を狙う場合もスペース区切りで並べます。
vitest basic/foo.test.ts:10 basic/foo.test.ts:25
コードに .only を書く
CLI ではなくテストコード側で絞ることもできます。
describe('auth', () => {
it.only('logs in with email', () => { /* ... */ });
it('logs in with sso', () => { /* ... */ });
});
.only を付けたテストだけがそのファイル内で実行されます。describe.only も同様で、ブロック単位の絞り込みになります。
ただし冒頭で触れたとおり、.only を残したまま push してしまうと、他のテストごと CI から見えなくなる事故につながります。eslint-plugin-vitest の no-focused-tests ルールを入れておくと検出できます[4]。
まとめ
普段の開発では「ファイルパスを軽く絞る」「-t で関係するブロックだけに絞る」の組み合わせで十分回ります。.only は手元でガッツリ集中したいときに使い、push 前に外す前提で扱うのが安全です。
行番号指定はエディタやスクリプトから自動的にコマンドを組み立てるときに真価が出るので、頻繁にテストを書く人ほどショートカット化しておくと作業がほぼ「保存→実行→修正」のループだけで完結するようになります。
Test Filtering | Guide | Vitest (2026-05-21 アクセス) ↩︎
Command Line Interface | Guide | Vitest (2026-05-21 アクセス) ↩︎
eslint-plugin-vitest (2026-05-21 アクセス) ↩︎
