Integrate pinning detection to HelidonTest

 * TestNG with always helidon fix

Signed-off-by: Daniel Kec <[email protected]>

bom/pom.xml

@@ -1088,6 +1088,11 @@
                 <version>${helidon.version}</version>
             </dependency>
             <!-- Testing -->
+            <dependency>
+                <groupId>io.helidon.common.testing</groupId>
+                <artifactId>helidon-common-testing-virtual-threads</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
             <dependency>
                 <groupId>io.helidon.microprofile.testing</groupId>
                 <artifactId>helidon-microprofile-testing-junit5</artifactId>

common/testing/pom.xml

@@ -34,5 +34,6 @@
     <modules>
         <module>junit5</module>
         <module>http-junit5</module>
+        <module>virtual-threads</module>
     </modules>
 </project>

common/testing/virtual-threads/etc/spotbugs/exclude.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 2024 Oracle and/or its affiliates.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+-->
+
+<FindBugsFilter
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://github.com/spotbugs/filter/3.0.0"
+        xsi:schemaLocation="https://github.com/spotbugs/filter/3.0.0 https://raw.githubusercontent.com/spotbugs/spotbugs/3.1.0/spotbugs/etc/findbugsfilter.xsd">
+
+    <Match>
+        <Class name="io.helidon.common.testing.virtualthreads.PinningException"/>
+        <Bug pattern="NM_CLASS_NOT_EXCEPTION"/>
+    </Match>
+</FindBugsFilter>

common/testing/virtual-threads/pom.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    Copyright (c) 2024 Oracle and/or its affiliates.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+  -->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.helidon.common.testing</groupId>
+        <artifactId>helidon-common-testing-project</artifactId>
+        <version>4.2.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>helidon-common-testing-virtual-threads</artifactId>
+
+    <name>Helidon Virtual Threads Testing Utilities</name>
+
+    <properties>
+        <spotbugs.exclude>etc/spotbugs/exclude.xml</spotbugs.exclude>
+    </properties>
+
+</project>

common/testing/virtual-threads/src/main/java/io/helidon/common/testing/virtualthreads/PinningException.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2024 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.helidon.common.testing.virtualthreads;
+
+import jdk.jfr.consumer.RecordedEvent;
+
+/**
+ * Exception used for reporting of Virtual Thread pinning detected during test.
+ */
+public class PinningException extends AssertionError {
+
+    /**
+     * Pinning JFR event.
+     */
+    private final RecordedEvent recordedEvent;
+
+    /**
+     * Create new pinning exception.
+     *
+     * @param recordedEvent pinning JFR event
+     */
+    PinningException(RecordedEvent recordedEvent) {
+        this.recordedEvent = recordedEvent;
+        if (recordedEvent.getStackTrace() != null) {
+            StackTraceElement[] stackTraceElements = recordedEvent.getStackTrace().getFrames().stream()
+                    .map(f -> new StackTraceElement(f.getMethod().getType().getName(),
+                                                    f.getMethod().getName(),
+                                                    f.getMethod().getType().getName() + ".java",
+                                                    f.getLineNumber()))
+                    .toArray(StackTraceElement[]::new);
+            super.setStackTrace(stackTraceElements);
+        }
+    }
+
+    @Override
+    public String getMessage() {
+        return "Pinned virtual threads were detected:\n"
+                + recordedEvent.toString();
+    }
+}

