[drill] branch master updated: [MINOR UPDATE]: /docs update for DRILL-8117 (#2763)

[dz...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

dzamo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/drill.git


The following commit(s) were added to refs/heads/master by this push:
     new d8eee4fd98 [MINOR UPDATE]: /docs update for DRILL-8117 (#2763)
d8eee4fd98 is described below

commit d8eee4fd984087ca1919413da446fd6e2d3a027c
Author: kingswanwho <ch...@gmail.com>
AuthorDate: Wed Feb 22 19:35:10 2023 +0800

    [MINOR UPDATE]: /docs update for DRILL-8117 (#2763)
---
 docs/dev/ClusterFixture.md | 48 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 46 insertions(+), 2 deletions(-)

diff --git a/docs/dev/ClusterFixture.md b/docs/dev/ClusterFixture.md
index da006502f7..7a47c20901 100644
--- a/docs/dev/ClusterFixture.md
+++ b/docs/dev/ClusterFixture.md
@@ -1,6 +1,6 @@
 # ClusterFixture
 
-Drill provides two ways to test. The original tests are based on the `BaseTestQuery` are are (or will be) described elsewhere. Limitations of this class prompted creation of a new framework, which this page describes.
+Drill provides two ways to test. The original tests are based on the `BaseTestQuery` are (or will be) described elsewhere. Limitations of this class prompted creation of a new framework, which this page describes.
 
 * A single base class `BaseTestQuery` holds a large amount of functionality, making it hard to create specialized test classes. One either starts with `BaseTestQuery`, or must replicate that functionality. Since one often has to create specialized setups, this was a bit of a limitation.
 * `BaseTestQuery` is very handy in that it starts an embedded Drillbit. But, it does so using a fixed set of boot options. To change the boot options as needed for some tests, one has to allow the initial Drillbit to start, then shut it down, create the new config, and restart. This is tedious when using tests for debugging.
@@ -125,6 +125,27 @@ In some cases, you may want to change an option in a test. Rather than writing o
 
 Again, you can pass a Java value which the test code will convert to a string, then will build the `ALTER SESSION` command.
 
+# Try-with-resource Style of Creating Single-use Client Fixtures.
+
+A benefit of the Cluster Fixture framework is the ability to define specific configs for specific clusterFixtures and clientFixtures as needed flexibly.
+
+In some cases, a clusterFixture has been initialized and we need to create several different config clients for different test cases.
+
+Using Java's try-with-resources syntax to create a single-use clientFixture is a convenient way to ensure that the clientFixture will automatically be closed once we've finished with it.
+
+```
+  @Test
+  public void testDirectImpersonation_HasUserReadPermissions() throws Exception {
+    // Table lineitem is owned by "user0_1:group0_1" with permissions 750. Try to read the table as "user0_1". We
+    // shouldn't expect any errors.
+    try (ClientFixture client = cluster.client(org1Users[0], "")) {
+      client.run("SELECT * FROM %s.lineitem ORDER BY l_orderkey LIMIT 1", getWSSchema(org1Users[0]));
+    }
+  }
+```
+
+* Use cluster.client() to create a new clientFixture with specific userName and password.
+
 # The Mock Data Source
 
 The test framework provides a [mock data source](The Mock Record Reader) that is sometimes handy, especially when you need to generate a large amount of data for, say, testing a sort or aggregation. The test framework automatically defines the required storage plugin:
@@ -156,6 +177,29 @@ It is often very handy, during development, to accumulate a collection of test f
 * The (local) file system location
 * The default format
 
+# Exception Matcher
+
+The `QueryBuilder` provides a clean and concise way to handle UserException matching which includes error type matching and error message pattern matching:
+
+```
+    @Test
+    public void unsupportedLiteralValidation() throws Exception {
+      String query = "ALTER session SET `%s` = %s";
+
+      client.queryBuilder()
+        .sql(query, ENABLE_VERBOSE_ERRORS_KEY, "DATE '1995-01-01'")
+        .userExceptionMatcher()
+        .expectedType(ErrorType.VALIDATION)
+        .include("Drill doesn't support assigning literals of type")
+        .match();
+    }
+```
+* Use `.userExceptionMatcher` to call UserExceptionMatcher
+* Use `.expectedType` to define expected Error type
+* Use `.include` to define an expected error message regex pattern
+* Use `.exclude` to define an unexpected error message regex pattern
+
+
 # Additional Query Tools
 
 As shown above, the query build provides a number of tools.
@@ -244,4 +288,4 @@ But, there are times when you may have specialized needs. The test framework has
 * Gather the query profile, parse it, and print a summary. (Very useful when optimizing code.)
 * Return results as a `RowSet` that allows programmatic inspection of values, in-process validation of results, and so on.
 
-If you find you have a special need, poke around the test framework code to see if the feature is already available. If not, feel free to add the feature and post a pull request.
\ No newline at end of file
+If you find you have a special need, poke around the test framework code to see if the feature is already available. If not, feel free to add the feature and post a pull request.