db: named parameter shortcut in case of single unique placeholder (#799)

Author: MykolaGolubyev

webtau-db/src/main/java/org/testingisdocumenting/webtau/db/Database.java

@@ -46,6 +46,10 @@ public DbQuery createQuery(String query, Map<String, Object> params) {
         return QueryRunnerUtils.createQuery(dataSource, query, params);
     }
 
+    public <E> DbQuery createQuery(String query, E singleParam) {
+        return QueryRunnerUtils.createQuery(dataSource, query, DbNamedParamsQuery.singleNoNameParam(singleParam));
+    }
+
     public TableData queryTableData(String query) {
         return queryTableData(query, Collections.emptyMap());
     }

webtau-db/src/main/java/org/testingisdocumenting/webtau/db/DatabaseFacade.java

@@ -48,6 +48,10 @@ public DbQuery createQuery(String query, Map<String, Object> params) {
         return from(getPrimaryDataSource()).createQuery(query, params);
     }
 
+    public <E> DbQuery createQuery(String query, E singleParam) {
+        return from(getPrimaryDataSource()).createQuery(query, singleParam);
+    }
+
     public TableData queryTableData(String query) {
         return from(getPrimaryDataSource()).queryTableData(query);
     }

webtau-db/src/main/java/org/testingisdocumenting/webtau/db/DbNamedParamsQuery.java

@@ -23,22 +23,31 @@ class DbNamedParamsQuery {
     private final Object[] valuesArray;
     private final String namedParamsQuery;
     private final Map<String, Object> params;
+    private final Set<String> uniqueParamNames;
 
     private final StringBuilder currentNamedParam;
     private final StringBuilder questionMarksQuery;
 
+    private final boolean hasSingleNoNameParameter;
+
     private boolean insideParamName;
     private boolean insideSingleQuote;
     private boolean insideDoubleQuote;
 
+    public DbNamedParamsQuery(String namedParamsQuery, Object singleParam) {
+        this(namedParamsQuery, singleNoNameParam(singleParam));
+    }
+
     public DbNamedParamsQuery(String namedParamsQuery, Map<String, Object> params) {
         this.namedParamsQuery = namedParamsQuery;
+        this.uniqueParamNames = new TreeSet<>();
         this.values = new ArrayList<>();
         this.currentNamedParam = new StringBuilder();
         this.questionMarksQuery = new StringBuilder();
         this.insideParamName = false;
         this.insideSingleQuote = false;
         this.insideDoubleQuote = false;
+        this.hasSingleNoNameParameter = params.size() == 1 && params.keySet().iterator().next().equals("");
         this.params = params;
 
         convertToQuestionMarks();
@@ -58,6 +67,22 @@ public Object[] getQuestionMarksValues() {
         return valuesArray;
     }
 
+    public Map<String, Object> effectiveParams() {
+        if (hasSingleNoNameParameter) {
+            return Collections.singletonMap(uniqueParamNames.iterator().next(), params.values().iterator().next());
+        }
+
+        return params;
+    }
+
+    public boolean isEmpty() {
+        return params.isEmpty();
+    }
+
+    static Map<String, Object> singleNoNameParam(Object singleParam) {
+        return Collections.singletonMap("", singleParam);
+    }
+
     private void convertToQuestionMarks() {
         char c;
 
@@ -77,7 +102,8 @@ private void convertToQuestionMarks() {
                 continue;
             }
 
-            if (insideParamName && Character.isAlphabetic(c)) {
+            if (insideParamName &&
+                    (Character.isAlphabetic(c) || (Character.isDigit(c) && currentNamedParam.length() > 0))) {
                 currentNamedParam.append(c);
             } else if (insideParamName) {
                 handleCurrentParamName();
@@ -93,7 +119,10 @@ private void convertToQuestionMarks() {
     }
 
     private void handleCurrentParamName() {
-        Object valueToAppend = valueByName(currentNamedParam.toString());
+        String paramName = currentNamedParam.toString();
+        uniqueParamNames.add(paramName);
+
+        Object valueToAppend = valueByName(paramName);
         if (valueToAppend instanceof Iterable) {
             handleIterableParam((Iterable<?>) valueToAppend);
         } else {
@@ -123,6 +152,15 @@ private void handleSingleParam(Object valueToAppend) {
     }
 
     private Object valueByName(String name) {
+        if (hasSingleNoNameParameter) {
+            if (uniqueParamNames.size() > 1) {
+                throw new IllegalArgumentException("one no-name parameter value was provided, " +
+                        "but have seen multiple placeholders: " + uniqueParamNames);
+            }
+
+            return params.values().iterator().next();
+        }
+
         Object value = params.get(name);
         if (value == null) {
             throw new IllegalArgumentException("No parameter value found: " + name);

webtau-db/src/main/java/org/testingisdocumenting/webtau/db/QueryRunnerUtils.java

@@ -34,7 +34,11 @@ static DbQuery createQuery(LabeledDataSource dataSource, String query, Map<Strin
         QueryRunner run = new QueryRunner(dataSource.getDataSource());
         MapListHandler handler = new MapListHandler();
 
-        return new DbQuery(dataSource.getLabel(),() -> runQuery(run, handler, query, params), query, params);
+        DbNamedParamsQuery namedParamsQuery = new DbNamedParamsQuery(query, params);
+
+        return new DbQuery(dataSource.getLabel(),
+                () -> runQuery(run, handler, namedParamsQuery),
+                query, namedParamsQuery.effectiveParams());
     }
 
     static int runUpdate(DataSource dataSource, String query) {
@@ -58,14 +62,12 @@ static int runUpdate(DataSource dataSource, String query, Map<String, Object> pa
 
     private static List<Map<String, Object>> runQuery(QueryRunner runner,
                                                       MapListHandler handler,
-                                                      String query,
-                                                      Map<String, Object> params) {
+                                                      DbNamedParamsQuery namedParamsQuery) {
         try {
-            if (params.isEmpty()) {
-                return runner.query(query, handler);
+            if (namedParamsQuery.isEmpty()) {
+                return runner.query(namedParamsQuery.getQuestionMarksQuery(), handler);
             }
 
-            DbNamedParamsQuery namedParamsQuery = new DbNamedParamsQuery(query, params);
             return runner.query(namedParamsQuery.getQuestionMarksQuery(),
                     handler,
                     namedParamsQuery.getQuestionMarksValues());

webtau-db/src/test/groovy/org/testingisdocumenting/webtau/db/DatabaseBaseTest.groovy

@@ -72,6 +72,7 @@ class DatabaseBaseTest {
         String definition =
                 """CREATE TABLE PRICES (
     id varchar(255),
+    external_id varchar(255),
     description varchar(255),
     available bool,
     type varchar(255),

webtau-db/src/test/groovy/org/testingisdocumenting/webtau/db/DatabaseFacadeTest.groovy

@@ -144,6 +144,15 @@ class DatabaseFacadeTest extends DatabaseBaseTest {
         // query with where clause end
     }
 
+    @Test
+    void "query table to match one row using single param shortcut and assert against map"() {
+        setupPrices()
+        // query with where clause start
+        def prices = db.createQuery("select * from PRICES where id=:id or external_id=:id", "id1")
+        prices.should == [ID: "id1", "DESCRIPTION": "nice set", PRICE: 1000]
+        // query with where clause end
+    }
+
     @Test
     void "query table to match multiple row and assert against map"() {
         setupPrices()

webtau-db/src/test/groovy/org/testingisdocumenting/webtau/db/DatabaseStepReporterTest.groovy

@@ -53,6 +53,17 @@ class DatabaseStepReporterTest extends DatabaseBaseTest implements StepReporter
         fullMessage.should contain("select price from PRICES where id=:id with {id=id1} doesn't equal 2000")
     }
 
+    @Test
+    void "query result comparison step should capture query and params in case of single param"() {
+        setupPrices()
+
+        def price = db.createQuery("select price from PRICES where id=:id", 'id1')
+        price.should == 1000
+
+        def fullMessage = stepMessages.join('\n')
+        fullMessage.should contain("select price from PRICES where id=:id with {id=id1} equals 1000")
+    }
+
     @Test
     void "query result comparison step should not capture params when no params ara passed"() {
         setupPrices()

webtau-db/src/test/groovy/org/testingisdocumenting/webtau/db/DbNamedParamsQueryTest.groovy

@@ -18,6 +18,9 @@ package org.testingisdocumenting.webtau.db
 
 import org.junit.Test
 
+import static org.testingisdocumenting.webtau.Matchers.code
+import static org.testingisdocumenting.webtau.Matchers.throwException
+
 class DbNamedParamsQueryTest {
     @Test
     void "convert named params to question marks outside quotes"() {
@@ -40,12 +43,37 @@ class DbNamedParamsQueryTest {
     }
 
     @Test
-    void "convert placeholder into multiple question marks in case of array"() {
+    void "handles parameter names with numeric prefix"() {
+        def query = new DbNamedParamsQuery(
+                "select * from table where id=:id1 or id=:id2", [id1: 1, id2: 2])
+
+        query.questionMarksQuery.should == "select * from table where id=? or id=?"
+        query.questionMarksValues.should == [1, 2]
+    }
+
+    @Test
+    void "validates missing params"() {
+        code {
+            new DbNamedParamsQuery(
+                    "select * from table where count>:count and date<:date and last_count<:count",
+                    [count: 10])
+        } should throwException("No parameter value found: date")
+    }
+
+    @Test
+    void "understands single parameter value when there is only one unique placeholder"() {
         def query = new DbNamedParamsQuery(
-                "select * from table where id in (:ids)",
-                [ids: [1, 2, 3, 10]])
+                "select * from table where id=:id or another_id=:id", 25)
 
-        query.questionMarksQuery.should == "select * from table where id in (?, ?, ?, ?)"
-        query.questionMarksValues.should == [1, 2, 3, 10]
+        query.questionMarksQuery.should == "select * from table where id=? or another_id=?"
+        query.questionMarksValues.should == [25, 25]
+    }
+
+    @Test
+    void "validates mismatch between single parameter and named placeholders"() {
+        code {
+            new DbNamedParamsQuery(
+                    "select * from table where id=:id1 or another_id=:id2", 25)
+        } should throwException("one no-name parameter value was provided, but have seen multiple placeholders: [id1, id2]")
     }
 }

webtau-docs/znai/database/data-query.md

@@ -40,6 +40,19 @@ To query all data from a table use:
     excludeStartEnd: true
 }
 
+# Named Parameter Shortcut
+
+If your query uses a single unique placeholder name, you can pass a regular value instead of a `java.util.Map`
+
+:include-groovy: org/testingisdocumenting/webtau/db/DatabaseFacadeTest.groovy {
+    entry: "query table to match one row using single param shortcut and assert against map",
+    title: "use regular value in case of one unique placeholder name",
+    bodyOnly: true,
+    startLine: "query with where clause start",
+    endLine: "query with where clause end",
+    excludeStartEnd: true
+}
+
 # Lazy Declaration
 
 `createQuery` doesn't query database at the call time. It defines a query to be used later.