Skip to content

Move JUnit tests to get started #767

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 24, 2025
Merged

Move JUnit tests to get started #767

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d21fb36
Move JUnit tests to get started
ban-mi Sep 2, 2025
fbe1e97
Update docs/src/docs/asciidoc/end-to-end-gradle-guide.adoc
ban-mi Sep 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 32 additions & 33 deletions docs/src/docs/asciidoc/end-to-end-gradle-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,37 @@ This command will compile your application and create a native executable in the
./gradlew nativeRun
----

Continue reading below to learn more about the plugin.

[[run-junit-tests]]
=== Run Junit Tests

This plugin supports running tests on the JUnit Platform.
The tests are compiled ahead of time and executed as native code.

- Add the JUnit 5 dependency to _build.gradle_ / _build.gradle.kts_ to include the testing framework:

[source,groovy,role="multi-language-sample"]
----
testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.1'
testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.8.1'
testImplementation 'junit:junit:4.13.2'
----
Copy link
Collaborator

@dnestoro dnestoro Sep 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@melix correct me if I am wrong, but since version 0.11.0 users should add the following as well?

testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

Copy link
Collaborator

@melix melix Sep 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It depends on the version of Gradle. Since 8.14 they have to.

Copy link
Collaborator

@dnestoro dnestoro Sep 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ban-mi can you please add some kind of note/warning that if users are using Gradle >= 8.14 and Native Build Tools >= 0.11.0, they should add the following dependency as well

testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

cc @vjovanov @melix

Copy link
Member

@vjovanov vjovanov Sep 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't this requirement independent of the plugin usage?

Copy link
Collaborator

@dnestoro dnestoro Sep 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I am not wrong, with earlier versions of NBT, users did not have to add this dependency themselves. When we fixed the issue with "leaking" dependencies (release 0.11.0), we stopped providing this dependency by ourselves, and required users to do so (but we fixed other bugs caused by leaking JUnit dependencies).

@melix please correct me if I missed something since you implemented fix for leaking dependencies.

See this comment: #712 (comment)


[source,kotlin,role="multi-language-sample"]
----
testImplementation('org.junit.jupiter:junit-jupiter-api:5.8.1')
testRuntimeOnly('org.junit.jupiter:junit-jupiter-engine:5.8.1')
testImplementation('junit:junit:4.13.2')
----

- Run the tests:

[source,bash,role="multi-language-sample"]
----
./gradlew nativeTest
----

The tests are compiled ahead of time and executed as native code.

[[advanced-use-cases]]
== Advanced Use Cases: How to
Expand Down Expand Up @@ -134,37 +164,6 @@ This works similarly to `JAVA_TOOL_OPTIONS`, where the value of the environment

Learn more about Native Image build configuration https://www.graalvm.org/reference-manual/native-image/overview/BuildConfiguration/[on the website].

[[run-junit-tests]]
=== Run Junit Tests

This plugin supports running tests on the JUnit Platform.
The tests are compiled ahead of time and executed as native code.

- Add the JUnit 5 dependency to _build.gradle_ / _build.gradle.kts_ to include the testing framework:

[source,groovy,role="multi-language-sample"]
----
testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.1'
testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.8.1'
testImplementation 'junit:junit:4.13.2'
----

[source,kotlin,role="multi-language-sample"]
----
testImplementation('org.junit.jupiter:junit-jupiter-api:5.8.1')
testRuntimeOnly('org.junit.jupiter:junit-jupiter-engine:5.8.1')
testImplementation('junit:junit:4.13.2')
----

- Run the tests:

[source,bash,role="multi-language-sample"]
----
./gradlew nativeTest
----

The tests are compiled ahead of time and executed as native code.

[[gather-execution-profiles]]
=== Gather Execution Profiles and Build Optimized Images

Expand Down Expand Up @@ -444,4 +443,4 @@ All the monitoring and debugging tools https://www.graalvm.org/reference-manual/

=== Learn more

To continue learning, refer to the <<changelog.adoc#,extensive reference documentation for the GraalVM Native Image Gradle plugin>>.
To continue learning, refer to the <<gradle-plugin.adoc#,Gradle plugin documentation>>.
98 changes: 49 additions & 49 deletions docs/src/docs/asciidoc/end-to-end-maven-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,54 +103,6 @@ This command will compile your application and create a native executable in the
You can have multiple profiles, which is very convenient if you want to produce different versions of your native images for your application (optimized, static, and others).
Continue to advanced use cases to learn more.

[[advanced-use-cases]]
== Advanced Use Cases: How to