common/testing/virtual-threads/src/main/java/io/helidon/common/testing/virtualthreads/PinningRecorder.java

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2024 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.helidon.common.testing.virtualthreads;
+
+import java.time.Duration;
+
+import jdk.jfr.consumer.RecordedEvent;
+import jdk.jfr.consumer.RecordingStream;
+
+/**
+ * Record pinned thread events and throw exception when detected.
+ */
+public class PinningRecorder implements AutoCloseable {
+
+    /**
+     * Default threshold for considering carrier thread blocking as pinning.
+     */
+    public static final long DEFAULT_THRESHOLD = 20;
+    private static final String JFR_EVENT_VIRTUAL_THREAD_PINNED = "jdk.VirtualThreadPinned";
+    private final RecordingStream recordingStream = new RecordingStream();
+    private volatile PinningException pinningException;
+
+    private PinningRecorder() {
+        //noop
+    }
+
+    /**
+     * Create new pinning JFR event recorder.
+     *
+     * @return new pinning recorder
+     */
+    public static PinningRecorder create() {
+        return new PinningRecorder();
+    }
+
+    /**
+     * Start async recording of {@code jdk.VirtualThreadPinned} JFR event.
+     *
+     * @param threshold time threshold for carrier thread blocking to be considered as pinning
+     */
+    public void record(Duration threshold) {
+        recordingStream.enable(JFR_EVENT_VIRTUAL_THREAD_PINNED)
+                .withThreshold(threshold)
+                .withStackTrace();
+        recordingStream.onEvent(JFR_EVENT_VIRTUAL_THREAD_PINNED, this::record);
+        recordingStream.startAsync();
+    }
+
+    @Override
+    public void close() {
+        try {
+            // Flush ending events
+            recordingStream.stop();
+        } finally {
+            recordingStream.close();
+        }
+        checkAndThrow();
+    }
+
+    void checkAndThrow() {
+        if (pinningException != null) {
+            throw pinningException;
+        }
+    }
+
+    private void record(RecordedEvent event) {
+        PinningException e = new PinningException(event);
+        if (pinningException == null) {
+            pinningException = e;
+        } else {
+            pinningException.addSuppressed(e);
+        }
+    }
+}

microprofile/testing/testng/src/main/java/io/helidon/microprofile/testing/testng/PinnedThreadValidation.java → common/testing/virtual-threads/src/main/java/io/helidon/common/testing/virtualthreads/package-info.java

@@ -13,19 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.helidon.microprofile.testing.testng;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Inherited;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
 
 /**
- * An annotation making this test class to fail at the end if a pinned virtual thread was detected.
+ * Virtual Threads testing features.
  */
-@Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.TYPE)
-@Inherited
-public @interface PinnedThreadValidation {
-}
+package io.helidon.common.testing.virtualthreads;

webserver/testing/junit5/junit5/src/main/java/io/helidon/webserver/testing/junit5/PinnedThreadValidation.java → common/testing/virtual-threads/src/main/java/module-info.java

@@ -13,22 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.helidon.webserver.testing.junit5;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Inherited;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-import org.junit.jupiter.api.extension.ExtendWith;
 
 /**
- * An annotation making this test class to fail at the end if a pinned virtual thread was detected.
+ * Virtual Thread testing features for Helidon test extensions.
  */
-@Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.TYPE)
-@ExtendWith(HelidonPinnedThreadValidationJunitExtension.class)
-@Inherited
-public @interface PinnedThreadValidation {
-}
+module io.helidon.common.testing.vitualthreads {
+    requires jdk.jfr;
+    exports io.helidon.common.testing.virtualthreads to
+            io.helidon.microprofile.testing.junit5,
+            io.helidon.microprofile.testing.testng,
+            io.helidon.webserver.testing.junit5;
+}

dependencies/pom.xml

@@ -95,6 +95,7 @@
         <version.lib.jersey>3.1.9</version.lib.jersey>
         <version.lib.jgit>6.7.0.202309050840-r</version.lib.jgit>
         <version.lib.junit>5.9.3</version.lib.junit>
+        <version.lib.junit-platform-teskit>1.11.3</version.lib.junit-platform-teskit>
         <version.lib.kafka>3.8.1</version.lib.kafka>
         <version.lib.log4j>2.21.1</version.lib.log4j>
         <version.lib.logback>1.4.14</version.lib.logback>
@@ -1284,6 +1285,11 @@
                 <artifactId>hamcrest-core</artifactId>
                 <version>${version.lib.hamcrest}</version>
             </dependency>
