[testFramework] docs around test fixtures and differences between light/heavy variants of them

GitOrigin-RevId: d724d6980a961303da030d9950124b2c7126d1ec

java/testFramework/src/com/intellij/testFramework/fixtures/JavaCodeInsightTestFixture.java

@@ -13,6 +13,12 @@ import org.jetbrains.annotations.NotNull;
 
 /**
  * A {@link CodeInsightTestFixture} extended a bit for Java-dependent tests.
+ * <p>
+ * Can be created using {@link JavaTestFixtureFactory#createCodeInsightFixture(IdeaProjectTestFixture)}.
+ *
+ * @see LightJavaCodeInsightFixtureTestCase
+ * @see LightJavaCodeInsightFixtureTestCase4
+ * @see LightJavaCodeInsightFixtureTestCase5
  */
 public interface JavaCodeInsightTestFixture extends CodeInsightTestFixture {
   JavaPsiFacadeEx getJavaFacade();

java/testFramework/src/com/intellij/testFramework/fixtures/JavaTestFixtureFactory.java

@@ -4,7 +4,9 @@ package com.intellij.testFramework.fixtures;
 import com.intellij.testFramework.fixtures.impl.JavaTestFixtureFactoryImpl;
 import org.jetbrains.annotations.NotNull;
 
-
+/**
+ * @see IdeaTestFixtureFactory
+ */
 public abstract class JavaTestFixtureFactory {
   private static final JavaTestFixtureFactory ourInstance = new JavaTestFixtureFactoryImpl();
 
@@ -12,13 +14,14 @@ public abstract class JavaTestFixtureFactory {
     return ourInstance;
   }
 
-  public abstract TestFixtureBuilder<IdeaProjectTestFixture> createLightFixtureBuilder(@NotNull String name);
+  public abstract @NotNull TestFixtureBuilder<IdeaProjectTestFixture> createLightFixtureBuilder(@NotNull String name);
 
-  public abstract JavaCodeInsightTestFixture createCodeInsightFixture(IdeaProjectTestFixture projectFixture);
+  public abstract @NotNull JavaCodeInsightTestFixture createCodeInsightFixture(IdeaProjectTestFixture projectFixture);
 
-  public abstract JavaCodeInsightTestFixture createCodeInsightFixture(IdeaProjectTestFixture projectFixture, TempDirTestFixture tempDirFixture);
+  public abstract @NotNull JavaCodeInsightTestFixture createCodeInsightFixture(IdeaProjectTestFixture projectFixture,
+                                                                               TempDirTestFixture tempDirFixture);
 
-  public static TestFixtureBuilder<IdeaProjectTestFixture> createFixtureBuilder(@NotNull String name) {
+  public static @NotNull TestFixtureBuilder<IdeaProjectTestFixture> createFixtureBuilder(@NotNull String name) {
     return IdeaTestFixtureFactory.getFixtureFactory().createFixtureBuilder(name);
   }
 }

java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase5.kt

@@ -13,7 +13,6 @@ import org.junit.jupiter.api.extension.RegisterExtension
 
 /**
  * A wrapper around [LightJavaCodeInsightFixtureTestCase] that is JUnit 5-compatible.
- * 
  * @see LightJavaCodeInsightFixtureTestCase
  * @see LightJavaCodeInsightFixtureTestCase4
  */

java/testFramework/src/com/intellij/testFramework/fixtures/impl/JavaTestFixtureFactoryImpl.java

@@ -13,17 +13,18 @@ public final class JavaTestFixtureFactoryImpl extends JavaTestFixtureFactory {
   }
 
   @Override
-  public JavaCodeInsightTestFixture createCodeInsightFixture(IdeaProjectTestFixture projectFixture) {
+  public @NotNull JavaCodeInsightTestFixture createCodeInsightFixture(IdeaProjectTestFixture projectFixture) {
     return new JavaCodeInsightTestFixtureImpl(projectFixture, new TempDirTestFixtureImpl());
   }
 
   @Override
-  public JavaCodeInsightTestFixture createCodeInsightFixture(IdeaProjectTestFixture projectFixture, TempDirTestFixture tempDirFixture) {
+  public @NotNull JavaCodeInsightTestFixture createCodeInsightFixture(IdeaProjectTestFixture projectFixture,
+                                                                      TempDirTestFixture tempDirFixture) {
     return new JavaCodeInsightTestFixtureImpl(projectFixture, tempDirFixture);
   }
 
   @Override
-  public TestFixtureBuilder<IdeaProjectTestFixture> createLightFixtureBuilder(@NotNull String name) {
+  public @NotNull TestFixtureBuilder<IdeaProjectTestFixture> createLightFixtureBuilder(@NotNull String name) {
     return new LightTestFixtureBuilderImpl<>(new LightIdeaTestFixtureImpl(ourJavaProjectDescriptor, name));
   }
 

platform/testFramework/src/com/intellij/testFramework/fixtures/IdeaProjectTestFixture.java

@@ -9,13 +9,22 @@ import org.jetbrains.annotations.NotNull;
 
 /**
  * This is to be provided by the test framework and not by plugin authors.
+ * <p>
+ * A heavy variant can be created using a {@link TestFixtureBuilder} from {@link IdeaTestFixtureFactory#createFixtureBuilder(String)}.
+ * <p>
+ * A light variant can be created using a {@link TestFixtureBuilder} from {@link IdeaTestFixtureFactory#createLightFixtureBuilder(String)}.
  *
- * @see IdeaTestFixtureFactory#createFixtureBuilder(String)
- * @see IdeaTestFixtureFactory#createLightFixtureBuilder(String)
+ * @see <a href="https://plugins.jetbrains.com/docs/intellij/tests-and-fixtures.html">Tests and Fixtures (IntelliJ Platform Docs)</a>
  */
 public interface IdeaProjectTestFixture extends IdeaTestFixture {
   Project getProject();
 
+  /**
+   * If this is a light fixture, returns the only module present in the project.
+   * <p>
+   * If this is a heavy fixture, returns the first/primary module.
+   * To access other modules present in the project, use {@link com.intellij.openapi.module.ModuleManager ModuleManager}.
+   */
   Module getModule();
 
   default @NotNull Disposable getTestRootDisposable() {

platform/testFramework/src/com/intellij/testFramework/fixtures/IdeaTestFixture.java

@@ -3,6 +3,8 @@ package com.intellij.testFramework.fixtures;
 
 /**
  * This is to be provided by the test framework and not by plugin authors.
+ *
+ * @see <a href="https://plugins.jetbrains.com/docs/intellij/tests-and-fixtures.html">Tests and Fixtures (IntelliJ Platform Docs)</a>
  */
 public interface IdeaTestFixture {
   /**