VSCodeでJUnitを実行する方法

2026年10月26日

VSCode（Visual Studio Code）では、Java向けの拡張機能を導入することで、JUnitのテストをエディター上から実行できます。

テストメソッド単位やクラス単位で実行できるほか、テストのデバッグ、結果の確認、失敗したテストの再実行なども可能です。

VSCodeでJUnitを利用する場合は、Microsoftが提供している「Test Runner for Java」を使用する方法が一般的です。

Test Runner for Javaは、Java開発に必要な拡張機能をまとめた「Extension Pack for Java」に含まれています。

VSCodeでJUnitを実行するために必要なもの

VSCodeでJUnitを実行する場合は、主に次の環境を準備します。

VSCode
JDK
Extension Pack for Java
JUnit
MavenまたはGradleなどのビルドツール

MavenやGradleは必須ではありません。

ただし、JUnitなどのライブラリを管理しやすく、CI/CD環境でも同じ構成を利用しやすいため、実務ではMavenやGradleを利用するケースが一般的です。

JDKをインストールする

JUnitを利用するには、Javaを実行できるJDK（Java Development Kit）が必要です。

JDKがインストールされているか確認する

VSCodeの統合ターミナルやOSのターミナルで、次のコマンドを実行します。

java -version

続いて、Javaコンパイラを確認します。

javac -version

バージョン情報が表示されれば、基本的にはJDKを利用できる状態です。

たとえば、次のように表示されます。

openjdk version "21.0.x"

JDKが入っていない場合は、Eclipse TemurinやOracle JDKなどをインストールします。

JUnitによって必要なJavaバージョンが異なる

注意したいのは、VSCodeのTest Runner for Javaの要件と、JUnit本体のJava要件は別である点です。

Test Runner for Java自体は比較的古いJDKにも対応していますが、使用するJUnitのバージョンによって必要なJavaバージョンが異なります。

たとえば、JUnit 6ではJava 17以上が必要です。

そのため、単純に「JDK 8以上であれば現在のJUnitをすべて利用できる」と考えるのではなく、使用するJUnitやフレームワークの要件を確認することが重要です。

VSCodeにJavaの拡張機能をインストールする

次に、VSCodeへJava開発用の拡張機能を追加します。

Extension Pack for Javaをインストールする

VSCodeの左側にある「拡張機能」を開きます。

検索欄に、次の名前を入力します。

Extension Pack for Java

表示されたMicrosoft提供の拡張機能をインストールします。

Extension Pack for Javaには、Java開発でよく利用する複数の拡張機能がまとめられています。

代表的なものは次のとおりです。

Language Support for Java by Red Hat
Debugger for Java
Test Runner for Java
Maven for Java
Project Manager for Java

JUnitを実行するうえで特に重要なのが「Test Runner for Java」です。

Test Runner for Javaとは

Test Runner for Javaを利用すると、VSCode上からJavaのテストを実行できます。

主に次の操作に対応しています。

テストメソッド単位で実行
テストクラス単位で実行
複数テストの一括実行
デバッグ実行
テスト結果の確認
失敗したテストの確認
Testingビューでのテスト管理

VSCode公式では、JUnit 4やJUnit 5系、TestNGなどのJavaテストフレームワークをサポートしています。

JUnit 5とJUnit 6の違いを理解しておく

現在のJava開発では、JUnit Jupiterを利用したテストが広く使われています。

ただし、「JUnit 5」と「JUnit Jupiter」は厳密には完全な同義語ではありません。

JUnit Jupiterとは

JUnitは複数のコンポーネントから構成されています。

代表的なものには、次のようなものがあります。

JUnit Platform
JUnit Jupiter
JUnit Vintage

通常、Javaコードで、

@Test
void test() {
}

のようにテストを書く際に利用するAPIがJUnit Jupiterです。

たとえば、@Testは次のようにimportします。

import org.junit.jupiter.api.Test;

JUnit 6が登場した現在でも、JUnit Jupiterの基本的な書き方は引き続き利用されています。

JUnit 5だけを前提にしない

既存プロジェクトではJUnit 5系が利用されていることも多いですが、現在はJUnit 6系も存在します。

