From 2a6109afe2077741cbd0180743d3a63e92965ae8 Mon Sep 17 00:00:00 2001 From: Bartek Pacia Date: Fri, 18 Apr 2025 13:52:35 +0000 Subject: [PATCH] [test framework] add some documentation Also includes some Grazie-suggested typo fixes. Merge-request: IJ-MR-159365 Merged-by: Bartek Pacia GitOrigin-RevId: 60ac557d8a16d35dd2b61d748d805b9a2e1e8143 --- .../intellij/codeInsight/package-info.java | 8 ++ .../src/com/intellij/codeInsight/package.html | 22 ------ .../JavaCodeInsightFixtureTestCase.java | 15 +++- .../fixtures/JavaCodeInsightTestFixture.java | 11 +-- .../LightJavaCodeInsightFixtureTestCase.java | 11 ++- .../LightJavaCodeInsightFixtureTestCase4.kt | 6 ++ .../LightJavaCodeInsightFixtureTestCase5.kt | 6 ++ .../com/intellij/testFramework/package.html | 4 - .../junit5/src/package-info.java | 10 +++ .../FileBasedTestCaseHelper.java | 45 ++++++++--- .../testFramework/UsefulTestCase.java | 26 +++--- .../fixtures/CodeInsightTestFixture.java | 79 +++++++++++++------ .../intellij/testFramework/package-info.java | 8 ++ 13 files changed, 172 insertions(+), 79 deletions(-) create mode 100644 java/openapi/src/com/intellij/codeInsight/package-info.java delete mode 100644 java/openapi/src/com/intellij/codeInsight/package.html delete mode 100644 java/testFramework/src/com/intellij/testFramework/package.html create mode 100644 platform/testFramework/junit5/src/package-info.java create mode 100644 platform/testFramework/src/com/intellij/testFramework/package-info.java diff --git a/java/openapi/src/com/intellij/codeInsight/package-info.java b/java/openapi/src/com/intellij/codeInsight/package-info.java new file mode 100644 index 000000000000..467dcf9f421b --- /dev/null +++ b/java/openapi/src/com/intellij/codeInsight/package-info.java @@ -0,0 +1,8 @@ +// Copyright 2000-2025 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. +/** + * Provides interfaces for working with highlighting in standard IDE editors, interfaces + * and classes for defining intention actions and additional functionality related to background + * code analysis in the IDE. + * @see Code Insight (IntelliJ Platform Docs) + */ +package com.intellij.codeInsight; diff --git a/java/openapi/src/com/intellij/codeInsight/package.html b/java/openapi/src/com/intellij/codeInsight/package.html deleted file mode 100644 index b8d21861c132..000000000000 --- a/java/openapi/src/com/intellij/codeInsight/package.html +++ /dev/null @@ -1,22 +0,0 @@ - - - - -Provides interfaces for working with highlighting in standard IDEA editors, interfaces -and classes for defining intention actions and additional functionality related to background -code analysis in IDEA. - diff --git a/java/testFramework/src/com/intellij/testFramework/fixtures/JavaCodeInsightFixtureTestCase.java b/java/testFramework/src/com/intellij/testFramework/fixtures/JavaCodeInsightFixtureTestCase.java index 1566cfa297ca..a73a75ef7c19 100644 --- a/java/testFramework/src/com/intellij/testFramework/fixtures/JavaCodeInsightFixtureTestCase.java +++ b/java/testFramework/src/com/intellij/testFramework/fixtures/JavaCodeInsightFixtureTestCase.java @@ -19,6 +19,19 @@ import org.jetbrains.annotations.NotNull; import java.io.File; +/** + * A JUnit 3-compatible {@link UsefulTestCase} which is based around a {@link JavaCodeInsightTestFixture}. + *

+ * This class is similar to {@link LightJavaCodeInsightFixtureTestCase}, but with some differences: + *

