2025 init

pmd-documentation/DetachedTestCase.md

@@ -0,0 +1,32 @@
+
+# DetachedTestCase
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/errorprone.xml/DetachedTestCase -format <output format>`
+
+*Description:*
+
+The method appears to be a test case since it has public or default visibility,
+non-static access, no arguments, no return value, has no annotations, but is a
+member of a class that has one or more JUnit test cases. If it is a utility
+method, it should likely have private visibility. If it is an ignored test, it
+should be annotated with @Test and @Ignore.
+        
+
+*Example:*
+```java
+
+
+public class MyTest {
+    @Test
+    public void someTest() {
+    }
+
+    // violation: Not annotated
+    public void someOtherTest () {
+    }
+
+}
+
+        
+```

pmd-documentation/JUnit4SuitesShouldUseSuiteAnnotation.md

@@ -0,0 +1,30 @@
+
+# JUnit4SuitesShouldUseSuiteAnnotation
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/bestpractices.xml/JUnit4SuitesShouldUseSuiteAnnotation -format <output format>`
+
+*Description:*
+
+In JUnit 3, test suites are indicated by the suite() method. In JUnit 4, suites are indicated
+through the @RunWith(Suite.class) annotation.
+        
+
+*Example:*
+```java
+
+
+public class BadExample extends TestCase{
+
+    public static Test suite(){
+        return new Suite();
+    }
+}
+
+@RunWith(Suite.class)
+@SuiteClasses( { TestOne.class, TestTwo.class })
+public class GoodTest {
+}
+
+        
+```

pmd-documentation/JUnitSpelling.md

@@ -0,0 +1,26 @@
+
+# JUnitSpelling
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/errorprone.xml/JUnitSpelling -format <output format>`
+
+*Description:*
+
+            In JUnit 3, the setUp method is used to set up all data entities required in running tests.
+            The tearDown method is used to clean up all data entities required in running tests.
+            You should not misspell method name if you want your test to set up and clean up everything correctly.
+        
+
+*Example:*
+```java
+
+
+import junit.framework.*;
+
+public class Foo extends TestCase {
+    public void setup() {}    // oops, should be setUp
+    public void TearDown() {} // oops, should be tearDown
+}
+
+        
+```

pmd-documentation/JUnitStaticSuite.md

@@ -0,0 +1,24 @@
+
+# JUnitStaticSuite
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/errorprone.xml/JUnitStaticSuite -format <output format>`
+
+*Description:*
+
+The suite() method in a JUnit test needs to be both public and static.
+        
+
+*Example:*
+```java
+
+
+import junit.framework.*;
+
+public class Foo extends TestCase {
+    public void suite() {}         // oops, should be static
+    private static void suite() {} // oops, should be public
+}
+
+        
+```

pmd-documentation/JUnitUseExpected.md

@@ -0,0 +1,33 @@
+
+# JUnitUseExpected
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/bestpractices.xml/JUnitUseExpected -format <output format>`
+
+*Description:*
+
+In JUnit4, use the @Test(expected) annotation to denote tests that should throw exceptions.
+        
+
+*Example:*
+```java
+
+
+public class MyTest {
+    @Test
+    public void testBad() {
+        try {
+            doSomething();
+            fail("should have thrown an exception");
+        } catch (Exception e) {
+        }
+    }
+
+    @Test(expected=Exception.class)
+    public void testGood() {
+        doSomething();
+    }
+}
+
+        
+```

pmd-documentation/UnitTestAssertionsShouldIncludeMessage.md

@@ -0,0 +1,27 @@
+
+# UnitTestAssertionsShouldIncludeMessage
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/bestpractices.xml/UnitTestAssertionsShouldIncludeMessage -format <output format>`
+
+*Description:*
+
+JUnit assertions should include an informative message - i.e., use the three-argument version of
+assertEquals(), not the two-argument version.
+        
+
+*Example:*
+```java
+
+
+public class Foo extends TestCase {
+    public void testSomething() {
+        assertEquals("foo", "bar");
+        // Use the form:
+        // assertEquals("Foo does not equals bar", "foo", "bar");
+        // instead
+    }
+}
+
+        
+```

