Add counter for easy generation of auto increment values.

Author: rabelenda-abstracta

docs/guide/request-generation/counter.md

@@ -0,0 +1,17 @@
+### Counter
+
+In scenarios that you need unique value for each request, for example for id parameters, you can use `counter` which provides easy means to have an auto incremental value that can be used in requests.
+
+Here is an example:
+
+```java
+testPlan(
+    threadGroup(1, 10,
+        counter("USER_ID")
+            .startingValue(1000), // will generate 1000, 1001, 1002...
+        httpSampler(wiremockUri + "/${USER_ID}")
+    )
+).run();
+```
+
+Check [DslCounter](/jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/core/configs/DslCounter.java) for more details.

docs/guide/request-generation/index.md

@@ -2,9 +2,10 @@
 
 @include(if-controller.md)
 @include(loops/index.md)
-@include(jsr223-pre-processor.md)
-@include(csv-dataset.md)
 @include(transaction-controller.md)
+@include(csv-dataset.md)
+@include(counter.md)
+@include(jsr223-pre-processor.md)
 @include(timers.md)
 @include(throughput-timer.md)
 @include(percent-controller.md)

docs/guide/request-generation/jsr223-pre-processor.md

@@ -1,8 +1,8 @@
 ### Provide request parameters programmatically per request
 
-With the standard DSL you can provide static values to request parameters, such as a body. However, you may also want to be able to modify your requests for each call. This is common in cases where your request creates something that must have unique values.
+So far we have seen a few ways to generate requests with information extracted from CSV or through a counter, but this is not enough for some scenarios. When you need more flexibility and power you can use `jsr223preProcessor` to specify your own logic to build each request.
 