新しいプロジェクトでどのJUnitバージョンを利用するかは、次のような条件を確認して決めます。

JDKのバージョン
Spring Bootなどのフレームワーク
MavenやGradleの設定
既存プロジェクトの依存関係
チーム内の開発ルール

そのため、単純に「JUnit 5が最新」と考えるのではなく、プロジェクトに合ったバージョンを選ぶことが重要です。

MavenプロジェクトでJUnitを利用する方法

Javaプロジェクトでよく利用されるビルドツールのひとつがMavenです。

Mavenでは、pom.xmlに依存ライブラリを記述します。

JUnit Jupiterを依存関係に追加する

たとえば、JUnit Jupiterを追加する場合は、概念的には次のように記述します。

<dependencies>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>使用するJUnitのバージョン</version>
        <scope>test</scope>
    </dependency>
</dependencies>

実際に指定するバージョンは、プロジェクトの構成に合わせます。

Spring Bootなどを利用している場合は、フレームワーク側が依存関係のバージョンを管理していることもあります。

その場合は、JUnitのバージョンを個別に固定しないケースもあります。

Mavenプロジェクトの基本構成

Mavenでは、一般的に次のようなディレクトリ構成を使用します。

project/
├─ pom.xml
└─ src/
   ├─ main/
   │ └─ java/
   │ └─ ...
   └─ test/
      └─ java/
         └─ ...

通常のJavaコードは、次のディレクトリに配置します。

src/main/java

JUnitのテストコードは、次のディレクトリに配置します。

src/test/java

GradleプロジェクトでJUnitを利用する方法

Gradleを使用している場合は、build.gradleまたはbuild.gradle.ktsでJUnitの依存関係を設定します。

Groovy DSLの場合

build.gradleでは、たとえば次のように設定します。

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter:使用するバージョン'
}

test {
    useJUnitPlatform()
}

useJUnitPlatform()を設定することで、JUnit Platform上でテストを実行できます。

Kotlin DSLの場合

build.gradle.ktsでは、たとえば次のように記述します。

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:使用するバージョン")
}

tasks.test {
    useJUnitPlatform()
}

プロジェクトの構成や使用するJUnitバージョンによっては、junit-platform-launcherなどを追加する場合もあります。

テスト対象のJavaクラスを作成する

ここでは、JUnitを実行する簡単な例を紹介します。

Calculatorクラスを作成する

次のようなクラスを用意します。

public class Calculator {

    public int add(int a, int b) {
        return a + b;
    }
}

MavenやGradleの標準構成であれば、たとえば次の場所に配置します。

src/main/java/Calculator.java

JUnitのテストクラスを作成する

続いて、Calculatorクラスをテストするコードを作成します。

JUnit Jupiterでテストを書く

次のように記述できます。

import static org.junit.jupiter.api.Assertions.assertEquals;

import org.junit.jupiter.api.Test;

class CalculatorTest {

    @Test
    void addTest() {
        Calculator calculator = new Calculator();

        int result = calculator.add(2, 3);

        assertEquals(5, result);
    }
}

テストクラスは、たとえば次の場所に配置します。

src/test/java/CalculatorTest.java

@Testとは

JUnit Jupiterでは、@Testを付けたメソッドがテストとして認識されます。

たとえば、次のコードです。

@Test
void addTest() {
}

JUnit Jupiterでは、次のクラスをimportします。

import org.junit.jupiter.api.Test;

一方、JUnit 4では次のようになります。

import org.junit.Test;

パッケージが異なるため、JUnit 4とJUnit Jupiterを混在させているプロジェクトでは、どちらのTestをimportしているか確認することが重要です。

assertEquals()とは

JUnitでは、想定している値と実際の値を比較するためにAssertionを利用します。

たとえば、次のコードです。

assertEquals(5, result);

これは、resultが5であることを確認しています。

resultが5ならテストは成功します。

一方、次のように期待値が間違っている場合はテストに失敗します。

assertEquals(10, result);

実際の値が5であれば、期待値と実際の値が異なるため、テスト結果に失敗内容が表示されます。

VSCode上からJUnitを実行する