+            <dependency>
+                <groupId>org.junit.platform</groupId>
+                <artifactId>junit-platform-testkit</artifactId>
+                <version>${version.lib.junit-platform-teskit}</version>
+            </dependency>
             <dependency>
                 <groupId>org.testcontainers</groupId>
                 <artifactId>junit-jupiter</artifactId>

docs/src/main/asciidoc/mp/testing/testing-ng.adoc

@@ -31,6 +31,7 @@ include::{rootdir}/includes/mp.adoc[]
 - <<Usage, Usage>>
 - <<API, API>>
 - <<Examples, Examples>>
+- <<Virtual Threads, Virtual Threads>>
 - <<Reference, Reference>>
 
 == Overview
@@ -150,6 +151,34 @@ include::{sourcedir}/mp/testing/TestingNgSnippets.java[tag=snippet_2, indent=0]
 <3> Add JaxRs support to the current test class.
 <4> Define a `RequestScoped` bean.
 
+
+== Virtual Threads
+Helidon tests are able to detect Virtual Threads pinning. A situation when carrier thread is blocked
+in a way, that virtual thread scheduler can't use it for scheduling of other virtual threads.
+This can happen for example when blocking native code is invoked, or prior to the JDK 24 when
+blocking IO operation happens in a synchronized block.
+Pinning can in some cases negatively affect application performance.
+
+[source,java]
+.Enable pinning detection
+----
+include::{sourcedir}/mp/testing/TestingNgSnippets.java[tag=snippet_3, indent=0]
+----
+
+Pinning is considered as harmful when it takes longer than 20 milliseconds,
+that is also the default when detecting it within Helidon tests.
+
+Pinning threshold can be changed with:
+
+[source,java]
+.Configure pinning threshold
+----
+include::{sourcedir}/mp/testing/TestingNgSnippets.java[tag=snippet_4, indent=0]
+----
+<1> Change pinning threshold from default(20) to 50 milliseconds.
+
+When pinning is detected, test fails with stacktrace pointing to the line of code causing it.
+
 == Reference
 
 * https://testng.org[TestNG Documentation]

docs/src/main/asciidoc/mp/testing/testing.adoc

@@ -33,6 +33,7 @@ include::{rootdir}/includes/mp.adoc[]
 - <<Usage, Usage>>
 - <<Examples, Examples>>
 - <<Mock Support, Mock Support>>
+- <<Virtual Threads, Virtual Threads>>
 - <<Additional Information, Additional Information>>
 - <<Reference, Reference>>
 
@@ -224,6 +225,33 @@ include::{sourcedir}/mp/testing/CDIMockingSnippets.java[tag=snippet_2, indent=0]
 <4> Test that the mock is injected with modified behavior.
 <5> Test the real method behavior.
 
+== Virtual Threads
+Helidon tests are able to detect Virtual Threads pinning. A situation when carrier thread is blocked
+in a way, that virtual thread scheduler can't use it for scheduling of other virtual threads.
+This can happen for example when blocking native code is invoked, or prior to the JDK 24 when
+blocking IO operation happens in a synchronized block.
+Pinning can in some cases negatively affect application performance.
+
+[source,java]
+.Enable pinning detection
+----
+include::{sourcedir}/mp/testing/TestingSnippets.java[tag=snippet_3, indent=0]
+----
+
+Pinning is considered as harmful when it takes longer than 20 milliseconds,
+that is also the default when detecting it within Helidon tests.
+
+Pinning threshold can be changed with:
+
+[source,java]
+.Configure pinning threshold
+----
+include::{sourcedir}/mp/testing/TestingSnippets.java[tag=snippet_4, indent=0]
+----
+<1> Change pinning threshold from default(20) to 50 milliseconds.
+
+When pinning is detected, test fails with stacktrace pointing to the line of code causing it.
+
 == Additional Information
 
 * https://medium.com/helidon/testing-helidon-9df2ea14e22[Official blog article about Helidon and JUnit usage]