pmd-documentation/UnitTestContainsTooManyAsserts.md

@@ -0,0 +1,36 @@
+
+# UnitTestContainsTooManyAsserts
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/bestpractices.xml/UnitTestContainsTooManyAsserts -format <output format>`
+
+*Description:*
+
+Unit tests should not contain too many asserts. Many asserts are indicative of a complex test, for which
+it is harder to verify correctness.  Consider breaking the test scenario into multiple, shorter test scenarios.
+Customize the maximum number of assertions used by this Rule to suit your needs.
+
+This rule checks for JUnit4, JUnit5 and TestNG Tests, as well as methods starting with "test".
+        
+
+*Example:*
+```java
+
+
+public class MyTestCase extends TestCase {
+    // Ok
+    public void testMyCaseWithOneAssert() {
+        boolean myVar = false;
+        assertFalse("should be false", myVar);
+    }
+
+    // Bad, too many asserts (assuming max=1)
+    public void testMyCaseWithMoreAsserts() {
+        boolean myVar = false;
+        assertFalse("myVar should be false", myVar);
+        assertEquals("should equals false", false, myVar);
+    }
+}
+
+        
+```

pmd-documentation/UnitTestShouldIncludeAssert.md

@@ -0,0 +1,27 @@
+
+# UnitTestShouldIncludeAssert
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/bestpractices.xml/UnitTestShouldIncludeAssert -format <output format>`
+
+*Description:*
+
+JUnit tests should include at least one assertion.  This makes the tests more robust, and using assert
+with messages provide the developer a clearer idea of what the test does.
+        
+
+*Example:*
+```java
+
+
+public class Foo extends TestCase {
+   public void testSomething() {
+      Bar b = findBar();
+   // This is better than having a NullPointerException
+   // assertNotNull("bar not found", b);
+   b.work();
+   }
+}
+
+        
+```

pmd-documentation/UnitTestShouldUseAfterAnnotation.md

@@ -0,0 +1,30 @@
+
+# UnitTestShouldUseAfterAnnotation
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/bestpractices.xml/UnitTestShouldUseAfterAnnotation -format <output format>`
+
+*Description:*
+
+In JUnit 3, the tearDown method was used to clean up all data entities required in running tests.
+JUnit 4 skips the tearDown method and executes all methods annotated with @After after running each test.
+JUnit 5 introduced @AfterEach and @AfterAll annotations to execute methods after each test or after all tests in the class, respectively.
+        
+
+*Example:*
+```java
+
+
+public class MyTest {
+    public void tearDown() {
+        bad();
+    }
+}
+public class MyTest2 {
+    @After public void tearDown() {
+        good();
+    }
+}
+
+        
+```

pmd-documentation/UnitTestShouldUseBeforeAnnotation.md

@@ -0,0 +1,30 @@
+
+# UnitTestShouldUseTestAnnotation
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/bestpractices.xml/UnitTestShouldUseTestAnnotation -format <output format>`
+
+*Description:*
+
+In JUnit 3, the setUp method was used to set up all data entities required in running tests.
+JUnit 4 skips the setUp method and executes all methods annotated with @Before before all tests.
+JUnit 5 introduced @BeforeEach and @BeforeAll annotations to execute methods before each test or before all tests in the class, respectively.
+        
+
+*Example:*
+```java
+
+
+public class MyTest {
+    public void setUp() {
+        bad();
+    }
+}
+public class MyTest2 {
+    @Before public void setUp() {
+        good();
+    }
+}
+
+        
+```

pmd-documentation/UnitTestShouldUseTestAnnotation.md

