mirror of
https://gitflic.ru/project/openide/openide.git
synced 2026-09-27 10:03:11 +07:00
docs testFramework: javadocs on DefaultLightProjectDescriptor and Mock JDKs
GitOrigin-RevId: f6a7c8d1191cd0e3da052eb7a6e78b4545c639ba
This commit is contained in:
Leonid Shalupov
committed by
intellij-monorepo-bot
intellij-monorepo-bot
parent
0b50d9cc68
commit
da03ff655c
@@ -114,6 +114,40 @@ public final class IdeaTestUtil {
|
||||
return getMockJdk(level.toJavaVersion());
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a mock JDK for the specified Java version.
|
||||
*
|
||||
* <h3>Version Mapping</h3>
|
||||
* Mock JDKs are simplified JDKs with limited class coverage. The requested version
|
||||
* is mapped to the nearest available mock JDK:
|
||||
* <ul>
|
||||
* <li>Java 4-6 → Mock JDK 1.7</li>
|
||||
* <li>Java 7 → Mock JDK 1.7</li>
|
||||
* <li>Java 8 → Mock JDK 1.8</li>
|
||||
* <li>Java 9-10 → Mock JDK 9</li>
|
||||
* <li>Java 11-20 → Mock JDK 11</li>
|
||||
* <li>Java 21-24 → Mock JDK 21</li>
|
||||
* <li>Java 25+ → Mock JDK 25</li>
|
||||
* </ul>
|
||||
*
|
||||
* <h3>Class Coverage</h3>
|
||||
* <table border="1">
|
||||
* <caption>Mock JDK Class Coverage</caption>
|
||||
* <tr><th>Mock JDK</th><th>java.io.File</th><th>java.nio.file.*</th><th>Source</th></tr>
|
||||
* <tr><td>1.7</td><td>Yes</td><td>No</td><td>community/java/mockJDK-1.7/</td></tr>
|
||||
* <tr><td>1.8</td><td>Yes</td><td>No</td><td>community/java/mockJDK-1.8/</td></tr>
|
||||
* <tr><td>11+</td><td>Yes</td><td>Yes</td><td>Maven: org.jetbrains.mockjdk:mockjdk-base-java</td></tr>
|
||||
* </table>
|
||||
*
|
||||
* <h3>Common Pitfall</h3>
|
||||
* 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).
|
||||
*
|
||||
* <p><b>Warning:</b> 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.
|
||||
*
|
||||
* <p><b>Warning:</b> 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).
|
||||
*
|
||||
* <p><b>Warning:</b> The method name "17" refers to version "1.7" (Java 7), NOT Java 17.
|
||||
* For Java 17, use {@code getMockJdk(JavaVersion.compose(17))}.
|
||||
*
|
||||
* <p>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.
|
||||
*
|
||||
* <p><b>Warning:</b> 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).
|
||||
*
|
||||
* <p><b>Warning:</b> The method name "18" refers to version "1.8" (Java 8), NOT Java 18.
|
||||
* For Java 18, use {@code getMockJdk(JavaVersion.compose(18))}.
|
||||
*
|
||||
* <p>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.
|
||||
*
|
||||
* <p>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));
|
||||
}
|
||||
|
||||
+16
@@ -43,6 +43,22 @@ public class DefaultLightProjectDescriptor extends LightProjectDescriptor {
|
||||
return JAVA_MODULE_ENTITY_TYPE_ID_NAME;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the SDK for tests using this descriptor.
|
||||
*
|
||||
* <p><b>Default:</b> Returns {@link IdeaTestUtil#getMockJdk17()} (Mock JDK 1.7, Java 7).
|
||||
*
|
||||
* <p><b>Important:</b> 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:
|
||||
* <pre>{@code
|
||||
* private static final LightProjectDescriptor DESCRIPTOR =
|
||||
* new DefaultLightProjectDescriptor(IdeaTestUtil::getMockJdk11);
|
||||
* }</pre>
|
||||
*
|
||||
* @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();
|
||||
|
||||
+44
-1
@@ -29,6 +29,28 @@ import java.io.File;
|
||||
* <li>Creates a simpler in-memory project structure</li>
|
||||
* <li>Faster to initialize and run but with some limitations</li>
|
||||
* </ul>
|
||||
*
|
||||
* <h3>Predefined Project Descriptors and Mock JDK Coverage</h3>
|
||||
* <table border="1">
|
||||
* <caption>Project Descriptors with Mock JDK Versions and Class Coverage</caption>
|
||||
* <tr><th>Descriptor</th><th>Language Level</th><th>Mock JDK</th><th>java.nio.file.*</th></tr>
|
||||
* <tr><td>{@link #JAVA_1_7}</td><td>JDK_1_7</td><td>1.7</td><td>No</td></tr>
|
||||
* <tr><td>{@link #JAVA_8}</td><td>JDK_1_8</td><td>1.8</td><td>No</td></tr>
|
||||
* <tr><td>{@link #JAVA_11}</td><td>JDK_11</td><td>11</td><td>Yes</td></tr>
|
||||
* <tr><td>{@link #JAVA_17}</td><td>JDK_17</td><td>11 (mapped)</td><td>Yes</td></tr>
|
||||
* <tr><td>{@link #JAVA_21}</td><td>JDK_21</td><td>21</td><td>Yes</td></tr>
|
||||
* <tr><td>{@link #JAVA_LATEST}</td><td>HIGHEST</td><td><b>1.7!</b></td><td>No</td></tr>
|
||||
* <tr><td>{@link #JAVA_LATEST_WITH_LATEST_JDK}</td><td>HIGHEST</td><td>matches level</td><td>Yes</td></tr>
|
||||
* </table>
|
||||
*
|
||||
* <p><b>Warning:</b> {@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.
|
||||
*
|
||||
* <p>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.
|
||||
* <p>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 <b>Mock JDK 1.7 (Java 7)</b>.
|
||||
* <p><b>Warning:</b> 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.
|
||||
* <p>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;
|
||||
|
||||
Reference in New Issue
Block a user