Java拡張機能とTest Runner for Javaが正しく認識されていると、VSCode上から直接JUnitを実行できます。

テストメソッド単位で実行する

次のようなテストメソッドがあるとします。

@Test
void addTest() {
}

VSCodeでは、テストメソッドの左側付近にテスト実行用のボタンが表示されます。

そのボタンをクリックすると、対象のテストだけを実行できます。

テストケースが多いプロジェクトで、特定の処理だけ確認したい場合に便利です。

テストクラス全体を実行する

テストクラス単位で実行することもできます。

たとえば、次のようなクラスがあります。

class CalculatorTest {

    @Test
    void addTest() {
    }

    @Test
    void subtractTest() {
    }

    @Test
    void multiplyTest() {
    }
}

クラス側の実行ボタンを利用すると、クラス内の複数のテストをまとめて実行できます。

TestingビューからJUnitを実行する

VSCodeには、テストをまとめて管理するためのTestingビューがあります。

Testingビューを開く

VSCode左側にあるフラスコのようなテストアイコンをクリックします。

テストが正しく認識されていれば、次のような形で一覧表示されます。

TESTING

CalculatorTest
├─ addTest
├─ subtractTest
└─ multiplyTest

Testingビューでは、次のような操作を行えます。

すべてのテストを実行
特定のテストだけを実行
テストクラス全体を実行
デバッグ実行
成功・失敗の確認

テストケースが増えてきたプロジェクトでは、Testingビューから管理すると分かりやすくなります。

コマンドパレットからJUnitを実行する

VSCodeのコマンドパレットから、テスト関連の操作を実行することもできます。

コマンドパレットを開く

WindowsやLinuxでは、次のショートカットを使用します。

Ctrl + Shift + P

macOSでは、次のショートカットです。

Command + Shift + P

コマンドパレットが開いたら、次のように入力します。

Test:

すると、テスト関連のコマンドを検索できます。

たとえば、現在開いているファイル内のテストを実行するコマンドとして、次のようなものがあります。

Run Tests in Current File

MavenからJUnitを実行する

VSCodeのGUIを使わず、統合ターミナルからJUnitを実行することもできます。

Mavenプロジェクトでは、プロジェクトのルートディレクトリで次のコマンドを実行します。

mvn test

Maven Wrapperを利用する場合

プロジェクトにMaven Wrapperが含まれている場合は、Wrapperを利用できます。

Windowsでは、たとえば次のように実行します。

mvnw.cmd test

macOSやLinuxでは、次のように実行します。

./mvnw test

プロジェクトにWrapperが用意されている場合は、チーム内でMavenのバージョンを統一しやすいため、Wrapperを使用すると便利です。

GradleからJUnitを実行する

Gradleプロジェクトでは、次のようにテストを実行できます。

gradle test

Gradle Wrapperを利用する場合

macOSやLinuxでは、一般的に次のように実行します。

./gradlew test

Windowsでは、次のように実行できます。

gradlew.bat test

PowerShellでは、次のように実行することもあります。

.\gradlew.bat test

プロジェクトにGradle Wrapperが含まれている場合は、システムにインストールされているGradleよりもWrapperを使用したほうが、開発環境を統一しやすくなります。

JUnitをデバッグ実行する

VSCodeでは、JUnitのテストを通常実行するだけでなく、デバッグ実行することもできます。

ブレークポイントを設定する

たとえば、次のテストがあるとします。

@Test
void addTest() {
    Calculator calculator = new Calculator();

    int result = calculator.add(2, 3);

    assertEquals(5, result);
}

次の行などにブレークポイントを設定します。

int result = calculator.add(2, 3);

そのうえでテストをデバッグ実行すると、処理を途中で停止できます。

デバッグ実行で確認できること

JUnitのデバッグ実行では、主に次のような情報を確認できます。

変数の値
オブジェクトの状態
メソッドの呼び出し順
条件分岐の動作
スタックトレース

テストが失敗する原因を詳しく調べたい場合に有効です。

JUnitのテスト結果を確認する

テストを実行すると、VSCode上で成功したか失敗したかを確認できます。

テストが成功した場合

期待値と実際の値が一致していれば、成功したテストとして表示されます。

