Fixes mockito#2398 : Implement global suppress static initialization leveraging javaagent

Author: mirkoalicastro

mockito-core/src/main/java/org/mockito/Mockito.java

@@ -119,6 +119,7 @@
  *      <a href="#55">55. Verification with assertions (Since 5.3.0)</a><br/>
  *      <a href="#56">56. Mocking singletons (like Java enums) (Since 5.22.0)</a><br/>
  *      <a href="#57">57. Spying on static methods (Since 5.23.0)</a><br/>
+ *      <a href="#58">58. Suppressing static initializers (Since 5.24.0)</a><br/>
  * </b>
  *
  * <h3 id="0">0. <a class="meaningful_link" href="#mockito2" name="mockito2">Migrating to Mockito 2</a></h3>
@@ -1823,6 +1824,34 @@
  *   // Original behavior is restored
  *   assertEquals("foo", Foo.method());
  * </code></pre>
+ *
+ * <h3 id="58">58. <a class="meaningful_link" href="#suppress_clinit" name="suppress_clinit">
+ *  Suppressing static initializers</a></h3>
+ *
+ * When Mockito is used as a Java agent ({@code -javaagent}), you can suppress static initializers
+ * ({@code <clinit>}) of specific classes via the system property {@code mockito.suppress.clinit}.
+ * This causes all static fields in those classes to retain their JVM zero-value defaults
+ * ({@code null}, {@code 0}, {@code false}, etc.) instead of running the static initialization block.
+ *
+ * <p>This is useful when a class static initializer performs expensive or environment-dependent
+ * operations (e.g. loading native libraries, connecting to databases) that are undesirable in tests.
+ *
+ * <p>Because suppression is configured once per JVM at agent startup, it is consistent across all
+ * tests, which means <b>tests can safely run in parallel</b>.
+ *
+ * <p><b>Maven configuration:</b>
+ * <pre class="code"><code class="xml">
+ * &lt;plugin&gt;
+ *     &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
+ *     &lt;artifactId&gt;maven-surefire-plugin&lt;/artifactId&gt;
+ *     &lt;configuration&gt;
+ *         &lt;argLine&gt;
+ *             -javaagent:${org.mockito:mockito-core:jar}
+ *             -Dmockito.suppress.clinit=com.example.ClassA,com.example.ClassB
+ *         &lt;/argLine&gt;
+ *     &lt;/configuration&gt;
+ * &lt;/plugin&gt;
+ * </code></pre>
  */
 @CheckReturnValue
 @SuppressWarnings("unchecked")

mockito-core/src/main/java/org/mockito/internal/PremainAttach.java

@@ -4,7 +4,12 @@
  */
 package org.mockito.internal;
 
+import org.mockito.internal.creation.bytebuddy.ClinitSuppressionTransformer;
+
 import java.lang.instrument.Instrumentation;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
 
 /**
  * Allows users to specify Mockito as a Java agent where the {@link Instrumentation}
@@ -17,15 +22,38 @@
 public class PremainAttach {
 
     private static volatile Instrumentation instrumentation;
+    private static final String SUPPRESS_CLINIT_PROPERTY = "mockito.suppress.clinit";
 
     public static void premain(String arg, Instrumentation instrumentation) {
         if (PremainAttach.instrumentation != null) {
             return;
         }
+        Set<String> classes =
+                parseSuppressClinitProperty(System.getProperty(SUPPRESS_CLINIT_PROPERTY));
+        if (!classes.isEmpty()) {
+            instrumentation.addTransformer(new ClinitSuppressionTransformer(classes), false);
+        }
         PremainAttach.instrumentation = instrumentation;
     }
 
-    public static Instrumentation getInstrumentation() {
-        return instrumentation;
+    /**
+     * Parses a comma-separated list of class names into a set, trimming whitespace from each
+     * entry and ignoring empty entries.
+     *
+     * @param property the property value, may be {@code null}
+     * @return an unmodifiable set of class names
+     */
+    static Set<String> parseSuppressClinitProperty(String property) {
+        if (property == null || property.trim().isEmpty()) {
+            return Collections.emptySet();
+        }
+        Set<String> result = new HashSet<>();
+        for (String name : property.split(",")) {
+            String trimmed = name.trim();
+            if (!trimmed.isEmpty()) {
+                result.add(trimmed);
+            }
+        }
+        return Collections.unmodifiableSet(result);
     }
 }

mockito-core/src/main/java/org/mockito/internal/creation/bytebuddy/ClinitSuppressionTransformer.java