For advanced use cases, this guide provides instructions for configuring the build process, running tests on native code, gathering execution profiles, troubleshooting missing configuration, and enabling diagnostic tools to analyze native images.

[[configure-image-build]]
=== Configure Native Image Build

The plugin supports passing options directly to Native Image inside the `<configuration>` block.
Using `<buildArg>`, you can pass any Native Image build option listed on https://www.graalvm.org/reference-manual/native-image/overview/Options/[this page].

The plugin also provides special properties to configure the build:

- `<environment>` - Sets the environment options
- `<imageName>` - Specifies of the name for the native executable file. If a custom name is not supplied, the artifact ID of the project will be used by default (defaults to the project name).
- `<jvmArgs>` - Passes the given argument directly to the JVM running the `native-image` tool
- `<quickBuild>` - Enables quick build mode
- `<verbose>` - Enables the verbose output
- and many more https://graalvm.github.io/native-build-tools/latest/maven-plugin.html#configuration-options[listed here].

Here is an example of additional options usage:
[source,xml, role="multi-language-sample"]
----
<configuration>
<mainClass>org.example.Main</mainClass>
<imageName>myApp</imageName>
<verbose>true</verbose>
<buildArgs>
<buildArg>-O3</buildArg> <!-- enables additional compiler optimizations -->
</buildArgs>
<environment>
<variable1>value1</variable1>
<variable2>value2</variable2>
</environment>
<jvmArgs>
<arg>your-argument</arg>
</jvmArgs>
</configuration>
----

[TIP]
====
As an alternative, you can pass additional build options via the `NATIVE_IMAGE_OPTIONS` environment variable, on the command line.
This works similarly to `JAVA_TOOL_OPTIONS`, where the value of the environment variable is prefixed to the options supplied to `native-image`.
====

Learn more about Native Image build configuration https://www.graalvm.org/reference-manual/native-image/overview/BuildConfiguration/[on the website].

[[run-junit-tests]]
=== Run Junit Tests

Expand Down Expand Up @@ -232,6 +184,54 @@ Alternatively, set `<skipNativeTests>` to `true` in the plugin configuration:

This way you configure your Maven profile to skip generation and execution of tests as native code.

[[advanced-use-cases]]
== Advanced Use Cases: How to

For advanced use cases, this guide provides instructions for configuring the build process, running tests on native code, gathering execution profiles, troubleshooting missing configuration, and enabling diagnostic tools to analyze native images.

[[configure-image-build]]
=== Configure Native Image Build

The plugin supports passing options directly to Native Image inside the `<configuration>` block.
Using `<buildArg>`, you can pass any Native Image build option listed on https://www.graalvm.org/reference-manual/native-image/overview/Options/[this page].

The plugin also provides special properties to configure the build:

- `<environment>` - Sets the environment options
- `<imageName>` - Specifies of the name for the native executable file. If a custom name is not supplied, the artifact ID of the project will be used by default (defaults to the project name).
- `<jvmArgs>` - Passes the given argument directly to the JVM running the `native-image` tool
- `<quickBuild>` - Enables quick build mode
- `<verbose>` - Enables the verbose output
- and many more https://graalvm.github.io/native-build-tools/latest/maven-plugin.html#configuration-options[listed here].

Here is an example of additional options usage:
[source,xml, role="multi-language-sample"]
----
<configuration>
<mainClass>org.example.Main</mainClass>
<imageName>myApp</imageName>
<verbose>true</verbose>
<buildArgs>
<buildArg>-O3</buildArg> <!-- enables additional compiler optimizations -->
</buildArgs>
<environment>
<variable1>value1</variable1>
<variable2>value2</variable2>
</environment>
<jvmArgs>
<arg>your-argument</arg>
</jvmArgs>
</configuration>
----

[TIP]
====
As an alternative, you can pass additional build options via the `NATIVE_IMAGE_OPTIONS` environment variable, on the command line.
This works similarly to `JAVA_TOOL_OPTIONS`, where the value of the environment variable is prefixed to the options supplied to `native-image`.
====

Learn more about Native Image build configuration https://www.graalvm.org/reference-manual/native-image/overview/BuildConfiguration/[on the website].

[[gather-execution-profiles]]
=== Gather Execution Profiles and Build Optimized Images

Expand Down Expand Up @@ -500,4 +500,4 @@ You will find the output of these tools among the generated artifacts after runn

=== Learn more

To continue learning, refer to the <<changelog.adoc#,extensive reference documentation for the GraalVM Native Image Maven plugin>>.
To continue learning, refer to the <<maven-plugin.adoc#,Maven plugin documentation>>.