Skip to content
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

Move failsafe config out of native profile #21997

Merged
merged 1 commit into from
Apr 30, 2022
Merged

Move failsafe config out of native profile #21997

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
60 changes: 8 additions & 52 deletions docs/src/main/asciidoc/building-native-image.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,55 +229,7 @@ You can do so by prepending the flag with `-J` and passing it as additional nati

== Testing the native executable

Producing a native executable can lead to a few issues, and so it's also a good idea to run some tests against the application running in the native file.

In the `pom.xml` file, the `native` profile contains:

[source, xml]
----
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
<configuration>
<systemPropertyVariables>
<native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>${maven.home}</maven.home>
</systemPropertyVariables>
</configuration>
</execution>
</executions>
</plugin>
----

This instructs the failsafe-maven-plugin to run integration-test and indicates the location of the produced native executable.

Then, open the `src/test/java/org/acme/quickstart/GreetingResourceIT.java`. It contains:

[source,java]
----
package org.acme.quickstart;


import io.quarkus.test.junit.QuarkusIntegrationTest;

@QuarkusIntegrationTest // <1>
public class GreetingResourceIT extends GreetingResourceTest { // <2>

// Run the same tests

}
----
<1> Use another test runner that starts the application from the native file before the tests.
The executable is retrieved using the `native.image.path` system property configured in the _Failsafe Maven Plugin_.
<2> We extend our previous tests, but you can also implement your tests
Producing a native executable can lead to a few issues, and so it's also a good idea to run some tests against the application running in the native file. The reasoning is explained in the link:getting-started-testing#quarkus-integration-test[Testing Guide].

To see the `GreetingResourceIT` run against the native executable, use `./mvnw verify -Pnative`:
[source,shell]
Expand Down Expand Up @@ -342,14 +294,18 @@ you can only test via HTTP calls. Your test code does not actually run natively,
that does not call your HTTP endpoints, it's probably not a good idea to run them as part of native tests.

If you share your test class between JVM and native executions like we advise above, you can mark certain tests
with the `@DisabledOnNativeImage` annotation in order to only run them on the JVM.
with the `@DisabledOnIntegrationTest` annotation in order to skip them when testing against a native image.

[NOTE]
====
Using `@DisabledOnIntegrationTest` will also disable the test in all integration test instances, including
testing the application in JVM mode, in a container image, and native image.
====

=== Testing an existing native executable

It is also possible to re-run the tests against a native executable that has already been built. To do this run
`./mvnw test-compile failsafe:integration-test`. This will discover the existing native image and run the tests against it using
failsafe.
`./mvnw test-compile failsafe:integration-test -Pnative`. This will discover the existing native image and run the tests against it using failsafe.

If the process cannot find the native image for some reason, or you want to test a native image that is no longer in the
target directory you can specify the executable with the `-Dnative.image.path=` system property.
Expand Down
52 changes: 51 additions & 1 deletion docs/src/main/asciidoc/getting-started-testing.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1221,10 +1221,60 @@ As is the case with `@NativeImageTest`, this is a black box test that supports t

[NOTE]
====
As a test annotated with `@QuarkusIntegrationTest` tests the result of the build, it should be run as part of the integration test suite - i.e. via the `maven-failsafe-plugin` if using Maven or the `quarkusIntTest` task if using Gradle.
As a test annotated with `@QuarkusIntegrationTest` tests the result of the build, it should be run as part of the integration test suite - i.e. by setting `-DskipITs=false` if using Maven or the `quarkusIntTest` task if using Gradle.
These tests will **not** work if run in the same phase as `@QuarkusTest` as Quarkus has not yet created the final artifact.
====

The `pom.xml` file contains:

[source, xml]
----
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
<configuration>
<systemPropertyVariables>
<native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>${maven.home}</maven.home>
</systemPropertyVariables>
</configuration>
</execution>
</executions>
</plugin>
----

This instructs the failsafe-maven-plugin to run integration-test.

Then, open the `src/test/java/org/acme/quickstart/GreetingResourceIT.java`. It contains:

[source,java]
----
package org.acme.quickstart;


import io.quarkus.test.junit.QuarkusIntegrationTest;

@QuarkusIntegrationTest // <1>
public class GreetingResourceIT extends GreetingResourceTest { // <2>

// Run the same tests

}
----
<1> Use another test runner that starts the application from the native file before the tests.
The executable is retrieved by the _Failsafe Maven Plugin_.
<2> We extend our previous tests as a convenience, but you can also implement your tests.

More information can be found in the link:building-native-image#testing-the-native-executable[Testing the native executable Guide].
maxandersen marked this conversation as resolved.
Show resolved Hide resolved

=== Launching containers

When `@QuarkusIntegrationTest` results in launching a container (because the application was built with `quarkus.container-image.build` set to `true`), the container is launched on a predictable container network. This facilitates writing integration tests that need to launch services to support the application.
Expand Down
80 changes: 43 additions & 37 deletions docs/src/main/asciidoc/maven-tooling.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -448,9 +448,13 @@ If you have not used <<project-creation,project scaffolding>>, add the following

[source,xml,subs=attributes+]
----
<properties>
<skipITs>true</skipITs> <1>
</properties>

<dependencyManagement>
<dependencies>
<dependency> <1>
<dependency> <2>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-bom</artifactId>
<version>${quarkus.platform.version}</version>
Expand All @@ -462,11 +466,11 @@ If you have not used <<project-creation,project scaffolding>>, add the following

