From da03ff655c62080900f799c2322d8baa73f7f7ee Mon Sep 17 00:00:00 2001 From: Leonid Shalupov Date: Wed, 7 Jan 2026 17:44:19 +0100 Subject: [PATCH] docs testFramework: javadocs on DefaultLightProjectDescriptor and Mock JDKs GitOrigin-RevId: f6a7c8d1191cd0e3da052eb7a6e78b4545c639ba --- .../intellij/testFramework/IdeaTestUtil.java | 114 +++++++++++++++++- .../DefaultLightProjectDescriptor.java | 16 +++ .../LightJavaCodeInsightFixtureTestCase.java | 45 ++++++- 3 files changed, 168 insertions(+), 7 deletions(-) diff --git a/java/testFramework/shared/src/com/intellij/testFramework/IdeaTestUtil.java b/java/testFramework/shared/src/com/intellij/testFramework/IdeaTestUtil.java index 0459123d4b38..70cf60b7b1ab 100644 --- a/java/testFramework/shared/src/com/intellij/testFramework/IdeaTestUtil.java +++ b/java/testFramework/shared/src/com/intellij/testFramework/IdeaTestUtil.java @@ -114,6 +114,40 @@ public final class IdeaTestUtil { return getMockJdk(level.toJavaVersion()); } + /** + * Returns a mock JDK for the specified Java version. + * + *

Version Mapping

+ * Mock JDKs are simplified JDKs with limited class coverage. The requested version + * is mapped to the nearest available mock JDK: + * + * + *

Class Coverage

+ * + * + * + * + * + * + *
Mock JDK Class Coverage
Mock JDKjava.io.Filejava.nio.file.*Source
1.7YesNocommunity/java/mockJDK-1.7/
1.8YesNocommunity/java/mockJDK-1.8/
11+YesYesMaven: org.jetbrains.mockjdk:mockjdk-base-java
+ * + *

Common Pitfall

+ * If your test uses {@code java.nio.file.Path} (e.g., {@code File.toPath()}), + * you need Mock JDK 11 or higher. Use {@link #getMockJdk11()} or specify + * {@code JavaVersion.compose(11)} or higher. + * + * @param version the desired Java version + * @return a mock JDK SDK + * @see #getMockJdk11() + */ public static @NotNull Sdk getMockJdk(@NotNull JavaVersion version) { int mockJdk = version.feature >= 25 ? 25 : version.feature >= 21 ? 21 : @@ -228,39 +262,107 @@ public final class IdeaTestUtil { return createMockJdk(name, path, null); } - /// It's JDK 1.4, not 14. + /** + * Returns Mock JDK 1.4 (Java 4). + * + *

Warning: The method name "14" refers to version "1.4" (Java 4), NOT Java 14. + * + * @return Mock JDK 1.4 (Java 4) + * @see #getMockJdk(JavaVersion) for version mapping and class coverage details + */ public static @NotNull Sdk getMockJdk14() { return getMockJdk(JavaVersion.compose(4)); } - /// It's JDK 1.6, not 16. + /** + * Returns Mock JDK 1.7 (Java 7), since there is no Mock JDK 1.6. + * + *

Warning: The method name "16" refers to version "1.6" (Java 6), NOT Java 16. + * This actually returns Mock JDK 1.7 due to version mapping. + * + * @return Mock JDK 1.7 (Java 7) + * @see #getMockJdk(JavaVersion) for version mapping and class coverage details + */ public static @NotNull Sdk getMockJdk16() { return getMockJdk(JavaVersion.compose(6)); } - /// It's JDK 1.7, not 17. + /** + * Returns Mock JDK 1.7 (Java 7). + * + *

Warning: The method name "17" refers to version "1.7" (Java 7), NOT Java 17. + * For Java 17, use {@code getMockJdk(JavaVersion.compose(17))}. + * + *

This mock JDK does NOT contain {@code java.nio.file.*} classes. + * If you need {@code Path}, {@code Paths}, or {@code Files}, use {@link #getMockJdk11()}. + * + * @return Mock JDK 1.7 (Java 7) + * @see #getMockJdk11() for tests needing java.nio.file.* + * @see #getMockJdk(JavaVersion) for version mapping and class coverage details + */ public static @NotNull Sdk getMockJdk17() { return getMockJdk(JavaVersion.compose(7)); } - /// It's JDK 1.7, not 17. + /** + * Returns Mock JDK 1.7 (Java 7) with a custom name. + * + *

Warning: The method name "17" refers to version "1.7" (Java 7), NOT Java 17. + * + * @param name the SDK name + * @return Mock JDK 1.7 (Java 7) + * @see #getMockJdk17() + */ public static @NotNull Sdk getMockJdk17(@NotNull String name) { return createMockJdk(name, getMockJdk17Path().getPath()); } - /// It's JDK 1.8, not 18. + /** + * Returns Mock JDK 1.8 (Java 8). + * + *

Warning: The method name "18" refers to version "1.8" (Java 8), NOT Java 18. + * For Java 18, use {@code getMockJdk(JavaVersion.compose(18))}. + * + *

This mock JDK does NOT contain {@code java.nio.file.*} classes. + * If you need {@code Path}, {@code Paths}, or {@code Files}, use {@link #getMockJdk11()}. + * + * @return Mock JDK 1.8 (Java 8) + * @see #getMockJdk11() for tests needing java.nio.file.* + * @see #getMockJdk(JavaVersion) for version mapping and class coverage details + */ public static @NotNull Sdk getMockJdk18() { return getMockJdk(JavaVersion.compose(8)); } + /** + * Returns Mock JDK 9. + * + * @return Mock JDK 9 + * @see #getMockJdk(JavaVersion) for version mapping and class coverage details + */ public static @NotNull Sdk getMockJdk9() { return getMockJdk(JavaVersion.compose(9)); } - + + /** + * Returns Mock JDK 11. + * + *

This is the recommended mock JDK for tests that need {@code java.nio.file.*} classes + * ({@code Path}, {@code Paths}, {@code Files}). Mock JDKs 1.7 and 1.8 do NOT contain these classes. + * + * @return Mock JDK 11 + * @see #getMockJdk(JavaVersion) for version mapping and class coverage details + */ public static @NotNull Sdk getMockJdk11() { return getMockJdk(JavaVersion.compose(11)); } + /** + * Returns Mock JDK 21. + * + * @return Mock JDK 21 + * @see #getMockJdk(JavaVersion) for version mapping and class coverage details + */ public static @NotNull Sdk getMockJdk21() { return getMockJdk(JavaVersion.compose(21)); } diff --git a/java/testFramework/src/com/intellij/testFramework/fixtures/DefaultLightProjectDescriptor.java b/java/testFramework/src/com/intellij/testFramework/fixtures/DefaultLightProjectDescriptor.java index 4c08f2919193..d5b5c591d116 100644 --- a/java/testFramework/src/com/intellij/testFramework/fixtures/DefaultLightProjectDescriptor.java +++ b/java/testFramework/src/com/intellij/testFramework/fixtures/DefaultLightProjectDescriptor.java @@ -43,6 +43,22 @@ public class DefaultLightProjectDescriptor extends LightProjectDescriptor { return JAVA_MODULE_ENTITY_TYPE_ID_NAME; } + /** + * Returns the SDK for tests using this descriptor. + * + *

Default: Returns {@link IdeaTestUtil#getMockJdk17()} (Mock JDK 1.7, Java 7). + * + *

Important: Mock JDK 1.7 does NOT contain {@code java.nio.file.*} classes. + * If your test needs {@code Path}, {@code Paths}, or {@code Files}, create a custom + * descriptor with a higher JDK version: + * 

{@code
+   * private static final LightProjectDescriptor DESCRIPTOR =
+   *     new DefaultLightProjectDescriptor(IdeaTestUtil::getMockJdk11);
+   * }
+ * + * @return the SDK, defaults to Mock JDK 1.7 (Java 7) + * @see IdeaTestUtil#getMockJdk(com.intellij.util.lang.JavaVersion) for version mapping details + */ @Override public Sdk getSdk() { return customSdk == null ? IdeaTestUtil.getMockJdk17() : customSdk.get(); diff --git a/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java b/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java index c1166acb3456..68f77d29bb4f 100644 --- a/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java +++ b/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java @@ -29,6 +29,28 @@ import java.io.File; *
  • Creates a simpler in-memory project structure
    • *
  • Faster to initialize and run but with some limitations
    • * + * + *

    Predefined Project Descriptors and Mock JDK Coverage

    + * + * + * + * + * + * + * + * + * + * + *
    Project Descriptors with Mock JDK Versions and Class Coverage
    DescriptorLanguage LevelMock JDKjava.nio.file.*
    {@link #JAVA_1_7}JDK_1_71.7No
    {@link #JAVA_8}JDK_1_81.8No
    {@link #JAVA_11}JDK_1111Yes
    {@link #JAVA_17}JDK_1711 (mapped)Yes
    {@link #JAVA_21}JDK_2121Yes
    {@link #JAVA_LATEST}HIGHEST1.7!No
    {@link #JAVA_LATEST_WITH_LATEST_JDK}HIGHESTmatches levelYes
    + * + *

    Warning: {@link #JAVA_LATEST} uses Mock JDK 1.7 despite having the highest + * language level. If you need modern JDK classes like {@code java.nio.file.Path}, + * use {@link #JAVA_LATEST_WITH_LATEST_JDK} or {@link #JAVA_11} instead. + * + *

    The {@code _ANNOTATED} variants (e.g., {@link #JAVA_11_ANNOTATED}) include JDK annotations + * for nullability and other contracts. + * + * @see IdeaTestUtil#getMockJdk(com.intellij.util.lang.JavaVersion) for mock JDK version mapping details * @see LightJavaCodeInsightFixtureTestCase4 * @see LightJavaCodeInsightFixtureTestCase5 */ @@ -90,7 +112,13 @@ public abstract class LightJavaCodeInsightFixtureTestCase extends UsefulTestCase public static final @NotNull LightProjectDescriptor JAVA_8_ANNOTATED = new ProjectDescriptor(LanguageLevel.JDK_1_8, true); public static final @NotNull LightProjectDescriptor JAVA_9 = new ProjectDescriptor(LanguageLevel.JDK_1_9); public static final @NotNull LightProjectDescriptor JAVA_9_ANNOTATED = new ProjectDescriptor(LanguageLevel.JDK_1_9, true); + /** + * Project descriptor with Java 11 language level and Mock JDK 11. + *

    Use this when your test needs {@code java.nio.file.*} classes + * ({@code Path}, {@code Paths}, {@code Files}). Mock JDKs 1.7 and 1.8 do NOT contain these classes. + */ public static final @NotNull LightProjectDescriptor JAVA_11 = new ProjectDescriptor(LanguageLevel.JDK_11); + /** Project descriptor with Java 11 and JDK annotations for nullability contracts. */ public static final @NotNull LightProjectDescriptor JAVA_11_ANNOTATED = new ProjectDescriptor(LanguageLevel.JDK_11, true); public static final @NotNull LightProjectDescriptor JAVA_12 = new ProjectDescriptor(LanguageLevel.JDK_12); public static final @NotNull LightProjectDescriptor JAVA_13 = new ProjectDescriptor(LanguageLevel.JDK_13); @@ -110,13 +138,28 @@ public abstract class LightJavaCodeInsightFixtureTestCase extends UsefulTestCase public static final @NotNull LightProjectDescriptor JAVA_25 = new ProjectDescriptor(LanguageLevel.JDK_25); public static final @NotNull LightProjectDescriptor JAVA_X = new ProjectDescriptor(LanguageLevel.JDK_X); + /** + * Project descriptor with highest language level but Mock JDK 1.7 (Java 7). + *

    Warning: Despite the name, this uses Java 7 mock JDK which does NOT + * contain {@code java.nio.file.*} classes ({@code Path}, {@code Paths}, {@code Files}). + * If you need those classes, use {@link #JAVA_LATEST_WITH_LATEST_JDK} or {@link #JAVA_11} instead. + * + * @see #JAVA_LATEST_WITH_LATEST_JDK for descriptor with matching mock JDK + * @see #JAVA_11 for tests needing java.nio.file.* classes + */ public static final @NotNull LightProjectDescriptor JAVA_LATEST = new ProjectDescriptor(LanguageLevel.HIGHEST) { @Override public Sdk getSdk() { return IdeaTestUtil.getMockJdk17(); } }; - + + /** + * Project descriptor with highest language level AND matching mock JDK. + *

    Unlike {@link #JAVA_LATEST}, this descriptor uses a mock JDK that matches + * the language level, so {@code java.nio.file.*} classes ({@code Path}, {@code Paths}, {@code Files}) + * are available. + */ public static final @NotNull LightProjectDescriptor JAVA_LATEST_WITH_LATEST_JDK = new ProjectDescriptor(LanguageLevel.HIGHEST); protected JavaCodeInsightTestFixture myFixture;