テストが失敗した場合

たとえば、次のテストを実行したとします。

assertEquals(10, result);

実際のresultが5だった場合、期待値と実際の値が異なるためテストは失敗します。

VSCode上では、失敗したAssertionやスタックトレースなどを確認できます。

Test: Peek Outputを利用する

テストの詳細な出力を確認したい場合は、Test: Peek Outputなどの機能を利用できます。

スタックトレース内のリンクから、問題が発生しているソースコードへ移動できる場合もあります。

JUnitのテストが表示されない場合の対処法

@Testを書いたのにVSCodeでテストとして認識されない場合は、いくつかの原因が考えられます。

Test Runner for Javaが有効か確認する

まず、次の拡張機能がインストールされているか確認します。

Extension Pack for Java

または、少なくとも次の拡張機能が必要です。

Test Runner for Java

インストール済みでも無効になっていないか確認します。

JUnitの依存関係を確認する

Mavenの場合は、次のファイルを確認します。

pom.xml

Gradleの場合は、次のファイルを確認します。

build.gradle

または、

build.gradle.kts

JUnitが依存関係に含まれていない場合、次のimportなどを解決できません。

import org.junit.jupiter.api.Test;

テストファイルの配置場所を確認する

MavenやGradleでは、テストコードを通常次のディレクトリに配置します。

src/test/java

たとえば、次のような構成にします。

src/
├─ main/
│ └─ java/
│ └─ Calculator.java
└─ test/
   └─ java/
      └─ CalculatorTest.java

JUnit 4とJUnit Jupiterを確認する

JUnit Jupiterの場合は、次のimportを利用します。

import org.junit.jupiter.api.Test;

JUnit 4では、次のimportです。

import org.junit.Test;

意図していないほうのTestを自動importしているケースもあるため、テストが認識されない場合は確認してみましょう。

Javaプロジェクトとして認識されているか確認する

VSCodeがフォルダをJavaプロジェクトとして正しく認識できていない場合、テストが検出されないことがあります。

その場合は、Java拡張機能の読み込み状態や、Maven・Gradleプロジェクトとして正常に読み込まれているかも確認します。

MavenやGradleを使わずにJUnitを利用する

MavenやGradleを使わないJavaプロジェクトでも、VSCodeからJUnitを利用できます。

ビルドツールなしのJavaプロジェクト

VSCodeでは、MavenやGradleで管理されていないJavaフォルダを、いわゆるunmanaged folderとして扱うことがあります。

このような環境でも、条件を満たせばTestingビューからJUnitを有効化できます。

JUnit PlatformのStandalone JARをクラスパスへ追加して利用する方法もあります。

たとえば、JUnit 5系の構成では次のようなJARが利用されることがあります。

junit-platform-console-standalone

ただし、ライブラリ管理やバージョン管理を考えると、規模の大きいプロジェクトではMavenやGradleを利用するほうが管理しやすいでしょう。

VSCodeでJUnitのテストコードを生成する

VSCodeには、テストコードのひな型を生成する機能もあります。

Generate Testsを利用する

Javaのソースコードを開いた状態で、Source Actionから次の機能を利用できます。

Generate Tests...

テスト対象のメソッドなどを選択すると、テストクラスのひな型を生成できます。

ただし、自動生成されたテストだけで十分とは限りません。

実際のテストでは、次のようなケースを追加することが重要です。

正常系
異常系
境界値
null
空文字
最大値
最小値
想定外の入力

テストコードの自動生成は、あくまで作成を補助する機能として利用するとよいでしょう。

VSCodeでJUnitを使うおすすめ構成

これからJavaのテスト環境を構築する場合は、次のような構成が分かりやすいです。

VSCode
↓
Extension Pack for Java
↓
MavenまたはGradle
↓
JUnit Jupiter
↓
src/main/java
↓
src/test/java
↓
Testingビューから実行

JUnitの具体的なバージョンについては、JDKやフレームワークの要件に合わせて選択します。

新規プロジェクトだから必ずJUnit 6、既存プロジェクトだから必ずJUnit 5というわけではありません。

プロジェクト全体の互換性を確認して選ぶことが重要です。