Expand documentation and tests for coverage filters.

README.md

@@ -198,8 +198,27 @@ described in [Coverage](https://www.utplsql.org/utPLSQL/latest/userguide/coverag
 | `includeObjectExpr` | Regular expression for the names of objects to include                               |
 | `excludeObjectExpr` | Regular expression for the names of objects to exclude                               |
 
-The regular expression filters need a utPLSQL version that supports them. See
-[Coverage reporting options](https://www.utplsql.org/utPLSQL/latest/userguide/coverage.html#coverage-reporting-options).
+The plugin passes these values unchanged to utPLSQL, which defines their exact semantics. See
+[Filtering objects in coverage reports](https://www.utplsql.org/utPLSQL/latest/userguide/coverage.html#filtering-objects-in-coverage-reports)
+in the utPLSQL documentation. The points that matter most in practice:
+
+* The `*Expr` parameters are regular expressions, matched case-insensitively. They are matched against the schema
+  name (`*SchemaExpr`) or the object name **without** the schema (`*ObjectExpr`). Use `^` and `$` to anchor them,
+  otherwise any partial match counts (`APP` also matches `MY_APP_TEST`).
+* If `includeSchemaExpr` or `includeObjectExpr` is set, utPLSQL ignores `includeObject`. All exclude parameters are
+  always applied and can be combined.
+* utPLSQL ignores all include/exclude filters when file mappings are in use, that is when the plugin finds files for
+  `sources` (explicitly configured, or in the default `src/main/plsql` directory). See
+  [Mapping project files to database objects](#mapping-project-files-to-database-objects). Use the filters when
+  your project does not provide source files to map.
+* Blank values are ignored.
+
+Example: report coverage of all packages in the `APP` schema except those ending in `_TMP`:
+
+```xml
+<includeSchemaExpr>^APP$</includeSchemaExpr>
+<excludeObjectExpr>_TMP$</excludeObjectExpr>
+```
 
 ### Mapping project files to database objects
 
@@ -466,7 +485,10 @@ The plugin's integration tests double as examples, in
 | `--ora-stuck-timeout`              | `oraStuckTimeout`                                        |
 | `-include`                         | `includeObject`                                          |
 | `-exclude`                         | `excludeObject`                                          |
-| not available                      | `includeSchemaExpr`, `excludeSchemaExpr`, `includeObjectExpr`, `excludeObjectExpr` |
+| `-include-schema-expr`             | `includeSchemaExpr`                                      |
+| `-exclude-schema-expr`             | `excludeSchemaExpr`                                      |
+| `-include-object-expr`             | `includeObjectExpr`                                      |
+| `-exclude-object-expr`             | `excludeObjectExpr`                                      |
 | not available                      | `skipUtplsqlTests`                                       |
 | `--coverage-schemes`               | not available                                            |
 | `-t`, `--timeout`                  | not available                                            |

src/test/java/org/utplsql/maven/plugin/UtPlsqlMojoIT.java

@@ -98,6 +98,20 @@
         assertThatReportsAreGeneratedAsExpected(result, "sonar-test-report.xml", "coverage-sonar-report.xml");
     }
 
+    @MavenTest
+    void include_schema_expr(MavenExecutionResult result) {
+        assertThat(result).isSuccessful();
+
+        assertThatReportsAreGeneratedAsExpected(result, "sonar-test-report.xml", "coverage-sonar-report.xml");
+    }
+
+    @MavenTest
+    void exclude_schema_expr(MavenExecutionResult result) {
+        assertThat(result).isSuccessful();
+
+        assertThatReportsAreGeneratedAsExpected(result, "sonar-test-report.xml", "coverage-sonar-report.xml");
+    }
+
     @MavenTest
     @SystemProperty(value = "skipTests", content = "true")
     void skip_tests(MavenExecutionResult result) {

src/test/resources-its/org/utplsql/maven/plugin/UtPlsqlMojoIT/exclude_schema_expr/expected-output/utplsql/coverage-sonar-report.xml

@@ -0,0 +1,2 @@
+<coverage version="1">
+</coverage>

src/test/resources-its/org/utplsql/maven/plugin/UtPlsqlMojoIT/exclude_schema_expr/expected-output/utplsql/sonar-test-report.xml

@@ -0,0 +1,11 @@
+<testExecutions version="1">
+<file path="plsql.examples.test_pkg_test_me">
+<testCase name="test_fc_input_1" duration="1" ></testCase>
+<testCase name="test_fc_input_0" duration="1" ></testCase>
+<testCase name="test_fc_input_null" duration="1" ></testCase>
+<testCase name="test_pr_test_me_null" duration="1" ></testCase>
+<testCase name="test_pr_test_me_not_null" duration="1" ></testCase>
+<testCase name="test_pr_test_me_exists" duration="1" ></testCase>
+<testCase name="test_pr_test_me_cursor" duration="1" ></testCase>
+</file>
+</testExecutions>

src/test/resources-its/org/utplsql/maven/plugin/UtPlsqlMojoIT/exclude_schema_expr/pom.xml

@@ -0,0 +1,52 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>org.utplsql</groupId>
+    <artifactId>owner-param</artifactId>
+    <version>1.0.0</version>
+    <packaging>pom</packaging>
+
+    <properties>
+        <dbUrl>jdbc:oracle:thin:@//localhost:1521/FREEPDB1</dbUrl>
+        <dbUser>UT3</dbUser>
+        <dbPass>ut3</dbPass>
+    </properties>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.utplsql</groupId>
+                <artifactId>utplsql-maven-plugin</artifactId>
+                <version>@project.version@</version>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>test</goal>
+                        </goals>
+                        <configuration>
+                            <ignoreFailure>false</ignoreFailure>
+                            <paths>
+                                <path>TESTS_OWNER</path>
+                            </paths>
+                            <reporters>
+                                <reporter>
+                                    <name>UT_COVERAGE_SONAR_REPORTER</name>
+                                    <fileOutput>utplsql/coverage-sonar-report.xml</fileOutput>
+                                    <consoleOutput>true</consoleOutput>
+                                </reporter>
+                                <reporter>
+                                    <name>UT_SONAR_TEST_REPORTER</name>
+                                    <fileOutput>utplsql/sonar-test-report.xml</fileOutput>
+                                    <consoleOutput>true</consoleOutput>
+                                </reporter>
+                            </reporters>
+                            <excludeSchemaExpr>^app$</excludeSchemaExpr>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

src/test/resources-its/org/utplsql/maven/plugin/UtPlsqlMojoIT/include_schema_expr/expected-output/utplsql/coverage-sonar-report.xml

@@ -0,0 +1 @@
+<coverage version="1"><file path="package body app.pkg_test_me"><lineToCover lineNumber="1" covered="false"/><lineToCover lineNumber="2" covered="false"/><lineToCover lineNumber="3" covered="false"/><lineToCover lineNumber="4" covered="false"/><lineToCover lineNumber="5" covered="false"/><lineToCover lineNumber="6" covered="false"/><lineToCover lineNumber="7" covered="false"/><lineToCover lineNumber="8" covered="false"/><lineToCover lineNumber="9" covered="false"/><lineToCover lineNumber="10" covered="false"/><lineToCover lineNumber="11" covered="false"/><lineToCover lineNumber="12" covered="false"/><lineToCover lineNumber="13" covered="false"/><lineToCover lineNumber="14" covered="false"/><lineToCover lineNumber="15" covered="false"/><lineToCover lineNumber="16" covered="false"/><lineToCover lineNumber="17" covered="false"/><lineToCover lineNumber="18" covered="false"/><lineToCover lineNumber="19" covered="false"/><lineToCover lineNumber="20" covered="false"/><lineToCover lineNumber="21" covered="false"/><lineToCover lineNumber="22" covered="false"/><lineToCover lineNumber="23" covered="false"/><lineToCover lineNumber="24" covered="false"/><lineToCover lineNumber="25" covered="false"/><lineToCover lineNumber="26" covered="false"/></file></coverage>

src/test/resources-its/org/utplsql/maven/plugin/UtPlsqlMojoIT/include_schema_expr/expected-output/utplsql/sonar-test-report.xml

@@ -0,0 +1,11 @@
+<testExecutions version="1">
+<file path="plsql.examples.test_pkg_test_me">
+<testCase name="test_fc_input_1" duration="1" ></testCase>
+<testCase name="test_fc_input_0" duration="1" ></testCase>
+<testCase name="test_fc_input_null" duration="1" ></testCase>
+<testCase name="test_pr_test_me_null" duration="1" ></testCase>
+<testCase name="test_pr_test_me_not_null" duration="1" ></testCase>
+<testCase name="test_pr_test_me_exists" duration="1" ></testCase>
+<testCase name="test_pr_test_me_cursor" duration="1" ></testCase>
+</file>
+</testExecutions>

src/test/resources-its/org/utplsql/maven/plugin/UtPlsqlMojoIT/include_schema_expr/pom.xml

@@ -0,0 +1,52 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>org.utplsql</groupId>
+    <artifactId>owner-param</artifactId>
+    <version>1.0.0</version>
+    <packaging>pom</packaging>
+
+    <properties>
+        <dbUrl>jdbc:oracle:thin:@//localhost:1521/FREEPDB1</dbUrl>
+        <dbUser>UT3</dbUser>
+        <dbPass>ut3</dbPass>
+    </properties>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.utplsql</groupId>
+                <artifactId>utplsql-maven-plugin</artifactId>
+                <version>@project.version@</version>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>test</goal>
+                        </goals>
+                        <configuration>
+                            <ignoreFailure>false</ignoreFailure>
+                            <paths>
+                                <path>TESTS_OWNER</path>
+                            </paths>
+                            <reporters>
+                                <reporter>
+                                    <name>UT_COVERAGE_SONAR_REPORTER</name>
+                                    <fileOutput>utplsql/coverage-sonar-report.xml</fileOutput>
+                                    <consoleOutput>true</consoleOutput>
+                                </reporter>
+                                <reporter>
+                                    <name>UT_SONAR_TEST_REPORTER</name>
+                                    <fileOutput>utplsql/sonar-test-report.xml</fileOutput>
+                                    <consoleOutput>true</consoleOutput>
+                                </reporter>
+                            </reporters>
+                            <includeSchemaExpr>^app$</includeSchemaExpr>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>