+ * It can be considered a "heavy test", even though it doesn't inherit from {@link com.intellij.testFramework.HeavyPlatformTestCase}. + * + * @see Light and Heavy Tests (IntelliJ Platform Docs) + */ @TestDataPath("$CONTENT_ROOT/testData") public abstract class JavaCodeInsightFixtureTestCase extends UsefulTestCase implements TestIndexingModeSupporter { protected JavaCodeInsightTestFixture myFixture; @@ -87,7 +100,7 @@ public abstract class JavaCodeInsightFixtureTestCase extends UsefulTestCase impl return PathManager.getHomePath().replace(File.separatorChar, '/') + getBasePath(); } - protected void tuneFixture(JavaModuleFixtureBuilder moduleBuilder) throws Exception {} + protected void tuneFixture(JavaModuleFixtureBuilder moduleBuilder) throws Exception { } protected Project getProject() { return myFixture.getProject(); diff --git a/java/testFramework/src/com/intellij/testFramework/fixtures/JavaCodeInsightTestFixture.java b/java/testFramework/src/com/intellij/testFramework/fixtures/JavaCodeInsightTestFixture.java index b37d30a469e5..ddb61fc3a575 100644 --- a/java/testFramework/src/com/intellij/testFramework/fixtures/JavaCodeInsightTestFixture.java +++ b/java/testFramework/src/com/intellij/testFramework/fixtures/JavaCodeInsightTestFixture.java @@ -11,20 +11,21 @@ import org.jetbrains.annotations.NonNls; import org.jetbrains.annotations.NotNull; +/** + * A {@link CodeInsightTestFixture} extended a bit for Java-dependent tests. + */ public interface JavaCodeInsightTestFixture extends CodeInsightTestFixture { JavaPsiFacadeEx getJavaFacade(); PsiClass addClass(@Language("JAVA") final @NotNull @NonNls String classText); /** - * Finds class by given fully-qualified name in {@link GlobalSearchScope#allScope(Project)}. + * Finds class by given fully qualified name in {@link GlobalSearchScope#allScope(Project)}. * * @param name Qualified name of class to find. * @return Class instance. */ - @NotNull - PsiClass findClass(@NotNull @NonNls String name); + @NotNull PsiClass findClass(@NotNull @NonNls String name); - @NotNull - PsiPackage findPackage(@NotNull @NonNls String name); + @NotNull PsiPackage findPackage(@NotNull @NonNls String name); } diff --git a/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java b/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java index 4bd0e9dafdc6..a150728ea585 100644 --- a/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java +++ b/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase.java @@ -20,6 +20,15 @@ import org.jetbrains.annotations.NotNull; import java.io.File; /** + * A JUnit 3-compatible {@link UsefulTestCase} which is based around a {@link JavaCodeInsightTestFixture}. + *

+ * This class is similar to {@link JavaCodeInsightFixtureTestCase}, but with some differences: + *