<build>
<plugins>
<plugin> <2>
<plugin> <3>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.platform.version}</version>
<extensions>true</extensions> <3>
<extensions>true</extensions> <4>
<executions>
<execution>
<goals>
Expand All @@ -477,7 +481,7 @@ If you have not used <<project-creation,project scaffolding>>, add the following
</execution>
</executions>
</plugin>
<plugin> <4>
<plugin> <5>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>${surefire-plugin.version}</version>
Expand All @@ -488,51 +492,53 @@ If you have not used <<project-creation,project scaffolding>>, add the following
</systemPropertyVariables>
</configuration>
</plugin>
<plugin> <6>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
<configuration>
<systemPropertyVariables>
<native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>${maven.home}</maven.home>
</systemPropertyVariables>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>

<profiles>
<profile> <5>
<profile> <7>
<id>native</id>
<properties> <6>
<properties> <8>
<quarkus.package.type>native</quarkus.package.type>
<skipITs>false</skipITs> <9>
</properties>
<build>
<plugins>
<plugin> <7>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
<configuration>
<systemPropertyVariables>
<native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>${maven.home}</maven.home>
</systemPropertyVariables>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
----

<1> Optionally use a BOM file to omit the version of the different Quarkus dependencies.
<2> Use the Quarkus Maven plugin that will hook into the build process.
<3> Enabling Maven plugin extensions will register a Quarkus `MavenLifecycleParticipant` which will make sure the Quarkus classloaders used during the build are properly closed. During the `generate-code` and `generate-code-tests` goals the Quarkus application bootstrap is initialized and re-used in the `build` goal (which actually builds and packages a production application). The Quarkus classloaders will be properly closed in the `build` goal of the `quarkus-maven-plugin`. However, if the build fails in between the `generate-code` or `generate-code-tests` and `build` then the Quarkus augmentation classloader won't be properly closed, which may lead to locking of JAR files that happened to be on the classpath on Windows OS.
<4> Add system properties to `maven-surefire-plugin`. +
<1> Disable running of integration tests (test names `*IT` and annotated with `@QuarkusIntegrationTest`) on all builds. To run these tests all the time, either remove this property, set its value to `false`, or set `-DskipITs=false` on the command line when you run the build. +
As mentioned below, this is overridden in the `native` profile.
<2> Optionally use a BOM file to omit the version of the different Quarkus dependencies.
<3> Use the Quarkus Maven plugin that will hook into the build process.
<4> Enabling Maven plugin extensions will register a Quarkus `MavenLifecycleParticipant` which will make sure the Quarkus classloaders used during the build are properly closed. During the `generate-code` and `generate-code-tests` goals the Quarkus application bootstrap is initialized and re-used in the `build` goal (which actually builds and packages a production application). The Quarkus classloaders will be properly closed in the `build` goal of the `quarkus-maven-plugin`. However, if the build fails in between the `generate-code` or `generate-code-tests` and `build` then the Quarkus augmentation classloader won't be properly closed, which may lead to locking of JAR files that happened to be on the classpath on Windows OS.
<5> Add system properties to `maven-surefire-plugin`. +
`maven.home` is only required if you have custom configuration in `${maven.home}/conf/settings.xml`.
<6> If you want to test the artifact produced by your build with Integration Tests, add the following plugin configuration. Test names `*IT` and annotated with `@QuarkusIntegrationTest` will be run against the artifact produced by the build (JAR file, container image, etc). See the xref:getting-started-testing.adoc#quarkus-integration-test[Integration Testing guide] for more info. +
`maven.home` is only required if you have custom configuration in `${maven.home}/conf/settings.xml`.
<5> Use a specific `native` profile for native executable building.
<6> Enable the `native` package type. The build will therefore produce a native executable.
<7> If you want to test your native executable with Integration Tests, add the following plugin configuration. Test names `*IT` and annotated `@NativeImageTest` or `@QuarkusIntegrationTest` will be run against the native executable. See the xref:building-native-image.adoc[Native executable guide] for more info.
<7> Use a specific `native` profile for native executable building.
<8> Enable the `native` package type. The build will therefore produce a native executable.
<9> Always run integration tests when building a native image (test names `*IT` and annotated with `@QuarkusIntegrationTest` or `@NativeImageTest`). +
If you do not wish to run integration tests when building a native image, simply remove this property altogether or set its value to `true`.

[[fast-jar]]
=== Using fast-jar
Expand Down
43 changes: 24 additions & 19 deletions ...destarts/quarkus-extension/code/integration-tests/java/integration-tests/pom.tpl.qute.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@
<name>{namespace.name}{extension.name} - Integration Tests</name>
{/if}

<properties>
<skipITs>true</skipITs>
</properties>

<dependencies>
<dependency>
<groupId>io.quarkus</groupId>
Expand Down Expand Up @@ -57,6 +61,25 @@
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
<configuration>
<systemPropertyVariables>
<native.image.path>$\{project.build.directory}/$\{project.build.finalName}-runner</native.image.path>
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>$\{maven.home}</maven.home>
</systemPropertyVariables>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>

Expand All @@ -70,6 +93,7 @@
</activation>
<properties>
<quarkus.package.type>native</quarkus.package.type>
<skipITs>false</skipITs>
</properties>
<build>
<plugins>
Expand All @@ -80,25 +104,6 @@
<skipTests>$\{native.surefire.skip}</skipTests>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
<configuration>
<systemPropertyVariables>
<native.image.path>$\{project.build.directory}/$\{project.build.finalName}-runner</native.image.path>
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>$\{maven.home}</maven.home>
</systemPropertyVariables>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
Expand Down
Loading