@@ -0,0 +1,30 @@
+
+# UnitTestShouldUseTestAnnotation
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/bestpractices.xml/UnitTestShouldUseTestAnnotation -format <output format>`
+
+*Description:*
+
+In JUnit 3, the framework executed all methods which started with the word test as a unit test.
+In JUnit 4, only methods annotated with the @Test annotation are executed.
+In JUnit 5, one of the following annotations should be used for tests: @Test, @RepeatedTest, @TestFactory, @TestTemplate or @ParameterizedTest.
+        
+
+*Example:*
+```java
+
+
+public class MyTest {
+    public void testBad() {
+        doSomething();
+    }
+
+    @Test
+    public void testGood() {
+        doSomething();
+    }
+}
+
+        
+```

pmd-documentation/UnnecessaryBooleanAssertion.md

@@ -0,0 +1,26 @@
+
+# UnnecessaryBooleanAssertion
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/errorprone.xml/UnnecessaryBooleanAssertion -format <output format>`
+
+*Description:*
+
+A JUnit test assertion with a boolean literal is unnecessary since it always will evaluate to the same thing.
+Consider using flow control (in case of assertTrue(false) or similar) or simply removing
+statements like assertTrue(true) and assertFalse(false).  If you just want a test to halt after finding
+an error, use the fail() method and provide an indication message of why it did.
+        
+
+*Example:*
+```java
+
+
+public class SimpleTest extends TestCase {
+    public void testX() {
+        assertTrue(true);       // serves no real purpose
+    }
+}
+
+        
+```

pmd-documentation/UseAssertEqualsInsteadOfAssertTrue.md

@@ -0,0 +1,25 @@
+
+# UseAssertEqualsInsteadOfAssertTrue
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/bestpractices.xml/UseAssertEqualsInsteadOfAssertTrue -format <output format>`
+
+*Description:*
+
+This rule detects JUnit assertions in object equality. These assertions should be made by more specific methods, like assertEquals.
+        
+
+*Example:*
+```java
+
+
+public class FooTest extends TestCase {
+    void testCode() {
+        Object a, b;
+        assertTrue(a.equals(b));                    // bad usage
+        assertEquals("a should equals b", a, b);    // good usage
+    }
+}
+
+        
+```

pmd-documentation/UseAssertNullInsteadOfAssertTrue.md

@@ -0,0 +1,28 @@
+
+# UseAssertNullInsteadOfAssertTrue
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/bestpractices.xml/UseAssertNullInsteadOfAssertTrue -format <output format>`
+
+*Description:*
+
+This rule detects JUnit assertions in object references equality. These assertions should be made by
+more specific methods, like assertNull, assertNotNull.
+        
+
+*Example:*
+```java
+
+
+public class FooTest extends TestCase {
+    void testCode() {
+        Object a = doSomething();
+        assertTrue(a==null);    // bad usage
+        assertNull(a);          // good usage
+        assertTrue(a != null);  // bad usage
+        assertNotNull(a);       // good usage
+    }
+}
+
+        
+```

pmd-documentation/UseAssertSameInsteadOfAssertTrue.md

@@ -0,0 +1,26 @@
+
+# UseAssertSameInsteadOfAssertTrue
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/bestpractices.xml/UseAssertSameInsteadOfAssertTrue -format <output format>`
+
+*Description:*
+
+This rule detects JUnit assertions in object references equality. These assertions should be made
+by more specific methods, like assertSame, assertNotSame.
+        
+
+*Example:*
+```java
+
+
+public class FooTest extends TestCase {
+    void testCode() {
+        Object a, b;
+        assertTrue(a == b); // bad usage
+        assertSame(a, b);   // good usage
+    }
+}
+
+        
+```

pmd-documentation/UseAssertTrueInsteadOfAssertEquals.md

@@ -0,0 +1,33 @@
+
+# UseAssertTrueInsteadOfAssertEquals
+
+*Usage:* 
+`pmd check -d <source code folder> -R category/java/bestpractices.xml/UseAssertTrueInsteadOfAssertEquals -format <output format>`
+
+*Description:*
+
+When asserting a value is the same as a literal or Boxed boolean, use assertTrue/assertFalse, instead of assertEquals.
+        
+
+*Example:*
+```java
+
+
+public class MyTestCase extends TestCase {
+    public void testMyCase() {
+        boolean myVar = true;
+        // Ok
+        assertTrue("myVar is true", myVar);
+        // Bad
+        assertEquals("myVar is true", true, myVar);
+        // Bad
+        assertEquals("myVar is false", false, myVar);
+        // Bad
+        assertEquals("myVar is true", Boolean.TRUE, myVar);
+        // Bad
+        assertEquals("myVar is false", Boolean.FALSE, myVar);
+    }
+}
+
+        
+```