* @see LightJavaCodeInsightFixtureTestCase4 * @see LightJavaCodeInsightFixtureTestCase5 */ @@ -210,4 +219,4 @@ public abstract class LightJavaCodeInsightFixtureTestCase extends UsefulTestCase public @NotNull IndexingMode getIndexingMode() { return myIndexingMode; } -} \ No newline at end of file +} diff --git a/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase4.kt b/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase4.kt index 18d08b5a6806..198553b31ee3 100644 --- a/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase4.kt +++ b/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase4.kt @@ -10,6 +10,12 @@ import org.junit.rules.RuleChain import org.junit.rules.TestName import org.junit.rules.TestRule +/** + * A wrapper around [LightJavaCodeInsightFixtureTestCase] that is JUnit 4-compatible. + * + * @see LightJavaCodeInsightFixtureTestCase + * @see LightJavaCodeInsightFixtureTestCase5 + */ @TestDataPath("\$CONTENT_ROOT/testData") abstract class LightJavaCodeInsightFixtureTestCase4( projectDescriptor: LightProjectDescriptor? = null, diff --git a/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase5.kt b/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase5.kt index 21a9097be5ca..2ec706b98906 100644 --- a/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase5.kt +++ b/java/testFramework/src/com/intellij/testFramework/fixtures/LightJavaCodeInsightFixtureTestCase5.kt @@ -11,6 +11,12 @@ import org.junit.jupiter.api.extension.BeforeEachCallback import org.junit.jupiter.api.extension.ExtensionContext import org.junit.jupiter.api.extension.RegisterExtension +/** + * A wrapper around [LightJavaCodeInsightFixtureTestCase] that is JUnit 5-compatible. + * + * @see LightJavaCodeInsightFixtureTestCase + * @see LightJavaCodeInsightFixtureTestCase4 + */ @TestDataPath("\$CONTENT_ROOT/testData") abstract class LightJavaCodeInsightFixtureTestCase5 (projectDescriptor: LightProjectDescriptor? = null) { diff --git a/java/testFramework/src/com/intellij/testFramework/package.html b/java/testFramework/src/com/intellij/testFramework/package.html deleted file mode 100644 index 960f5c5ad199..000000000000 --- a/java/testFramework/src/com/intellij/testFramework/package.html +++ /dev/null @@ -1,4 +0,0 @@ - - -Provides a test framework for writing tests which use IDEA projects, PSI and other services. - diff --git a/platform/testFramework/junit5/src/package-info.java b/platform/testFramework/junit5/src/package-info.java new file mode 100644 index 000000000000..7f9c5cb983d0 --- /dev/null +++ b/platform/testFramework/junit5/src/package-info.java @@ -0,0 +1,10 @@ +// Copyright 2000-2025 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. + +/** + * Provides a JUnit 5-based test framework for writing tests which use IDE projects, PSI and other services. + *

+ * For examples, see {@link com.intellij.testFramework.junit5.showcase}. + *

+ * This package is a successor to {@link com.intellij.testFramework}. + */ +package com.intellij.testFramework.junit5; diff --git a/platform/testFramework/src/com/intellij/testFramework/FileBasedTestCaseHelper.java b/platform/testFramework/src/com/intellij/testFramework/FileBasedTestCaseHelper.java index b217de76ddbc..bd78b72c5567 100644 --- a/platform/testFramework/src/com/intellij/testFramework/FileBasedTestCaseHelper.java +++ b/platform/testFramework/src/com/intellij/testFramework/FileBasedTestCaseHelper.java @@ -5,24 +5,47 @@ import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; /** - * Should be implemented by a test together with annotation @RunWith(com.intellij.testFramework.Parameterized.class) - * in order to get test run on all test data files located in directory. The desired directory could be configured - * whether by implementing {@link FileBasedTestCaseHelperEx#getRelativeBasePath()} or by annotating test case - * with {@link TestDataPath} (annotation would enable additional test assistance support, e.g. - * navigation from test data to test class/method as well as starting tests right from test data files). - *

- * BTW @RunWith works also on abstract super classes. + * Should be implemented by a test class together with the annotation {@code @RunWith(com.intellij.testFramework.Parameterized.class)} + * in order to get test run on all test data files located in directory. + *

+ * The desired directory can be configured by implementing + * {@link FileBasedTestCaseHelperEx#getRelativeBasePath()} + * or by annotating the test case class with {@link TestDataPath}. + * Annotating with {@link TestDataPath} enables additional test assistance support, like: + *

+ * N.B. {@code @RunWith} works also on abstract super classes. + * * @see LightPlatformCodeInsightTestCase#params(Class) */ public interface FileBasedTestCaseHelper { /** - * @return for 'before' files should return core file name or null otherwise + *

Example 1

+ * Input: {@code afterMethodCanBeStatic.java} + *

+ * Output: {@code null} + *

Example 2

+ * Input: {@code beforeMethodCanBeStatic.java} + *

+ * Output: {@code MethodCanBeStatic.java} + * + * @return the "core part" of the file name if the file is an "after" file, or null otherwise */ - @Nullable - String getFileSuffix(@NotNull String fileName); + @Nullable String getFileSuffix(@NotNull String fileName); /** - * @return for 'after' files should return core file name or null otherwise + *

Example 1

+ * Input: {@code afterMethodCanBeStatic.java} + *

+ * Output: {@code MethodCanBeStatic.java} + *

Example 2

+ * Input: {@code beforeMethodCanBeStatic.java} + *

+ * Output: {@code null} + * + * @return the "core part" of the file name if the file is an "after" file, or null otherwise */ default @Nullable String getBaseName(@NotNull String fileAfterSuffix) { return null; diff --git a/platform/testFramework/src/com/intellij/testFramework/UsefulTestCase.java b/platform/testFramework/src/com/intellij/testFramework/UsefulTestCase.java index 90aab2d945f1..f1fd0bb781aa 100644 --- a/platform/testFramework/src/com/intellij/testFramework/UsefulTestCase.java +++ b/platform/testFramework/src/com/intellij/testFramework/UsefulTestCase.java @@ -77,11 +77,15 @@ import static com.intellij.testFramework.common.TestEnvironmentKt.initializeTest import static org.junit.Assume.assumeTrue; /** - * This class is compatible with both JUnit 3 and JUnit 4, - * but not JUnit 5 (see the module intellij.platform.testFramework.junit5 instead). + * This class is compatible with both JUnit 3 and JUnit 4, but not JUnit 5. *

- * To use JUnit 4, annotate your test subclass with {@code @RunWith(JUnit4.class)} or any other (like {@code Parametrized.class}), - * and you are all set. + * To use JUnit 3, make the name of your test methods start with {@code test}, as per the JUnit 3 convention. + *

+ * To use JUnit 4, annotate your test subclass with {@code @RunWith(JUnit4.class)} or any other runner (like {@code Parametrized.class}). + *

+ * For JUnit 5 support, + * see the {@code intellij.platform.testFramework.junit5} module in {@code community/platform/testFramework/junit5}. + *

Caveats

* If you're looking for JUnit 4 for Assume support and still have JUnit 3 tests, * consider using {@code @RunWith(JUnit38AssumeSupportRunner.class)}. *

@@ -90,9 +94,9 @@ import static org.junit.Assume.assumeTrue; *

* Don't define {@code @Rule}s calling {@linkplain #runBare()}, just subclassing this class (directly or indirectly) is enough. *

- * The execution order is the following: + *

Execution order

*