Java: move original files

Author: Jami Cogswell

java/ql/src/Likely Bugs/Frameworks/JUnit/JUnit5NonStaticInnerClassMissingNestedAnnotation.md

@@ -0,0 +1,64 @@
+# J-T-004: Non-static inner class defined in a JUnit 5 is missing a `@Nested` annotation
+
+A non-static inner class defined in a JUnit 5 test missing a `@Nested` annotation will be excluded from execution and it may indicate a misunderstanding from the programmer.
+
+## Overview
+
+JUnit tests are grouped in a class, and starting from JUnit 5 users can group the test classes in a bigger class so they can share the local environment of the enclosing class. While this helps to organize the unit tests and foster code reuse, if the inner class is not annotated with `@Nested`, the unit tests in it will fail to execute during builds.
+
+Note that static classes, whether static or not, behave as independent sets of unit tests. Thus, inner static classes do not share the information provided by the outer class with other inner classes. Thus, this rule only applies to non-static JUnit 5 inner classes.
+
+## Recommendation
+
+If you want the tests defined in an inner class to be recognized by the build plugin and be executed, annotate with `@Nested`, imported from `org.junit.jupiter.api`.
+
+## Example
+
+```java
+import org.junit.jupiter.api.Nested;
+import static org.junit.Assert.assertEquals;
+
+public class IntegerOperationTest {
+  private int i;                // Shared variable among the inner classes.
+
+  @BeforeEach
+  public void initTest() { i = 0; }
+
+  @Nested
+  public class AdditionTest {   // COMPLIANT: Inner test class annotated with `@Nested`.
+    @Test
+    public void addTest1() {    // Test of an inner class, implying `AdditionTest` is a test class.
+      assertEquals(1, i+1);
+    }
+  }
+
+  public class SubtractionTest { // NON_COMPLIANT: Inner test class missing `@Nested`.
+    @Test
+    public void addTest1() {     // Test of an inner class, implying `SubtractionTest` is a test class.
+      assertEquals(-1, i-1);
+    }
+  }
+
+  static public class MultiplicationTest {  // COMPLIANT: static test class should not be annotated as `@Nested`.
+    ...
+  }
+}
+```
+
+## Implementation Notes
+
+The `@Nested` annotation does not apply to inner static classes, since the meaning of the annotation is to mark a class as "a *non-static* inner class containing `@Test` methods to be picked up by a build system". Therefore, this rule does not aim to target static inner test classes with a `@Nested` annotation, nor does it try to enforce such correct usage of `@Nested`. Therefore, any code that resembles below is not non-compliant to this rule.
+
+``` java
+@Nested
+public static class Test6 { // COMPLIANT: Although invalid, this matter is out of the scope
+  @Test
+  public void test() {
+  }
+}
+```
+
+## References
+
+- JUnit: [Documentation on `@Nested`](https://junit.org/junit5/docs/current/api/org.junit.jupiter.api/org/junit/jupiter/api/Nested.html).
+- Baeldung: [JUnit 5 @Nested Test Classes](https://www.baeldung.com/junit-5-nested-test-classes).

java/ql/src/Likely Bugs/Frameworks/JUnit/JUnit5NonStaticInnerClassMissingNestedAnnotation.ql

@@ -0,0 +1,30 @@
+/**
+ * @id java/junit5-non-static-inner-class-missing-nested-annotation
+ * @name J-T-004: Non-static inner class defined in a JUnit5 test is missing a `@Nested` annotation
+ * @description A non-static inner class defined in a JUnit5 test missing a `@Nested` annotation
+ *              will be excluded from execution and it may indicate a misunderstanding from the
+ *              programmer.
+ * @kind problem
+ * @precision very-high
+ * @problem.severity warning
+ * @tags maintainability
+ *       correctness
+ */
+
+import java
+
+class JUnit5TestClass extends Class {
+  JUnit5TestClass() {
+    this.getAMethod().getAnAnnotation().getType().hasQualifiedName("org.junit.jupiter.api", "Test")
+  }
+}
+
+from JUnit5TestClass testClass // `TestClass` by definition should have at least one @Test method.
+where
+  not testClass.isStatic() and
+  testClass instanceof InnerClass and // `InnerClass` is by definition a non-static nested class.
+  not exists(Annotation annotation |
+    annotation.getType().hasQualifiedName("org.junit.jupiter.api", "Nested") and
+    annotation.getAnnotatedElement() = testClass
+  )
+select testClass, "This JUnit5 inner test class lacks a @Nested annotation."

java/ql/test/query-tests/Likely Bugs/Frameworks/JUnit/AnnotationTest.java

@@ -0,0 +1,44 @@
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Nested;
+
+public class AnnotationTest {
+  @Nested
+  public class Test1 { // COMPLIANT: Inner test class has `@Nested`
+    @Test
+    public void test() {
+    }
+  }
+
+  public class Test2 { // NON_COMPLIANT: Inner test class is missing a `@Nested`
+    @Test
+    public void test() {
+    }
+  }
+
+  public class Test3 { // COMPLIANT: Since it is empty, it is not a test class
+  }
+
+  public class Test4 { // COMPLIANT: Since no methods have `@Test`, it is not a test class
+    public void f() {
+    }
+
+    public void g() {
+    }
+
+    public void h() {
+    }
+  }
+
+  public static class Test5 { // COMPLIANT: Static inner test classes don't need `@Nested`
+    @Test
+    public void test() {
+    }
+  }
+
+  @Nested
+  public static class Test6 { // COMPLIANT: Although invalid, this matter is out of the scope (see Implementation Details)
+    @Test
+    public void test() {
+    }
+  }
+}

java/ql/test/query-tests/Likely Bugs/Frameworks/JUnit/JUnit5NonStaticInnerClassMissingNestedAnnotation.expected

@@ -0,0 +1 @@
+| AnnotationTest.java:12:16:12:20 | Test2 | This JUnit5 inner test class lacks a @Nested annotation. |

java/ql/test/query-tests/Likely Bugs/Frameworks/JUnit/JUnit5NonStaticInnerClassMissingNestedAnnotation.qlref

@@ -0,0 +1 @@
+Likely Bugs/Frameworks/JUnit/JUnit5NonStaticInnerClassMissingNestedAnnotation.ql

java/ql/test/query-tests/Likely Bugs/Frameworks/JUnit/options

@@ -0,0 +1 @@
+//semmle-extractor-options: --javac-args -cp ${testdir}/../../../../stubs/junit-jupiter-api-5.2.0