Deprecate milliseconds contracts for timers to keep API consistency with durations

Also fix documentation grammar

Author: rabelenda-abstracta

README.md

@@ -5,11 +5,11 @@ actionText: User Guide →
 actionLink: /guide/
 features:
 - title: 💙 Git, IDE & Programmers Friendly
-  details: Simple way of defining performance tests which takes advantage of IDEs autocompletion and inline documentation.
+  details: Simple way of defining performance tests that takes advantage of IDEs autocompletion and inline documentation.
 - title: 💪 JMeter ecosystem & community
-  details: Use the most popular performance tool and take advantage of wide support of protocols and tools.
+  details: Use the most popular performance tool and take advantage of the wide support of protocols and tools.
 - title: 😎 Built-in features & extensibility
-  details: Built-in additional features which ease usage (like <a href="guide/#dsl-code-generation-from-jmx-file">jmx2dsl</a>)  and CI/CD pipelines integration. 
+  details: Built-in additional features which ease usage (like <a href="guide/#dsl-code-generation-from-jmx-file">jmx2dsl</a>)  and CI/CD pipelines integration.
 ---
 
 ## Example

docs/guide/README.md

@@ -7,13 +7,15 @@ sidebar: auto
 
 There are many tools to script performance/load tests, being [JMeter](http://jmeter.apache.org/) and [Gatling](https://gatling.io/) the most popular ones.
 
+Here we explore some alternatives, their pros & cons, and the main motivations behind the development of jmeter-java-dsl.
+
 ## Alternatives analysis
 
 ### JMeter
 
 JMeter is great for people with no programming knowledge since it provides a graphical interface to create test plans and run them. Additionally, it is the most popular tool (with a lot of supporting tools built on it) and has a big amount of supported protocols and plugins making it very versatile.
 
-But, JMeter has some downsides as well: sometimes might be slow to create test plans in JMeter GUI and you can't get the full picture of the test plan unless you dig in every tree node to check its properties. Furthermore, it doesn't provide a simple programmer friendly API (you can check [here](https://www.blazemeter.com/blog/5-ways-launch-jmeter-test-without-using-jmeter-gui/) for an example on how to run JMeter programmatically without jmeter-java-dsl), nor a Git friendly format (too verbose and hard to review). For example, for this test plan:
+But, JMeter has some downsides as well: sometimes it might be slow to create test plans in JMeter GUI and you can't get the full picture of the test plan unless you dig in every tree node to check its properties. Furthermore, it doesn't provide a simple programmer-friendly API (you can check [here](https://www.blazemeter.com/blog/5-ways-launch-jmeter-test-without-using-jmeter-gui/) for an example of how to run JMeter programmatically without jmeter-java-dsl), nor a Git-friendly format (too verbose and hard to review). For example, for this test plan:
 
 ```java
 import static org.assertj.core.api.Assertions.assertThat;
@@ -48,24 +50,24 @@ In JMeter, you would need a JMX file like [this](../../docs/motivation/sample.jm
 
 ### Gatling
 
-Gatling does provide a simple API and a Git friendly format, but requires scala knowledge and environment [[1](#gatling-java)]. Additionally, it doesn't provide as rich environment as JMeter (protocol support, plugins, tools) and requires learning a new framework for testing (if you already use JMeter, which is the most popular tool).
+Gatling does provide a simple API and Git-friendly format but requires scala knowledge and environment [[1](#gatling-java)]. Additionally, it doesn't provide as a rich environment as JMeter (protocol support, plugins, tools) and requires learning a new framework for testing (if you already use JMeter, which is the most popular tool).
 
 ### Taurus
 
-[Taurus](https://gettaurus.org/) is another open-source tool that allows specifying tests in a Git friendly yaml syntax, and provides additional features like pass/fail criteria and easier CI/CD integration. But, this tool requires a python environment, in addition to the java environment. Additionally, there is no built-in GUI or IDE auto-completion support, which makes it harder to discover and learn the actual syntax. Finally, Taurus syntax only supports a subset of the features JMeter provides.
+[Taurus](https://gettaurus.org/) is another open-source tool that allows specifying tests in a Git-friendly yaml syntax, and provides additional features like pass/fail criteria and easier CI/CD integration. But, this tool requires a python environment, in addition to the java environment. Additionally, there is no built-in GUI or IDE auto-completion support, which makes it harder to discover and learn the actual syntax. Finally, Taurus syntax only supports a subset of the features JMeter provides.
 
 ### ruby-dsl
 
-Finally, [ruby-dsl](https://github.com/flood-io/ruby-jmeter) is also an opensource library which allows specifying and run in ruby custom dsl JMeter test plans. This is the most similar tool to jmeter-java-dsl, but it requires ruby (in addition to java environment) with the additional performance impact, does not follow same naming and structure convention as JMeter, and lacks of debugging integration with JMeter execution engine.
+Finally, [ruby-dsl](https://github.com/flood-io/ruby-jmeter) is also an open-source library that allows specifying and running in ruby custom DSL JMeter test plans. This is the most similar tool to jmeter-java-dsl, but it requires ruby (in addition to the java environment) with the additional performance impact, does not follow the same naming and structure convention as JMeter, and lacks debugging integration with JMeter execution engine.
 
 ### jmeter-java-dsl
 
-jmeter-java-dsl tries to get the best of these tools by providing a simple java API with Git friendly format to run JMeter tests, taking advantage of all JMeter benefits and knowledge also providing many of the benefits of Gatling scripting.
-As shown in previous example, it can be easily executed with JUnit, modularized in code and easily integrated in any CI/CD pipeline. Additionally, it makes it easy to debug the execution of test plans with usual IDE debugger tools. Finally, as with most Java libraries, you can use it not only in a Java project, but also in projects of most JVM languages (like kotlin, scala, groovy, etc.).
+jmeter-java-dsl tries to get the best of these tools by providing a simple java API with Git friendly format to run JMeter tests, taking advantage of all JMeter benefits and knowledge and also providing many of the benefits of Gatling scripting.
+As shown in the previous example, it can be easily executed with JUnit, modularized in code, and easily integrated into any CI/CD pipeline. Additionally, it makes it easy to debug the execution of test plans with the usual IDE debugger tools. Finally, as with most Java libraries, you can use it not only in a Java project but also in projects of most JVM languages (like kotlin, scala, groovy, etc.).
 
 ## Comparison Table
 
-Here is a table with summary of main pros and cons of each tool:
+Here is a table with a summary of the main pros and cons of each tool:
 
 | Tool            | Pros                                                                                                                                                                                                                                                                                                                                                                                                                                               | Cons                                                                                                                                                                                                                                    |
 |-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -76,7 +78,7 @@ Here is a table with summary of main pros and cons of each tool:
 | jmeter-java-dsl | 👍 VCS friendly<br/>👍 IDE friendly (auto-complete and debug)<br/>👍 Natural CI/CD integration<br/>👍 Natural code modularization and reuse<br/>👍 Existing JMeter documentation<br/>👍 Easy to add support for JMeter supported protocols and new plugins<br/>👍 Could easily interact with JMX files and take advantage of JMeter ecosystem<br/>👍 All details of simple test plans at a glance<br/>👍 Simple way to do assertions on statistics | 👎 Basic Java knowledge required<br/>👎 Same resources (CPU & RAM) usage as JMeter                                                                                                                                                      |
 
 ::: tip Notes
-1. <a name="gatling-java"></a> One year after jmeter-java-dsl release, on November 2021, Gatling released [3.7 version](https://gatling.io/2021/11/gatling-3-7-java-dsl-kotlin-and-much-more/), including a Java friendly API for existing Gatling Scala API. This greatly simplifies usage for Java users and is a great addition to Gatling. 
+1. <a name="gatling-java"></a> One year after jmeter-java-dsl release, on November 2021, Gatling released [3.7 version](https://gatling.io/2021/11/gatling-3-7-java-dsl-kotlin-and-much-more/), including a Java friendly API for existing Gatling Scala API. This greatly simplifies usage for Java users and is a great addition to Gatling.
 
-   As a side note, take into consideration that underlying code is still Scala and async model based, which makes debugging and understanding it harder for Java developers than JMeter code. Additionally, the model is still tied to `Simulator` classes and maven (gradle or sbt) plugin to be able to run the tests, compared to the simplicity and flexibility of jmeter-java-dsl tests execution.
-:::
+   As a side note, take into consideration that the underlying code is still Scala and async model-based, which makes debugging and understanding it harder for Java developers than JMeter code. Additionally, the model is still tied to `Simulator` classes and maven (gradle or sbt) plugin to be able to run the tests, compared to the simplicity and flexibility of jmeter-java-dsl tests execution.
+:::

docs/index.md

@@ -4,7 +4,6 @@
 import java.sql.Connection;
 import java.sql.Driver;
 import java.time.Duration;
-import java.time.temporal.ChronoUnit;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
@@ -19,7 +18,6 @@
 import us.abstracta.jmeter.javadsl.codegeneration.MethodParam;
 import us.abstracta.jmeter.javadsl.codegeneration.SingleTestElementCallBuilder;
 import us.abstracta.jmeter.javadsl.codegeneration.TestElementParamBuilder;
-import us.abstracta.jmeter.javadsl.codegeneration.params.DurationParam;
 import us.abstracta.jmeter.javadsl.core.configs.BaseConfigElement;
 
 /**
@@ -209,10 +207,8 @@ protected MethodCall buildMethodCall(DataSourceElement testElement, MethodCallCo
           .chain("password", paramBuilder.stringParam("password"))
           .chain("autoCommit", paramBuilder.boolParam("autocommit", true))
           .chain("maxConnections", paramBuilder.intParam("poolMax", 0))
-          .chain("maxConnectionWait", paramBuilder.buildParam("timeout",
-              (expression, defaultValue) -> new DurationParam(expression, defaultValue,
-                  ChronoUnit.MILLIS),
-              DEFAULT_MAX_CONNECTION_WAIT))
+          .chain("maxConnectionWait",
+              paramBuilder.durationParamMillis("timeout", DEFAULT_MAX_CONNECTION_WAIT))
           .chain("transactionIsolation", new TransactionIsolationParam(
               testElement.getPropertyAsString("transactionIsolation")));
     }

docs/motivation/README.md

@@ -1,6 +1,6 @@
 ///usr/bin/env jbang "$0" "$@" ; exit $?
 /*
-These commented lines make the class executable if you have jbang installed by making file
+These commented lines make the class executable if you have jbang installed by making the file
 executable (eg: chmod +x ./PerformanceTest.java) and just executing it with ./PerformanceTest.java
 */
 //DEPS org.assertj:assertj-core:3.23.1
@@ -38,8 +38,8 @@ public void test() throws IOException {
   }
 
   /*
-   This method is only included to make test class self executable. You can remove it when
-   executing tests with maven, gradle or some other tool.
+   This method is only included to make the test class self-executable. You can remove it when
+   executing tests with maven, gradle, or some other tool.
    */
   public static void main(String[] args) {
     SummaryGeneratingListener summaryListener = new SummaryGeneratingListener();

jmeter-java-dsl-jdbc/src/main/java/us/abstracta/jmeter/javadsl/jdbc/DslJdbcConnectionPool.java

@@ -1295,39 +1295,72 @@ public static DslViewResultsTree resultsTreeVisualizer() {
    *
    * @param durationMillis specifies the number of milliseconds for the timer to wait.
    * @return the timer for usage in test plan.
+   * @see #constantTimer(Duration)
    * @since 0.62
+   * @deprecated as of 0.66, use {@link #constantTimer(Duration)}
    */
+  @Deprecated
   public static DslConstantTimer constantTimer(long durationMillis) {
-    return new DslConstantTimer(durationMillis);
+    return constantTimer(Duration.ofMillis(durationMillis));
+  }
+
+  /**
+   * Builds a Constant Timer which pauses the thread with for a given duration.
+   *
+   * @param duration specifies the duration for the timer to wait.
+   * @return the timer for usage in test plan.
+   * @since 0.66
+   */
+  public static DslConstantTimer constantTimer(Duration duration) {
+    return new DslConstantTimer(duration);
+  }
+
+  /**
+   * Builds a Uniform Random Timer which pauses the thread with a random time with uniform
+   * distribution.
+   *
+   * @param minimumMillis is used to set the constant delay of the Uniform Random Timer.
+   * @param maximumMillis is used to set the maximum time the timer will be paused and will be used
+   *                      to obtain the random delay from the result of (maximumMillis -
+   *                      minimumMillis).
+   * @return The Uniform Random Timer instance
+   * @see DslUniformRandomTimer
+   * @see #uniformRandomTimer(Duration, Duration)
+   * @since 0.16
+   * @deprecated as of 0.66, use {@link #uniformRandomTimer(Duration, Duration)}
+   */
+  @Deprecated
+  public static DslUniformRandomTimer uniformRandomTimer(long minimumMillis, long maximumMillis) {
+    return uniformRandomTimer(Duration.ofMillis(minimumMillis), Duration.ofMillis(maximumMillis));
   }
 
   /**
    * Builds a Uniform Random Timer which pauses the thread with a random time with uniform
    * distribution.
    *
    * <p>
-   * The timer uses the minimumMillis and maximumMillis to define the range of values to be used in
+   * The timer uses the minimum and maximum durations to define the range of values to be used in
    * the uniformly distributed selected value. These values differ from the parameters used in
    * JMeter Uniform Random Timer element to make it simpler for general users to use. The generated
-   * JMeter test element uses as "constant delay offset" the minimumMillis value, and as "maximum
-   * random delay" (maximumMillis - minimumMillis) value.
+   * JMeter test element uses as "constant delay offset" the minimum value, and as "maximum
+   * random delay" (maximum - minimum) value.
    * </p>
    *
    * <p>
    * EXAMPLE: wait at least 3 seconds and maximum of 10 seconds
-   * {@code uniformRandomTimer(3000,10000)}
+   * {@code uniformRandomTimer(Duration.ofSeconds(3), Duration.ofSeconds(10))}
    * <p>
    *
-   * @param minimumMillis is used to set the constant delay of the Uniform Random Timer.
-   * @param maximumMillis is used to set the maximum time the timer will be paused and will be used
-   *                      to obtain the random delay from the result of (maximumMillis -
-   *                      minimumMillis).
+   * @param minimum is used to set the constant delay of the Uniform Random Timer.
+   * @param maximum is used to set the maximum time the timer will be paused and will be used
+   *                      to obtain the random delay from the result of (maximum -
+   *                      minimum).
    * @return The Uniform Random Timer instance
    * @see DslUniformRandomTimer
-   * @since 0.16
+   * @since 0.66
    */
-  public static DslUniformRandomTimer uniformRandomTimer(long minimumMillis, long maximumMillis) {
-    return new DslUniformRandomTimer(minimumMillis, maximumMillis);
+  public static DslUniformRandomTimer uniformRandomTimer(Duration minimum, Duration maximum) {
+    return new DslUniformRandomTimer(minimum, maximum);
   }
 
   /**

jmeter-java-dsl-jmx2dsl/src/test/resources/TestPlan.java

@@ -2,6 +2,7 @@
 
 import java.nio.charset.Charset;
 import java.time.Duration;
+import java.time.temporal.ChronoUnit;
 import java.util.function.BiFunction;
 import org.apache.jmeter.testelement.TestElement;
 import org.apache.jmeter.testelement.property.JMeterProperty;
@@ -236,6 +237,22 @@ public MethodParam durationParam(String propName) {
     return durationParam(propName, null);
   }
 
+  /**
+   * Gets a MethodParam representing a test element property containing a duration (in
+   * milliseconds).
+   *
+   * @param propName     is the name of the property. For nested properties (a property that is
+   *                     inside another object property) you can use the slash character to separate
+   *                     the levels (eg: http_config/use_proxy).
+   * @param defaultValue the default value assigned to the JMeter test element property.
+   * @return the {@link MethodParam} instance.
+   */
+  public MethodParam durationParamMillis(String propName, Duration defaultValue) {
+    return buildParam(propName,
+        (expression, defValue) -> new DurationParam(expression, defValue, ChronoUnit.MILLIS),
+        defaultValue);
+  }
+
   /**
    * Gets a MethodParam representing a test element property with a restricted set (enumerated) of
    * string values.

jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/JmeterDsl.java

@@ -2,7 +2,6 @@
 
 import java.lang.reflect.Method;
 import java.time.Duration;
-import java.time.temporal.ChronoUnit;
 import java.util.List;
 import kg.apc.jmeter.dummy.DummyElement;
 import kg.apc.jmeter.samplers.DummySampler;
@@ -12,7 +11,6 @@
 import us.abstracta.jmeter.javadsl.codegeneration.MethodCallContext;
 import us.abstracta.jmeter.javadsl.codegeneration.SingleTestElementCallBuilder;
 import us.abstracta.jmeter.javadsl.codegeneration.TestElementParamBuilder;
-import us.abstracta.jmeter.javadsl.codegeneration.params.DurationParam;
 import us.abstracta.jmeter.javadsl.core.util.JmeterFunction;
 
 /**
@@ -189,9 +187,7 @@ protected MethodCall buildMethodCall(DummySampler testElement, MethodCallContext
           .chain("responseCode", paramBuilder.stringParam("RESPONSE_CODE", DEFAULT_RESPONSE_CODE))
           .chain("responseMessage",
               paramBuilder.stringParam("RESPONSE_MESSAGE", DEFAULT_RESPONSE_MESSAGE))
-          .chain("responseTime", paramBuilder.buildParam("RESPONSE_TIME",
-              (expression, defaultValue) -> new DurationParam(expression, null, ChronoUnit.MILLIS),
-              null))
+          .chain("responseTime", paramBuilder.durationParamMillis("RESPONSE_TIME", null))
           .chain("simulateResponseTime", paramBuilder.boolParam("WAITING", false))
           .chain("url", paramBuilder.stringParam("URL"))
           .chain("requestBody", paramBuilder.stringParam("REQUEST_DATA"));