You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUITING.md
+16-16Lines changed: 16 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,25 +14,25 @@ Test elements are classes that implement [DslTestElement] interface, which basic
14
14
15
15
To implement your own DslTestElement, the library already provides some base classes from where to start:
16
16
17
-
*[BaseTestElement](src/main/java/us/abstracta/jmeter/javadsl/core/BaseTestElement.java): This contains the very basics of test elements, allowing to abstract the common logic of all test elements (ie: naming them, setting common properties and adding them to a JMeter tree). Create a subclass of this class only if the test element can't nest children, otherwise extend [TestElementContainer]. Examples: [HttpHeaders] and [JtlWriter].
18
-
*[TestElementContainer]: This represents a test element which can nest other test elements. If you need to implement a Sampler, then extend DslSampler instead. Examples: [DslTestPlan](src/main/java/us/abstracta/jmeter/javadsl/core/DslTestPlan.java), [DslThreadGroup](src/main/java/us/abstracta/jmeter/javadsl/core/DslThreadGroup.java).
19
-
*[DslSampler]: This contains common logic for samplers, and should be the class extended in most of the cases. Examples: [DslHttpSampler](src/main/java/us/abstracta/jmeter/javadsl/http/DslHttpSampler.java)
17
+
*[BaseTestElement](jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/core/BaseTestElement.java): This contains the very basics of test elements, allowing to abstract the common logic of all test elements (ie: naming them, setting common properties and adding them to a JMeter tree). Create a subclass of this class only if the test element can't nest children, otherwise extend [TestElementContainer]. Examples: [HttpHeaders] and [JtlWriter].
18
+
*[TestElementContainer]: This represents a test element which can nest other test elements. If you need to implement a Sampler, then extend DslSampler instead. Examples: [DslTestPlan](jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/core/DslTestPlan.java), [DslThreadGroup](jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/core/DslThreadGroup.java).
19
+
*[DslSampler]: This contains common logic for samplers, and should be the class extended in most of the cases. Examples: [DslHttpSampler](jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/http/DslHttpSampler.java)
20
20
21
21
As previously mentioned, DslTestElement instances can be nested, and when implementing one, you should define under what other test elements this element can be nested (eg: thread groups can only be added under test plans). To do that, just implement the appropriate interface required by the associated "parent" element, currently provided interfaces are:
So, for example, [DslThreadGroup](src/main/java/us/abstracta/jmeter/javadsl/core/DslThreadGroup.java) implements TestPlanChild and [DslSampler] implements ThreadGroupChild. You might implement multiple interfaces if the element can be used at different levels, for example check [HttpHeaders] and [JtlWriter] implement multiple interfaces.
27
+
So, for example, [DslThreadGroup](jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/core/DslThreadGroup.java) implements TestPlanChild and [DslSampler] implements ThreadGroupChild. You might implement multiple interfaces if the element can be used at different levels, for example check [HttpHeaders] and [JtlWriter] implement multiple interfaces.
28
28
29
29
You might also implement a new "child" interface if you need additional hierarchy levels (like ControllerChild).
30
30
31
31
## Test runs
32
32
33
-
When you want to run a test plan, it needs to run in a JMeter engine. By default, DslTestPlan uses [EmbeddedJMeterEngine](src/main/java/us/abstracta/jmeter/javadsl/core/EmbeddedJmeterEngine.java), which is the fastest and easiest way to run a test plan, but you might use EmbeddedJMeterEngine as an example and implement your own engine (for example to run tests on BlazeMeter, or in a distributed fashion).
33
+
When you want to run a test plan, it needs to run in a JMeter engine. By default, DslTestPlan uses [EmbeddedJMeterEngine](jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/core/EmbeddedJmeterEngine.java), which is the fastest and easiest way to run a test plan, but you might use EmbeddedJMeterEngine as an example and implement your own engine (for example to run tests on BlazeMeter, or in a distributed fashion).
34
34
35
-
When a test plan runs, the engine returns an instance of [TestPlanStats](src/main/java/us/abstracta/jmeter/javadsl/core/TestPlanStats.java), grouping information by test element name (aka label). This allows to check the expected statistics and verify that everything worked within expected boundaries.
35
+
When a test plan runs, the engine returns an instance of [TestPlanStats](jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/core/TestPlanStats.java), grouping information by test element name (aka label). This allows to check the expected statistics and verify that everything worked within expected boundaries.
36
36
37
37
## Class diagram
38
38
@@ -82,12 +82,12 @@ Add proper tests and update documentation (if needed) so users know about the ne
82
82
83
83
Just create an issue in the repository stating what you need and why, and we will do our best to implement what you need :).
84
84
85
-
Or, check existing code. It contains embedded documentation with additional detail, and the code never lies.
85
+
Or, check existing code. It contains embedded documentation with additional details, and the code never lies.
> This example also uses [AssertJ](https://joel-costigliola.github.io/assertj/assertj-core-quick-start.html) for assertions, but you can use whatever assertion library you chose.
47
47
48
-
More examples can be found in [tests](src/test/java/us/abstracta/jmeter/javadsl/JmeterDslTest.java)
48
+
More examples can be found in [tests](jmeter-java-dsl/src/test/java/us/abstracta/jmeter/javadsl/JmeterDslTest.java)
49
49
50
-
> **Tip 1:** Since JMeter uses [log4j2](https://logging.apache.org/log4j/2.x/), if you want to control logging level or output, you can use something similar to the tests included [log4j2.xml](src/test/resources/log4j2.xml).
50
+
> **Tip 1:** Since JMeter uses [log4j2](https://logging.apache.org/log4j/2.x/), if you want to control logging level or output, you can use something similar to the tests included [log4j2.xml](jmeter-java-dsl/src/test/resources/log4j2.xml).
51
51
>
52
52
> **Tip 2:** When working with multiple samplers in a test plan, specify their names to easily check their respective statistics.
53
53
@@ -61,7 +61,7 @@ But, JMeter has some problems as well: sometimes might be slow to create test pl
61
61
62
62
Gatling does provide a simple API and a VCS friendly format, but requires scala knowledge and environment. 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).
63
63
64
-
[Taurus](https://gettaurus.org/) is another open-source tool that allows specifying tests in a VCS 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, which reduces scope usage.
64
+
[Taurus](https://gettaurus.org/) is another open-source tool that allows specifying tests in a VCS 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, which reduces scope usage.
65
65
66
66
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.
67
67
@@ -80,16 +80,77 @@ Here is a table with summary of main pros and cons of each tool:
80
80
81
81
## Additional features
82
82
83
+
### Run test at scale
84
+
85
+
Running a load test from one machine is not always enough, since you are limited to the machine hardware capabilities. Some times is necessary to run the test using a cluster of machines to be able to generate enough load for the system under test.
86
+
87
+
By including following module as dependency:
88
+
89
+
```xml
90
+
<dependency>
91
+
<groupId>us.abstracta.jmeter</groupId>
92
+
<projectId>jmeter-java-dsl-blazemeter</projectId>
93
+
<version>0.2</version>
94
+
</dependency>
95
+
```
96
+
97
+
You can easily run a JMeter test plan at scale in BlazeMeter like this:
> This test is using `BZ_TOKEN` (a custom environment variable) to get the BlazeMeter API authentication credentials (with `<KEY_ID>:<KEY_SECRET>` format).
131
+
132
+
Note that is as simple as [generating a BlazeMeter authentication token](https://guide.blazemeter.com/hc/en-us/articles/115002213289-BlazeMeter-API-keys-) and adding `.runIn(new BlazeMeterEngine(...))` to any existing `jmeter-java-dsl` test to get it running at scale in BlazeMeter.
133
+
134
+
Check [BlazeMeterEngine](jmeter-java-dsl-blazemeter/src/main/java/us/abstracta/jmeter/javadsl/blazemeter/BlazeMeterEngine.java) for details on usage and available settings when running tests in BlazeMeter.
135
+
136
+
> **Tip:** In case you want to get debug logs for HTTP calls to BlazeMeter API, you can include following setting to an existing `log4j2.xml` configuration file:
public static void main(String[] args) throws Exception {
93
154
testPlan(
94
155
threadGroup(2, 10,
95
156
httpSampler("http://my.service")
@@ -105,7 +166,7 @@ public class SaveTestPlanAsJMX {
105
166
106
167
> Take into consideration that currently there is no automatic way to migrate changes done in JMX to the Java DSL.
107
168
108
-
This can be helpful to share a Java DSL defined test plan with people not used to the DSL, or to use some JMeter feature (or plugin) that is not yet supported by the DSL (**but we strongly encourage you to report it as an issue**, so we can implement support for it).
169
+
This can be helpful to share a Java DSL defined test plan with people not used to the DSL, or to use some JMeter feature (or plugin) that is not yet supported by the DSL (**but, we strongly encourage you to report it as an issue**, so we can implement support for it).
0 commit comments