-Here is an example of how to achieve this:
+Here is an example:
 
 ```java
 import static org.assertj.core.api.Assertions.assertThat;
@@ -59,4 +59,8 @@ post(s -> buildRequestBody(s.vars), Type.TEXT_PLAIN)
 Using java code (lambdas) will only work with embedded JMeter engine (no support for saving to JMX and running it in JMeter GUI, or running it with BlazeMeter or OctoPerf). Use the first option to avoid such limitations.
 :::
 
+::: tip
+`jsr223PreProcessor` is quite powerful. But, provided example can easily be achieved through the usage of [counter element](./counter#counter).  
+:::
+
 Check [DslJsr223PreProcessor](/jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/core/preprocessors/DslJsr223PreProcessor.java) & [DslHttpSampler](/jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/http/DslHttpSampler.java) for more details and additional options.

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

@@ -8,6 +8,7 @@
 import us.abstracta.jmeter.javadsl.core.DslTestPlan;
 import us.abstracta.jmeter.javadsl.core.DslTestPlan.TestPlanChild;
 import us.abstracta.jmeter.javadsl.core.assertions.DslResponseAssertion;
+import us.abstracta.jmeter.javadsl.core.configs.DslCounter;
 import us.abstracta.jmeter.javadsl.core.configs.DslCsvDataSet;
 import us.abstracta.jmeter.javadsl.core.configs.DslVariables;
 import us.abstracta.jmeter.javadsl.core.controllers.DslForEachController;
@@ -98,10 +99,11 @@ public static DslTestPlan testPlan(TestPlanChild... children) {
    *                   thread group is configured to stop on error, or some other explicit
    *                   termination condition).
    *                   <p>
-   *                   <b>Setting this property to -1 is in general not advised</b>, since you might
-   *                   inadvertently end up running a test plan without
-   *                   limits consuming unnecessary computing power. Prefer specifying a big value
-   *                   as a safe limit for iterations or duration instead.
+   *                   <b>Setting this property to -1 is in general not advised</b>, since you
+   *                   might
+   *                   inadvertently end up running a test plan without limits consuming unnecessary
+   *                   computing power. Prefer specifying a big value as a safe limit for iterations
+   *                   or duration instead.
    * @param children   contains the test elements that each thread will execute in each iteration.
    * @return the thread group instance.
    * @see DslDefaultThreadGroup
@@ -1455,6 +1457,19 @@ public static DslCsvDataSet csvDataSet(TestResource resource) {
     return new DslCsvDataSet(resource.filePath());
   }
 
+  /**
+   * Builds a counter for easy usage of auto incremental numbers in test plans.
+   * <p>
+   * This element is handy when generating uto incremental ids, positions in a list, etc.
+   *
+   * @param name specifies the variable name used for holding the counter value.
+   * @return the counter for further configuration and usage.
+   * @since 1.10
+   */
+  public static DslCounter counter(String name) {
+    return new DslCounter(name);
+  }
+
   /**
    * Allows easy usage of test resources like the ones in {@code src/test/resource} in maven
    * projects.

jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/codegeneration/TestElementParamBuilder.java

@@ -133,6 +133,21 @@ public JMeterProperty prop(String propName) {
   /**
    * Generates a MethodParam representing a long test element property.
    *
+   * @param propName     is the name of the property holding a long value. 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 is the default value used by the test element for this property.
+   * @return the MethodParam instance.
+   * @throws UnsupportedOperationException when no long can be parsed from the property value.
+   * @since 1.10
+   */
+  public MethodParam longParam(String propName, Long defaultValue) {
+    return buildParam(propName, LongParam::new, defaultValue);
+  }
+
+  /**
+   * Same as {@link #longParam(String, Long)} but with no default value.
+   *
    * @param propName is the name of the property holding a long value. 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).
@@ -141,7 +156,7 @@ public JMeterProperty prop(String propName) {
    * @since 0.61
    */
   public MethodParam longParam(String propName) {
-    return buildParam(propName, LongParam::new, (Long) null);
+    return longParam(propName, null);
   }
 
   /**

jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/core/configs/DslCounter.java

@@ -0,0 +1,83 @@
+package us.abstracta.jmeter.javadsl.core.configs;
+
+import java.lang.reflect.Method;
+import java.util.List;
+import org.apache.jmeter.modifiers.CounterConfig;
+import org.apache.jmeter.modifiers.gui.CounterConfigGui;
+import org.apache.jmeter.testelement.TestElement;
+import us.abstracta.jmeter.javadsl.codegeneration.MethodCall;
+import us.abstracta.jmeter.javadsl.codegeneration.MethodCallContext;
+import us.abstracta.jmeter.javadsl.codegeneration.SingleTestElementCallBuilder;
+import us.abstracta.jmeter.javadsl.codegeneration.TestElementParamBuilder;
+
+/**
+ * Allows easy usage of auto incremental values in test plans.
+ * <p>
+ * This element is handy for generating incremental IDs, positions in certain list, etc.
+ *
+ * @since 1.10
+ */
+public class DslCounter extends BaseConfigElement {
+
+  private final String varName;
+  private String start = "0";
+
+  public DslCounter(String varName) {
+    super(varName, CounterConfigGui.class);
+    this.varName = varName;
+  }
+
+  /**
+   * Allows specifying the starting value of the counter.
+   *
+   * @param start specifies the value to start the counter with. When not specified, 0 will be
+   *              used.
+   * @return the counter for further configuration and usage.
+   */
+  public DslCounter startingValue(long start) {
+    return startingValue(String.valueOf(start));
+  }
+
+  /**
+   * Same as {@link #startingValue(long)} but allowing to use JMeter expressions for starting
+   * value.
+   * <p>
+   * This method allows to extract the initial value of the counter for example from a JMeter
+   * property (eg: ${__P(COUNT_INIT)}).
+   *
+   * @param start specifies a jmeter expression evaluating to a number that specifies the initial
+   *              value for the counter.
+   * @return the counter for further configuration and usage.
+   */
+  public DslCounter startingValue(String start) {
+    this.start = start;
+    return this;
+  }
+
+  @Override
+  protected TestElement buildTestElement() {
+    CounterConfig ret = new CounterConfig();
+    ret.setVarName(varName);
+    ret.setStart(start);
+    ret.setIncrement(1);
+    return ret;
+  }
+
+  public static class CodeBuilder extends SingleTestElementCallBuilder<CounterConfig> {
+
+    public CodeBuilder(List<Method> builderMethods) {
+      super(CounterConfig.class, builderMethods);
+    }
+
+    @Override
+    protected MethodCall buildMethodCall(CounterConfig testElement, MethodCallContext context) {
+      TestElementParamBuilder paramBuilder = new TestElementParamBuilder(testElement,
+          "CounterConfig");
+      MethodCall ret = buildMethodCall(paramBuilder.stringParam("name"));
+      ret.chain("startingValue", paramBuilder.longParam("start", 0L));
+      return ret;
+    }
+
+  }
+
+}

jmeter-java-dsl/src/test/java/us/abstracta/jmeter/javadsl/core/configs/DslCounterTest.java

@@ -0,0 +1,25 @@
+package us.abstracta.jmeter.javadsl.core.configs;
+
+import static com.github.tomakehurst.wiremock.client.WireMock.*;
+import static us.abstracta.jmeter.javadsl.JmeterDsl.*;
+
+import org.junit.jupiter.api.Test;
+import us.abstracta.jmeter.javadsl.JmeterDslTest;
+
+public class DslCounterTest extends JmeterDslTest {
+
+  @Test
+  public void shouldUseIncrementalValuesInRequestWhenCounterInRequest() throws Exception {
+    int startingValue = 1;
+    testPlan(
+        threadGroup(1, 2,
+            counter("USER_ID")
+                .startingValue(startingValue),
+            httpSampler(wiremockUri + "/${USER_ID}")
+        )
+    ).run();
+    verify(getRequestedFor(urlEqualTo("/" + startingValue)));
+    verify(getRequestedFor(urlEqualTo("/" + (startingValue + 1))));
+  }
+
+}