Update documentation

https://github.com/pmd/pmd/actions/runs/2714446850 029b4b2053...6d8c811403
2022-07-21 20:38:39 +00:00
parent 000cf5fcd7
commit 89f9a6676c
3 changed files with 46 additions and 18 deletions
--- a/feed.xml
+++ b/feed.xml
@@ -5,8 +5,8 @@
        <description>Intended as a documentation theme based on Jekyll for technical writers documenting software and other technical products, this theme has all the elements you would need to handle multiple products with both multi-level sidebar navigation, tags, and other documentation features.</description>
        <link>https://pmd.github.io/pmd/</link>
        <atom:link href="https://pmd.github.io/pmd/feed.xml" rel="self" type="application/rss+xml"/>
-        <pubDate>Thu, 21 Jul 2022 15:51:53 +0000</pubDate>
-        <lastBuildDate>Thu, 21 Jul 2022 15:51:53 +0000</lastBuildDate>
+        <pubDate>Thu, 21 Jul 2022 20:36:19 +0000</pubDate>
+        <lastBuildDate>Thu, 21 Jul 2022 20:36:19 +0000</lastBuildDate>
        <generator>Jekyll v3.9.2</generator>
        
    </channel>
--- a/pmd_release_notes.html
+++ b/pmd_release_notes.html
@@ -1590,10 +1590,29 @@ for the <a href="https://cucumber.io/docs/gherkin/">Gherkin</a> language. It is
      <li><a href="https://github.com/pmd/pmd/issues/3625">#3625</a>: [java] AddEmptyString - false negative with empty var</li>
    </ul>
  </li>
+  <li>test
+    <ul>
+      <li><a href="https://github.com/pmd/pmd/issues/3758">#3758</a>: [test] Move pmd-test to java 8</li>
+      <li><a href="https://github.com/pmd/pmd/pull/3976">#3976</a>: [test] Extract xml schema module</li>
+    </ul>
+  </li>
 </ul>

 <h3 id="api-changes">API Changes</h3>

+<h4 id="rule-test-framework">Rule Test Framework</h4>
+
+<ul>
+  <li>The module “pmd-test”, which contains support classes to write rule tests, now <strong>requires Java 8</strong>. If you depend on
+this module for testing your own custom rules, you’ll need to make sure to use at least Java 8.</li>
+  <li>The new module “pmd-test-schema” contains now the XSD schema and the code to parse the rule test XML files. The
+schema has been extracted in order to easily share it with other tools like the Rule Designer or IDE plugins.</li>
+  <li>The attribute <code class="language-plaintext highlighter-rouge">isRegressionTest</code> is deprecated and the new attribute <code class="language-plaintext highlighter-rouge">disabled</code> should be used instead for
+defining whether a rule test should be skipped or not.</li>
+  <li>More information about the rule test framework can be found in the documentation:
+<a href="pmd_userdocs_extending_testing.html">Testing your rules</a></li>
+</ul>
+
 <h4 id="deprecated-api">Deprecated API</h4>

 <ul>
--- a/pmd_userdocs_extending_testing.html
+++ b/pmd_userdocs_extending_testing.html
@@ -1585,7 +1585,8 @@ src/test/resources/net/sourceforge/pmd/lang/&lt;Language Terse Name&gt;/rule/&lt

 <div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip:</b> This convention allows you to quickly find the test cases for a given rule:
 Just search in the project for a file <code class="language-plaintext highlighter-rouge">&lt;RuleName&gt;.xml</code>. Search for a class <code class="language-plaintext highlighter-rouge">&lt;Rule Name&gt;Test</code> to find the
-unit test class for the given rule.</div>
+unit test class for the given rule. And if the rule is a Java-based rule, the search for <code class="language-plaintext highlighter-rouge">&lt;Rule Name&gt;Rule</code>
+finds the rule implementation class.</div>

 <div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> If you want to use the test framework with a different package structure,
 see <a href="#using-the-test-framework-externally">Using the test framework externally</a>.</div>
@@ -1652,19 +1653,23 @@ between different test cases.</p>

 <h3 id="test-code-attributes"><code class="language-plaintext highlighter-rouge">&lt;test-code&gt;</code> attributes</h3>

-<p>The <code class="language-plaintext highlighter-rouge">&lt;test-code&gt;</code> elements understands three optional attributes:</p>
+<p>The <code class="language-plaintext highlighter-rouge">&lt;test-code&gt;</code> elements understands the following optional attributes:</p>

 <ul>
  <li>
    <p><strong>reinitializeRule</strong>: By default, it’s <code class="language-plaintext highlighter-rouge">true</code>, so each test case starts with a fresh instantiated rule. Set it
-to <code class="language-plaintext highlighter-rouge">false</code> to reproduce cases, where the previous run has influences.</p>
+  to <code class="language-plaintext highlighter-rouge">false</code> to reproduce cases, where the previous run has influences.</p>
  </li>
  <li>
-    <p><strong>regressionTest</strong>: By default, it’s <code class="language-plaintext highlighter-rouge">true</code>. Set it to <code class="language-plaintext highlighter-rouge">false</code>, to ignore and skip a test case.</p>
+    <p><strong>disabled</strong>: By default, it’s <code class="language-plaintext highlighter-rouge">false</code>. Set ti to <code class="language-plaintext highlighter-rouge">true</code>, to ignore and skip a test case.</p>
  </li>
  <li>
    <p><strong>useAuxClasspath</strong>: By default, it’s <code class="language-plaintext highlighter-rouge">true</code>. Set it to <code class="language-plaintext highlighter-rouge">false</code> to reproduce issues which only