@@ -0,0 +1,112 @@
+/*
+ * Copyright (c) 2026 Mockito contributors
+ * This program is made available under the terms of the MIT License.
+ */
+package org.mockito.internal.creation.bytebuddy;
+
+import net.bytebuddy.jar.asm.ClassReader;
+import net.bytebuddy.jar.asm.ClassVisitor;
+import net.bytebuddy.jar.asm.ClassWriter;
+import net.bytebuddy.jar.asm.MethodVisitor;
+import net.bytebuddy.jar.asm.Opcodes;
+import net.bytebuddy.utility.OpenedClassReader;
+
+import java.lang.instrument.ClassFileTransformer;
+import java.security.ProtectionDomain;
+import java.util.Set;
+
+/**
+ * A {@link ClassFileTransformer} that suppresses static initializers ({@code <clinit>}) for
+ * specified classes at class-load time.
+ *
+ * <p>When a class is first loaded (not retransformed) and its fully-qualified name appears in the
+ * configured set, the transformer replaces the {@code <clinit>} method with an empty method body.
+ * This causes all static fields to retain their JVM zero-value defaults ({@code null},
+ * {@code 0}, {@code false}, etc.).
+ *
+ * <p>This transformer is registered at premain time when the system property
+ * {@code mockito.suppress.clinit} is set. See {@link org.mockito.internal.PremainAttach} for
+ * details.
+ *
+ * @since 5.+
+ */
+public class ClinitSuppressionTransformer implements ClassFileTransformer {
+
+    private final Set<String> classNames;
+
+    /**
+     * Creates a new transformer.
+     *
+     * @param classNames fully-qualified class names whose static initializers should be suppressed
+     *     (e.g. {@code "com.example.MyClass"})
+     */
+    public ClinitSuppressionTransformer(Set<String> classNames) {
+        this.classNames = classNames;
+    }
+
+    @Override
+    public byte[] transform(
+            ClassLoader loader,
+            String className,
+            Class<?> classBeingRedefined,
+            ProtectionDomain protectionDomain,
+            byte[] classfileBuffer) {
+        if (classBeingRedefined != null) {
+            return null;
+        }
+        if (className == null) {
+            return null;
+        }
+        String dotName = className.replace('/', '.');
+        if (!classNames.contains(dotName)) {
+            return null;
+        }
+        return suppressClinit(classfileBuffer);
+    }
+
+    /**
+     * Replaces the {@code <clinit>} method in the given class bytecode with an empty method body.
+     * If the class has no {@code <clinit>}, the bytecode is returned unchanged.
+     *
+     * <p>The transformation uses ASM (shaded inside ByteBuddy) to visit all methods. When
+     * {@code <clinit>} is encountered, a new empty method body containing only a {@code RETURN}
+     * instruction is emitted. All other methods and class structure are preserved as-is.
+     *
+     * @param classfileBuffer the original class bytecode
+     * @return the transformed bytecode with an empty {@code <clinit>}, or the original bytecode
+     *     if no {@code <clinit>} was found
+     */
+    static byte[] suppressClinit(byte[] classfileBuffer) {
+        ClassReader reader = new ClassReader(classfileBuffer);
+        ClassWriter writer = new ClassWriter(reader, 0);
+        ClinitSuppressionClassVisitor classVisitor = new ClinitSuppressionClassVisitor(writer);
+
+        reader.accept(classVisitor, 0);
+
+        return classVisitor.found ? writer.toByteArray() : classfileBuffer;
+    }
+
+    private static class ClinitSuppressionClassVisitor extends ClassVisitor {
+        boolean found;
+
+        ClinitSuppressionClassVisitor(ClassVisitor classVisitor) {
+            super(OpenedClassReader.ASM_API, classVisitor);
+        }
+
+        @Override
+        public MethodVisitor visitMethod(
+                int access, String name, String descriptor, String signature, String[] exceptions) {
+            if ("<clinit>".equals(name)) {
+                found = true;
+                MethodVisitor mv =
+                        super.visitMethod(access, name, descriptor, signature, exceptions);
+                mv.visitCode();
+                mv.visitInsn(Opcodes.RETURN);
+                mv.visitMaxs(0, 0);
+                mv.visitEnd();
+                return null;
+            }
+            return super.visitMethod(access, name, descriptor, signature, exceptions);
+        }
+    }
+}

mockito-core/src/test/java/org/mockito/internal/PremainAttachTest.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2026 Mockito contributors
+ * This program is made available under the terms of the MIT License.
+ */
+package org.mockito.internal;
+
+import org.junit.Test;
+
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+public class PremainAttachTest {
+
+    @Test
+    public void parse_suppress_clinit_property_with_multiple_classes() {
+        Set<String> result =
+                PremainAttach.parseSuppressClinitProperty(
+                        "com.example.ClassA,com.example.ClassB,com.example.ClassC");
+
+        assertThat(result)
+                .containsExactlyInAnyOrder(
+                        "com.example.ClassA", "com.example.ClassB", "com.example.ClassC");
+    }
+
+    @Test
+    public void parse_suppress_clinit_property_with_whitespace_trimming() {
+        Set<String> result =
+                PremainAttach.parseSuppressClinitProperty(
+                        " com.example.ClassA , com.example.ClassB ");
+
+        assertThat(result).containsExactlyInAnyOrder("com.example.ClassA", "com.example.ClassB");
+    }
+
+    @Test
+    public void parse_suppress_clinit_property_returns_empty_when_null() {
+        Set<String> result = PremainAttach.parseSuppressClinitProperty(null);
+
+        assertThat(result).isEmpty();
+    }
+
+    @Test
+    public void parse_suppress_clinit_property_returns_empty_when_blank() {
+        Set<String> result = PremainAttach.parseSuppressClinitProperty("   ");
+
+        assertThat(result).isEmpty();
+    }
+}