-appear without type resolution.</p>
+  appear without type resolution.</p>
+  </li>
+  <li>
+    <p><strong>regressionTest</strong>: <em>deprecated since PMD 6.48.0: Use <code class="language-plaintext highlighter-rouge">disabled</code> instead. Note: It has the opposite boolean
+semantic.</em> By default, it’s <code class="language-plaintext highlighter-rouge">true</code>. Set it to <code class="language-plaintext highlighter-rouge">false</code>, to ignore and skip a test case.</p>
  </li>
 </ul>

@@ -1724,7 +1729,7 @@ in a “CDATA” section, so that no further XML escapes (entity references such
    <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span>
    <span class="na">xsi:schemaLocation=</span><span class="s">"http://pmd.sourceforge.net/rule-tests https://pmd.sourceforge.io/rule-tests_1_0_0.xsd"</span><span class="nt">&gt;</span>

-    <span class="nt">&lt;test-code</span> <span class="na">reinitializeRule=</span><span class="s">"true"</span> <span class="na">regressionTest=</span><span class="s">"true"</span> <span class="na">useAuxClasspath=</span><span class="s">"true"</span><span class="nt">&gt;</span>
+    <span class="nt">&lt;test-code</span> <span class="na">reinitializeRule=</span><span class="s">"true"</span> <span class="na">disabled=</span><span class="s">"false"</span> <span class="na">useAuxClasspath=</span><span class="s">"true"</span><span class="nt">&gt;</span>
        <span class="nt">&lt;description&gt;</span>Just a description, will be used as the test name for JUnit in the reports<span class="nt">&lt;/description&gt;</span>
        <span class="nt">&lt;rule-property</span> <span class="na">name=</span><span class="s">"somePropName"</span><span class="nt">&gt;</span>propValue<span class="nt">&lt;/rule-property&gt;</span>    <span class="c">&lt;!-- optional --&gt;</span>
        <span class="nt">&lt;expected-problems&gt;</span>2<span class="nt">&lt;/expected-problems&gt;</span>
@@ -1807,25 +1812,29 @@ the path “com/example/pmd/ruleset.xml”.</p>
 <ul>
  <li>
    <p><code class="language-plaintext highlighter-rouge">PmdRuleTst</code>: This is the base class for tests in PMD’s code base. It is a subclass of <code class="language-plaintext highlighter-rouge">RuleTst</code> and just
-contains the logic to determine the test resources based on the test class name.</p>
+  contains the logic to determine the test resources based on the test class name.</p>
  </li>
  <li>
    <p><code class="language-plaintext highlighter-rouge">SimpleAggregatorTst</code>: This is a more generic base class for the test classes and defines
-the custom JUnit test runner. It doesn’t register any test cases on its own.
-It itself is a subclass of <code class="language-plaintext highlighter-rouge">RuleTst</code>.</p>
+  the custom JUnit test runner. It doesn’t register any test cases on its own.
+  It itself is a subclass of <code class="language-plaintext highlighter-rouge">RuleTst</code>.</p>
  </li>
  <li>
-    <p><code class="language-plaintext highlighter-rouge">RuleTst</code>: contains the logic to parse the XML files and provide a list of <code class="language-plaintext highlighter-rouge">TestDescriptor</code>s. Each test descriptor
-describes a single test case. It also contains the logic to execute such a test descriptor and assert the results.</p>
+    <p>The maven module “pmd-test-schema” contains the logic to parse the XML files and provide a <code class="language-plaintext highlighter-rouge">RuleTestCollection</code>. This
+in turn contains a list of <code class="language-plaintext highlighter-rouge">RuleTestDescriptor</code>s. Each rule test descriptor describes a single test case.</p>
+  </li>
+  <li>
+    <p><code class="language-plaintext highlighter-rouge">RuleTst</code>: uses the <code class="language-plaintext highlighter-rouge">TestSchemaParser</code> from module “pmd-test-schema” to parse the test cases, executes each
+rule test descriptor and asserts the results.</p>
  </li>
  <li>
    <p><code class="language-plaintext highlighter-rouge">PMDTestRunner</code>: A custom JUnit test runner, that combines two separate test runners: The custom <code class="language-plaintext highlighter-rouge">RuleTestRunner</code>
-and the standard <code class="language-plaintext highlighter-rouge">JUnit4</code> test runner. This combination allows you to add additional standard unit test methods
-annotated with <code class="language-plaintext highlighter-rouge">@Test</code> to your test class.</p>
+  and the standard <code class="language-plaintext highlighter-rouge">JUnit4</code> test runner. This combination allows you to add additional standard unit test methods
+  annotated with <code class="language-plaintext highlighter-rouge">@Test</code> to your test class.</p>

    <p><em>Note:</em> Since the test class is executed through two test runners, it is actually instantiated twice. Be aware
-of this, if you do any initialization in the constructor. Also, the static hooks <code class="language-plaintext highlighter-rouge">@BeforeClass</code> and <code class="language-plaintext highlighter-rouge">@AfterClass</code>
-will be executed twice.</p>
+  of this, if you do any initialization in the constructor. Also, the static hooks <code class="language-plaintext highlighter-rouge">@BeforeClass</code> and <code class="language-plaintext highlighter-rouge">@AfterClass</code>
+  will be executed twice.</p>
  </li>
  <li>
    <p><code class="language-plaintext highlighter-rouge">RuleTestRunner</code>: This test runner executes the test descriptors with the help of <code class="language-plaintext highlighter-rouge">RuleTst</code>.</p>
@@ -1875,7 +1884,7 @@ will be executed twice.</p>
            &copy;2022 PMD Open Source Project. All rights
            reserved. <br />
            <span>Page last updated:</span>
-            November 2018<br /> Site last generated: Jul 21, 2022 <br />
+            July 2022<br /> Site last generated: Jul 21, 2022 <br />
            <p>
                <img src="images/pmd-logo-small.png" alt="Company
                logo"/>