From daf6cf8b60a01613705ee35adef29e3350a5969b Mon Sep 17 00:00:00 2001 From: Joaquin Araujo Date: Wed, 3 Jul 2024 10:49:00 +0100 Subject: [PATCH] Documentation release v2.5.1 --- docs/package.json | 4 +- docs/src/.vuepress/config.js | 19 +- docs/src/guide/README.md | 22 +- docs/src/guide/after-recording.md | 2 +- docs/src/guide/analysis-configuration.md | 8 +- docs/src/guide/before-recording.md | 4 +- docs/src/guide/concepts.md | 18 +- .../guide/configuring-correlation-rules.md | 6 +- docs/src/guide/correlation-process.md | 14 +- docs/src/guide/correlation-rules.md | 199 +++++++++--------- docs/src/guide/custom-extensions/README.md | 6 +- .../custom-extensions/custom-extensions.md | 6 +- .../siebel_extension_explanations.md | 4 +- .../custom-extensions/the_flow_explanation.md | 2 +- docs/src/guide/installation-configuration.md | 27 ++- docs/src/guide/installation-guide.md | 82 ++++---- docs/src/guide/knonw-issues.md | 36 ++-- docs/src/guide/templates/create.md | 4 +- docs/src/guide/templates/readme.md | 10 +- docs/src/guide/troubleshooting.md | 65 +++--- docs/src/guide/using-the-plugin.md | 77 +++---- 21 files changed, 327 insertions(+), 288 deletions(-) diff --git a/docs/package.json b/docs/package.json index 74578e7..5ef5c1f 100755 --- a/docs/package.json +++ b/docs/package.json @@ -1,7 +1,7 @@ { - "name": "CorrelationRecorder", + "name": "AutoCorrelationRecorder", "version": "2.0.", - "description": "Effortlessly handle dynamic values in JMeter with the Correlation recorder plugin.", + "description": "Effortlessly handle dynamic values in JMeter with the Auto Correlation Recorder plugin.", "main": "index.js", "authors": { "name": "", diff --git a/docs/src/.vuepress/config.js b/docs/src/.vuepress/config.js index d2b64ee..18b8214 100755 --- a/docs/src/.vuepress/config.js +++ b/docs/src/.vuepress/config.js @@ -1,16 +1,23 @@ -const { description } = require("../../package"); +const {description} = require("../../package"); const REPO_URL = "https://github.com/Blazemeter/CorrelationRecorder"; +const BASE_PATH = buildBaseUrl(); + +function buildBaseUrl() { + return process.env.CI_PAGES_URL + ? "/jmeter-siebel-plugin/" + : "/CorrelationRecorder/"; +} module.exports = { /** * Ref：https://v1.vuepress.vuejs.org/config/#title */ - title: "Correlation Recorder", + title: "Auto Correlation Recorder", /** * Ref：https://v1.vuepress.vuejs.org/config/#description */ description: description, - base: "/CorrelationRecorder/", + base: BASE_PATH, /** * Extra tags to be injected to the page HTML `` @@ -18,11 +25,11 @@ module.exports = { * ref：https://v1.vuepress.vuejs.org/config/#head */ head: [ - ["meta", { name: "theme-color", content: "#00ace6" }], - ["meta", { name: "apple-mobile-web-app-capable", content: "yes" }], + ["meta", {name: "theme-color", content: "#00ace6"}], + ["meta", {name: "apple-mobile-web-app-capable", content: "yes"}], [ "meta", - { name: "apple-mobile-web-app-status-bar-style", content: "black" }, + {name: "apple-mobile-web-app-status-bar-style", content: "black"}, ], ], diff --git a/docs/src/guide/README.md b/docs/src/guide/README.md index 54fd9d2..eda9c93 100644 --- a/docs/src/guide/README.md +++ b/docs/src/guide/README.md @@ -4,7 +4,7 @@ next: /guide/installation-guide.md # User Guide -Correlations Recorder it's a [JMeter's](http://jmeter.apache.org/usermanual/get-started.html) plugin that simplifies +Auto Correlation Recorder it's a [JMeter's](http://jmeter.apache.org/usermanual/get-started.html) plugin that simplifies the process of recording for applications with Dynamic Variables by providing automatic **correlations of variables**. You can perform exploratory detections of dynamic variables and create **correlation rules** to correlate them @@ -32,18 +32,18 @@ Additional Features: ## Benefits -Here are 10 key benefits of using the JMeter's Automatic Correlation Recorder Plugin: +Here are 10 key benefits of using the JMeter's Auto Correlation Recorder Plugin: 1. Fast script creation -2. Preloaded templates -3. Hassle-free collaboration -4. Customizable correlations -5. Easy customization -6. Streamlined collaboration -7. Customizable extensions -8. Dynamic value correlation -9. Fast rule generation -10. Reliable testing. +1. Preloaded templates +1. Hassle-free collaboration +1. Customizable correlations +1. Easy customization +1. Streamlined collaboration +1. Customizable extensions +1. Dynamic value correlation +1. Fast rule generation +1. Reliable testing. ## System requirements diff --git a/docs/src/guide/after-recording.md b/docs/src/guide/after-recording.md index 9c13529..1337e0e 100644 --- a/docs/src/guide/after-recording.md +++ b/docs/src/guide/after-recording.md @@ -86,7 +86,7 @@ If you want to know more about Enterprise Correlation Templates, please contact 4. Add the JTL file of the recording (if it isn't already loaded) -By default, the plugin loads the JTL file that is found in the View Result Tree of the "bzm - Correlation Recorder" element. +By default, the plugin loads the JTL file that is found in the View Result Tree of the "bzm - Auto Correlation Recorder" element. If you want to use a different JTL file, you can click on the "Browse" button and select the file you want to use. ::: warning diff --git a/docs/src/guide/analysis-configuration.md b/docs/src/guide/analysis-configuration.md index 1052334..555346d 100644 --- a/docs/src/guide/analysis-configuration.md +++ b/docs/src/guide/analysis-configuration.md @@ -3,9 +3,9 @@ prev: /guide/after-recording.md next: /guide/before-recording.md --- -# Configuring the Correlation Recorder Plugin +# Configuring the Auto Correlation Recorder Plugin -The Correlation Recorder plugin in JMeter allows you to automatically correlate dynamic values in your +The Auto Correlation Recorder plugin in JMeter allows you to automatically correlate dynamic values in your HTTP requests. The plugin provides several configurations that can be customized to meet your specific needs. ## Available Configurations @@ -95,7 +95,7 @@ With this, the plugin will ignore any request that has `example.com` in its doma ### Exclude small values -Don't want the Correlation Recorder Plugin to pick up certain small values? We get it! Sometimes those tiny arguments, +Don't want the Auto Correlation Recorder Plugin to pick up certain small values? We get it! Sometimes those tiny arguments, like "amount" with a value of "100", just aren't worth correlating. If you're using Automatic Correlation analysis by Correlation Templates, this particular element probably won't be @@ -115,7 +115,7 @@ correlation.configuration.min_value_length=10 ### Exclude certain file types from correlation Let's say that you have a web application that serves different types of files such as images, PDFs, or CSS files. -When recording your test scenario, you notice that the Correlation Recorder plugin is also capturing some of these +When recording your test scenario, you notice that the Auto Correlation Recorder plugin is also capturing some of these files as dynamic values. Since these files are not part of the application's business logic, you may want to exclude them from the correlation analysis. diff --git a/docs/src/guide/before-recording.md b/docs/src/guide/before-recording.md index 2302f30..0a4adaa 100644 --- a/docs/src/guide/before-recording.md +++ b/docs/src/guide/before-recording.md @@ -72,7 +72,7 @@ requests, not only possible, but also easier than if you manage to do it, alone, Assuming you know [how Correlations works](#basic-concepts), lets jump into adding and configuring your rules. -Go to _bzm - Correlation Recorder_ > click the Rules Tab. +Go to _bzm - Auto Correlation Recorder_ > click the Rules Tab. You will be presented with multiple options to add, move and delete your Correlation Rules Groups, any rule that you want to add must be inside a group @@ -348,7 +348,7 @@ This section will be divided into cases, from simple and common cases to unusual ## Variable Replacement -The replacement of dynamic or static data in a request for JMeter Variables is one of the main objectives of the **Correlation Recorder**. +The replacement of dynamic or static data in a request for JMeter Variables is one of the main objectives of the **Auto Correlation Recorder**. Mainly, the idea is to replace data for variables, therefore, we get a proper correlated script. The data we want to replace needs to match a certain regex, condition or even a criteria. diff --git a/docs/src/guide/concepts.md b/docs/src/guide/concepts.md index 345e1a8..67e4e41 100644 --- a/docs/src/guide/concepts.md +++ b/docs/src/guide/concepts.md @@ -66,16 +66,16 @@ requests with the JMeter variable containing the captured value. This ensures th a unique value. Manual correlation can be a time-consuming process, particularly when dealing with large or complex test scenarios -that involve multiple dynamic values. This is where Automatic Correlation recorder comes in handy. -The Automatic Correlation recorder provides several methods for automatically detecting and correlating dynamic +that involve multiple dynamic values. This is where Auto Correlation Recorder comes in handy. +The Auto Correlation Recorder provides several methods for automatically detecting and correlating dynamic values, including the use of regular expressions and JSON Path expressions. -Here are some of the Automatic Correlation methods supported by Correlation Recorder: +Here are some of the Automatic Correlation methods supported by Auto Correlation Recorder: 1. RegEx (Regular Expression) Extractor 1. JSON Extractor -By using the Automatic Correlation recorder, however, you can simplify the process of correlating dynamic values and save time when creating test scripts. +By using the Auto Correlation Recorder, however, you can simplify the process of correlating dynamic values and save time when creating test scripts. Please take a look at previous sections in the guide, where you can learn about the different mechanisms for automatically correlating dynamic values, either after the recording is being done or after the whole recording @@ -83,7 +83,7 @@ is done. ## Correlation Rule -The Correlation Recorder plugin provides a powerful feature called "Correlation Rules" that simplifies the process of +The Auto Correlation Recorder plugin provides a powerful feature called "Correlation Rules" that simplifies the process of making correlations in JMeter scripts. A Correlation Rule consists of three key components: Reference Variable: This variable is used to store the dynamic value that will be extracted from a response and @@ -104,23 +104,23 @@ refer to the "Correlation Rules" section of the JMeter User Manual. ## Correlation Template -The Correlation Recorder Plugin in JMeter utilizes Correlation Templates to maintain a simplified versioning of +The Auto Correlation Recorder Plugin in JMeter utilizes Correlation Templates to maintain a simplified versioning of Correlation Rules and to store and organize them together. A Correlation Template includes essential information such as version number, name, description, and changes log. -The Correlation Template serves as the foundation for the Automatic Correlation Analysis in the Correlation Recorder +The Correlation Template serves as the foundation for the Automatic Correlation Analysis in the Auto Correlation Recorder Plugin. It allows the user to keep track of the version of the Correlation Rules being used for the analysis. This feature ensures that the user is always working with the latest version of the Correlation Rules and helps to maintain the accuracy of the results. Additionally, BlazeMeter provides several Correlation Templates that are designed for different technologies and protocols. These templates can be used to facilitate the correlation process for specific types of applications -and make it easier for users to get started with the Correlation Recorder Plugin. To learn more about how to use +and make it easier for users to get started with the Auto Correlation Recorder Plugin. To learn more about how to use Correlation Templates and benefit from this powerful feature, refer to the JMeter User Manual. ## Correlation Repository -The Correlation Repository is a powerful mechanism used by the Correlation Recorder Plugin in JMeter to keep your set +The Correlation Repository is a powerful mechanism used by the Auto Correlation Recorder Plugin in JMeter to keep your set of Correlation Templates up-to-date. This feature allows for continuous updates of Correlation Templates from external sources. diff --git a/docs/src/guide/configuring-correlation-rules.md b/docs/src/guide/configuring-correlation-rules.md index 9ea8940..77bad11 100644 --- a/docs/src/guide/configuring-correlation-rules.md +++ b/docs/src/guide/configuring-correlation-rules.md @@ -4,12 +4,12 @@ sidebar: auto # Correlation Rules -Correlation rules are the mechanism that allows you to define how to the Correlation Recorder will detect dynamic values, extract and replacement them in your recorded flow. +Correlation rules are the mechanism that allows you to define how to the Auto Correlation Recorder will detect dynamic values, extract and replacement them in your recorded flow. ## Concepts -A Correlation Rule consists of three elements: a **Reference variable name**, an **Extractor**, and a **Replacement**. +A Correlation Rule consists of three elements: a **Reference variable name**, an **Extractor**, and a **Replacement**. It's important to note that while the **Reference variable name must be defined,** it doesn't have to be unique. You can create **multiple** correlation rules with **the same name**. -You can create a Correlation Rule with only an Extractor or only a Replacement, but at least one of them must be defined. If you create multiple rules with the same reference variable name, but different extractors or replacements, you'll be able to extract or replace the same dynamic value in different ways. \ No newline at end of file +You can create a Correlation Rule with only an Extractor or only a Replacement, but at least one of them must be defined. If you create multiple rules with the same reference variable name, but different extractors or replacements, you'll be able to extract or replace the same dynamic value in different ways. diff --git a/docs/src/guide/correlation-process.md b/docs/src/guide/correlation-process.md index fd79504..71035a0 100644 --- a/docs/src/guide/correlation-process.md +++ b/docs/src/guide/correlation-process.md @@ -28,11 +28,11 @@ This process is repeated on each failed request until all the dynamic values are the dynamic values are not easy to locate, and sometimes, they might even have different values for the same argument within the same recording. -When performing this process manually, it can be very time-consuming and frustrating. That's why we created the Correlation Recorder plugin, to automate this process and make it easier for you. +When performing this process manually, it can be very time-consuming and frustrating. That's why we created the Auto Correlation Recorder plugin, to automate this process and make it easier for you. ## Methods of Correlation -The Correlation Recorder plugin offers different methods of correlation, each one with its own advantages and disadvantages. In this section, we will cover all of them divided into two categories: Before the Recording and After the Recording. +The Auto Correlation Recorder plugin offers different methods of correlation, each one with its own advantages and disadvantages. In this section, we will cover all of them divided into two categories: Before the Recording and After the Recording. ### Before the Recording @@ -41,11 +41,13 @@ When we say 'Before the Recording,' it refers to the process between loading the Once you have finished configuring the rules, you can start the recording, and the plugin will automatically compare each request and response with the configured rules. Pros: + - It is the most flexible method since you can configure it to your needs. - It is the most efficient method since it is the only one that does not require you to replay the recording. - It supports extensibility, allowing you to develop your own rules according to your needs. Cons: + - It requires you to configure the rules before the recording is done. - It requires prior knowledge of potential dynamic values and how to configure the rules to extract them. - It requires a re-recording to test the changes made to the rules. @@ -69,12 +71,14 @@ Let's see what each one of these methods has to offer. This method involves analyzing a recording using different Correlation Templates to automatically detect dynamic values. It generates a list of Correlation Suggestions based on those values and lets you choose which ones to apply in the Test Plan. Pros: + - This is the most reliable method as it only correlates the dynamic values found with the rules in the Correlation Template. - It lets you test any set of Correlation Rules before applying them to the Test Plan. - You can easily roll-back changes made to the Test Plan as it stores it in a separate file. - It integrates with the Correlation Repository feature, allowing you to use the Correlation Templates from BlazeMeter, GitHub, or any other sources, aside from your local ones. Cons: + - It still requires Rules to properly correlate the dynamic values. - It does not detect dynamic values that are not present in the Correlation Templates. @@ -83,19 +87,21 @@ Cons: This method involves analyzing the results of a recording replay by comparing them with the original recording. It only focuses on the arguments of the requests that failed in the replay. By doing so, it generates a list of Correlation Suggestions based on the differences found, allowing you to select which ones to apply in the Test Plan. Pros: + - It is pretty flexible since it detects dynamic values that you might not be aware of. - It is customizable since you can configure how the analysis is done. Cons: + - It is not 100% bullet-proof since it might correlate dynamic values that are not dynamic. - It requires your input of which of the detected dynamic values you are interested in correlating. Otherwise, it will end up correlating values that you might not be interested in. While they both have their own advantages and disadvantages, we recommend you use the **Correlation by Using Correlation Templates** method as it is the most reliable one. With that being said, the **Correlation by Replay and Compare** method can be pretty useful when you are not sure where the dynamic values are present in the recording. -In conclusion, the Correlation Process is a crucial step in JMeter testing, and the Correlation Recorder plugin provides several methods to make it easier and more efficient. By following the recommended methods, you can save time and effort and ensure a more accurate and reliable test plan. +In conclusion, the Correlation Process is a crucial step in JMeter testing, and the Auto Correlation Recorder plugin provides several methods to make it easier and more efficient. By following the recommended methods, you can save time and effort and ensure a more accurate and reliable test plan. If you are new to JMeter, we recommend you start with the basics of recording and gradually move on to the more advanced topics of correlation. Take your time to learn and practice the different methods, and find the one that works best for your specific scenario. Also, keep in mind that correlation is not a one-time process. Dynamic values can change over time, and you may need to update your correlation rules or templates accordingly. So, make sure to regularly review and update your test plan to ensure its accuracy and reliability. -In summary, the correlation process is a crucial part of JMeter testing, and the Correlation Recorder plugin provides valuable tools to make it easier and more efficient. By mastering the different methods and techniques, you can create accurate and reliable test plans that can help you identify performance issues and optimize your applications. \ No newline at end of file +In summary, the correlation process is a crucial part of JMeter testing, and the Auto Correlation Recorder plugin provides valuable tools to make it easier and more efficient. By mastering the different methods and techniques, you can create accurate and reliable test plans that can help you identify performance issues and optimize your applications. diff --git a/docs/src/guide/correlation-rules.md b/docs/src/guide/correlation-rules.md index 8cc3f21..82d2b07 100644 --- a/docs/src/guide/correlation-rules.md +++ b/docs/src/guide/correlation-rules.md @@ -11,20 +11,20 @@ When a **Response** comes from the server, there are ways to get the information - It could be stored on a Cookie, that has an expiration date The Correlation Extractor has, as its main responsibility, locate if in any of these cases, there are embedded - dynamic variables. In the case where there are, its second responsibility is to extract and save the value so - that, in future requests that the app made, other players take those values and replace it, allowing the full - cycle to be completed. +dynamic variables. In the case where there are, its second responsibility is to extract and save the value so +that, in future requests that the app made, other players take those values and replace it, allowing the full +cycle to be completed. ## Correlation Replacement Now that its known who it's the one responsible to extract the values from the responses, it's the responsibility - to the Correlation Replacement to take those values and replacement them in the following requests, made to the server. +to the Correlation Replacement to take those values and replacement them in the following requests, made to the server. ## Reference Variable Even if it's not part of the process of correlating dynamic values, when one its extracted, the name of the place - where its stored, and from where its going to be taken, in order to replace it, in the subsequent requests, - it's called Reference Variable. +where its stored, and from where its going to be taken, in order to replace it, in the subsequent requests, +it's called Reference Variable. Everything that it's been explained, so far, will be used in one final tool: a Correlation Rule. @@ -33,17 +33,17 @@ Everything that it's been explained, so far, will be used in one final tool: a C Once all those concepts are explained, the tool that allows to merge them together, it's the Correlation Rule. Each Correlation Rule contains, a Correlation Extractor, as you now know, to extracts the dynamic value, - a Reference Variable, to store the value from the Extractor for the Replacement, and one Correlation Replacement. +a Reference Variable, to store the value from the Extractor for the Replacement, and one Correlation Replacement. Each one of these rules, will help to make this whole process of capturing and replacing values between responses and - requests, not only possible, but also easier than if you manage to do it, alone, using JMeter. +requests, not only possible, but also easier than if you manage to do it, alone, using JMeter. ### Configuration Assuming you know [what a correlation is](/guide/correlation-process.md#correlation-process-2) and which parts of the process - the [Correlation Rules are part of](/guide/after-recording.md#by-using-correlation-templates) lets jump into adding and configuring your rules. +the [Correlation Rules are part of](/guide/after-recording.md#by-using-correlation-templates) lets jump into adding and configuring your rules. -Go to *bzm - Correlation Recorder* > click the Rules Tab. +Go to *bzm - Auto Correlation Recorder* > click the Rules Tab. You will be presented with multiple options to add, move and delete your Correlation Rules Groups, any rule that you want to add must be inside a group @@ -97,7 +97,7 @@ Also, Correlation Replacements have their own Advance section, like Correlation ![Expand_Advance_Section Replacement](./assets/expand-advance-sextion-replacement.gif "Expanding advance section on Correlation Replacement") -As in Correlation Extractor, here to add any Correlation Replacement the option **more** should be used. +As in Correlation Extractor, here to add any Correlation Replacement the option **more** should be used. ![Add_Custom_Replacement](./assets/add_custom_replacement.gif "Adding custom Correlation Replacement") @@ -130,20 +130,20 @@ This extractor comes installed, by default, in the plugin, and it receives 4 fie ![Regex Correlation Extractor](./assets/regex-correlation-extractor.png) -1. *RegEx*: which corresponds to the Regular Expression that will be used to perform the extraction. -1. *Match Number*: In the case that the Regex matches more than once in the response, this number will indicate which one of all of them it's going to be extracted. Use the value `-1` when you need to retrieve all matched values from the expressions. -1. *Match Group*: In the case that the Regex contains, more than one group, this field indicates which one of those is going to be considered to do the extraction, once the Regex its matched. Only use positive numbers. -1. *Target*: Which field to check the regular expression against. - * *The following fields can be checked: (from JMeter documentation):* - * *Body* - the body of the response, e.g. the content of a web-page (excluding headers) - * *Body (unescaped)* - the body of the response, with all Html escape codes replaced. Note that Html escapes are processed wi thought regard of context, so some incorrect substitutions may be made. Note that this option highly impacts performances, so use it only when absolutely necessary and be aware of its impacts. - * *Body as a Document* - extract text from various type of documents via Apache Tika. Note that Body as a Document option can impact performance, so ensure it is OK for your test. - * *Request Headers* - the request header of the HTTP sampler. - * *Response Headers* - the response header of the HTTP sampler. - * *URL* - * *Response Code* - e.g. 200 - * *Response Message* - e.g. OK -1. *Multivalued*: Multiple valuation is useful when we want to separate each unique value as a particular variant name from different responses. Variables extracted with multivalued are non-overwritable and additionally they have a specific format. See [Variable Generation](#variable-generation) for case usages and variable formats. +1. _RegEx_: which corresponds to the Regular Expression that will be used to perform the extraction. +1. _Match Number_: In the case that the Regex matches more than once in the response, this number will indicate which one of all of them it's going to be extracted. Use the value `-1` when you need to retrieve all matched values from the expressions. +1. _Match Group_: In the case that the Regex contains, more than one group, this field indicates which one of those is going to be considered to do the extraction, once the Regex its matched. Only use positive numbers. +1. _Target_: Which field to check the regular expression against. + - _The following fields can be checked: (from JMeter documentation):_ + - _Body_ - the body of the response, e.g. the content of a web-page (excluding headers) + - _Body (unescaped)_ - the body of the response, with all Html escape codes replaced. Note that Html escapes are processed wi thought regard of context, so some incorrect substitutions may be made. Note that this option highly impacts performances, so use it only when absolutely necessary and be aware of its impacts. + - _Body as a Document_ - extract text from various type of documents via Apache Tika. Note that Body as a Document option can impact performance, so ensure it is OK for your test. + - _Request Headers_ - the request header of the HTTP sampler. + - _Response Headers_ - the response header of the HTTP sampler. + - _URL_ + - _Response Code_ - e.g. 200 + - _Response Message_ - e.g. OK +1. _Multivalued_: Multiple valuation is useful when we want to separate each unique value as a particular variant name from different responses. Variables extracted with multivalued are non-overwritable and additionally they have a specific format. See [Variable Generation](#variable-generation) for case usages and variable formats. In case the Regex Extractor is not matched, during a Replay of a Recorded flow, the replaced value will be ` + "_NOT_FOUND"`. **JSON** @@ -159,12 +159,12 @@ This extractor comes installed, by default, in the plugin, and it receives 4 fie ![JSON Correlation Extractor](./assets/json-correlation-extractor.png) -1. *JSON*: which corresponds to the JSONPath Expression that will be used to perform the extraction. -1. *Match Number*: In the case that the JSONPath matches more than once in the response, this number will indicate which one of all of them it's going to be extracted. Use the value `-1` when you need to retrieve all matched values from the expressions. -1. *Target*: Which field to check the regular expression against. - * *The following fields can be checked: (from JMeter documentation):* - * *Body* - the body of the response, e.g. the content of a web-page (excluding headers) -1. *Multivalued*: Multiple valuation is useful when we want to separate each unique value as a particular variant name from different responses. Variables extracted with multivalued are non-overwritable and additionally they have a specific format. See [Variable Generation](#variable-generation) for case usages and variable formats. +1. _JSON_: which corresponds to the JSONPath Expression that will be used to perform the extraction. +1. _Match Number_: In the case that the JSONPath matches more than once in the response, this number will indicate which one of all of them it's going to be extracted. Use the value `-1` when you need to retrieve all matched values from the expressions. +1. _Target_: Which field to check the regular expression against. + - _The following fields can be checked: (from JMeter documentation):_ + - _Body_ - the body of the response, e.g. the content of a web-page (excluding headers) +1. _Multivalued_: Multiple valuation is useful when we want to separate each unique value as a particular variant name from different responses. Variables extracted with multivalued are non-overwritable and additionally they have a specific format. See [Variable Generation](#variable-generation) for case usages and variable formats. In case the JSONPath Extractor is not matched, during a Replay of a Recorded flow, the replaced value will be ` + "_NOT_FOUND"`. JMeter use JSONPath syntax from [Jayway JsonPath](https://github.com/json-path/JsonPath) Use the Jayway JsonPath syntax documentation as a reference. @@ -180,25 +180,30 @@ JMeter allows you to evaluate JSONPaths in the Sample results of the ViewResult An example will be provided below that will allow you to visually understand some general concepts of the JSONPath syntax. ```json -{ "store": { +{ + "store": { "book": [ - { "category": "reference", + { + "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 }, - { "category": "fiction", + { + "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 }, - { "category": "fiction", + { + "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99 }, - { "category": "fiction", + { + "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", @@ -216,19 +221,19 @@ An example will be provided below that will allow you to visually understand som Some JSONPath query expressions and their expected result. | JSONPath | Intended result | -|-----------------------------|-------------------------------------------------------------------| +| --------------------------- | ----------------------------------------------------------------- | | $.store.book[*].author | the authors of all books in the store | | $..author | all authors | -| $.store.* | all things in store, which are some books and a red bicycle | +| $.store.\* | all things in store, which are some books and a red bicycle | | $.store..price | the prices of everything in the store | | $..book[2] | the third book | | $..book[2].author | the third book's author | | $..book[2].publisher | empty result: the third book does not have a "publisher" member | | $..book[-1] | the last book in order | | $..book[0,1] or $..book[:2] | the first two books | -| $..book[?@.isbn] | all books with an ISBN number | +| $..book[?@.isbn] | all books with an ISBN number | | $..book[?@.price<10] | all books cheaper than 10 | -| $..* | all member values and array elements contained in the input value | +| $..\* | all member values and array elements contained in the input value | The IETF group in charge of creating Internet standards in February 2024 completed its work on the creation of RFC 9535 associated with JSONPath. You can consult the RFC documentation in case you require more details about JSONPath @@ -243,31 +248,30 @@ This Correlation Extractor comes in the already installed Siebel's Template. To The Siebel Row Correlation Extractor works in a similar way like the previously mentioned RegEx, with the main differences that: - This applies a "Siebel Star Array strings" parsing function over the matched regex and store the parsed values as variables. -- Regarding the Parameters expected, Siebel Row Correlation Extractor uses all but the *Match Number*, since it parses every match it founds. +- Regarding the Parameters expected, Siebel Row Correlation Extractor uses all but the _Match Number_, since it parses every match it founds. - Last, but not least, if the Regex its matched, a JSR223PostProcessor will be added to the sampler. -*For a better understanding, lets do an example* +_For a better understanding, lets do an example_ Let's say that the String we want to extract and, therefore, apply this extracting and parsing function, its `8\*testUser12\*testPassword6\*VRId-0` -The plugin will search for the number before an occurrence of "\*", uses that value as the length of the number of characters to store, and then repeats if there is another occurrence of "*". +The plugin will search for the number before an occurrence of "\*", uses that value as the length of the number of characters to store, and then repeats if there is another occurrence of "\*". -If the Reference Variable is set to *VAR*, the split strings returned will be set in variables names like ${VAR_1}, ${VAR_2}, ${VAR_3} etc. and, the count of variables is returned as ${VAR_n}. +If the Reference Variable is set to _VAR_, the split strings returned will be set in variables names like ${VAR_1}, ${VAR_2}, ${VAR_3} etc. and, the count of variables is returned as ${VAR_n}. The stored values for that string, at the end, will be: -* VAR_n=3 -* VAR_1=testUser -* VAR_2=testPassword -* VAR_3=VRId-0 +- VAR_n=3 +- VAR_1=testUser +- VAR_2=testPassword +- VAR_3=VRId-0 ### Star Array Correlation When the server returns variables using a star array, the plugin will parse the array and generate a new variable for each of the parameters, using the specified prefix name. - ## Variable Generation The creation of JMeter variables for later usage is one of the pillars of this plugin. Therefore, this section is specially dedicated to understand and review all the possible scenarios. @@ -280,42 +284,42 @@ This section will be divided into cases, from simple and common cases to unusual ### Extract specific match from the response (overridable) | | Description | -|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Objective | extract the second appearance of a character chain included on the response that matches the given regex | | Configuration | need to specify a variable name (the variable stored will use it), regex, desired match number and no need to check for multi-valued | | Visualization | ![extractor_configuration_visualization](./assets/extraction-specific-match-overwritable.png) | | Overall | value will be stored in a JMeter variable, with the exact name as the value introduced on the reference variable name field. **If a variable exists (from previous extractions) the variable will be overwritten with new match value** | ### Extract specific match from a response (not overridable) + | | Description | -|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Objective | extract a certain value from a specific match number on the response. The value will be saved in a non-overwritable variable. | -| Configuration | variable name, regex, desired match number and **multivalue must be selected** | +| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Objective | extract a certain value from a specific match number on the response. The value will be saved in a non-overwritable variable. | +| Configuration | variable name, regex, desired match number and **multivalue must be selected** | | Visualization | ![extractor_configuration_visualization](./assets/extraction-specific-match-non-overwritable.png) | -| Overall | value will be extracted and stored in a variable with the following convention: E.g: `var#34`
  • **var**: reference variable name
  • **#34**: represents the variable count number
Note: this variable will endure the whole execution | +| Overall | value will be extracted and stored in a variable with the following convention: E.g: `var#34`
  • **var**: reference variable name
  • **#34**: represents the variable count number
Note: this variable will endure the whole execution | ### Extract multiple variables that can be overwritten | | Description | -|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Objective | extract all values that match the regex on the response | | Configuration | variable name, regex, **match number needs to be lower than 0** (E.g: -1). No need for multi-valued. | | Visualization | ![extractor_configuration_visualization](./assets/extraction-multiple-overwritable.png) | | Overall | a new variable will be created to store every match found on the response. If the variable already exists, it will be overwritten. The format of this type of variable consists of a prefix (reference variable name) with an underscore followed by the integer which represents the match number of the extracted value. E.g: **ID_1**
**Important**: If variables are been extracted in previous responses, for instance, 5 matches (`ID_1, ID_2,..., ID_5`), when another response arrives with new matches, these variables will not just be overwritten, will be deleted. If the new response matches thrice, then the resultant variables will be `ID_1, ID_2, ID_3`. Previous variables `ID_4` and `ID_5` will no longer exist. | - ### Extract multiple variables that can NOT be overwritten -| | Description | -|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Objective | extract all values that match the regex on the response and store them immutably | -| Configuration | variable name, regex, **match number needs to be lower than 0** (E.g: -1). **_Multi-valued needs to be checked_** | -| Visualization | ![extractor_configuration_visualization](./assets/extraction-multiple-non-overwritable.png) | -| Overall | a new variable will be created to store every match found on the response. This type of extractions have a particular format name. E.g: `myVar#2_1` Where:
  • **myVar**: reference variable name
  • **#2**: hash followed by the variable count number
  • **\_1**: number of match in that response

New JMeter variables are created (with the format showed above) every time a response arrives, and the regex matches more than twice.
Note: if the response contains one match, and optimization is done. Therefore, the generated variable will be like in section _Extract specific match from a response (not overwritable)_ | +| | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Objective | extract all values that match the regex on the response and store them immutably | +| Configuration | variable name, regex, **match number needs to be lower than 0** (E.g: -1). **_Multi-valued needs to be checked_** | +| Visualization | ![extractor_configuration_visualization](./assets/extraction-multiple-non-overwritable.png) | +| Overall | a new variable will be created to store every match found on the response. This type of extractions have a particular format name. E.g: `myVar#2_1` Where:
  • **myVar**: reference variable name
  • **#2**: hash followed by the variable count number
  • **\_1**: number of match in that response

New JMeter variables are created (with the format showed above) every time a response arrives, and the regex matches more than twice.
Note: if the response contains one match, and optimization is done. Therefore, the generated variable will be like in section _Extract specific match from a response (not overwritable)_ | ## Variable Replacement -The replacement of dynamic or static data in a request for JMeter Variables is one of the main objectives of the **Correlation Recorder**. +The replacement of dynamic or static data in a request for JMeter Variables is one of the main objectives of the **Auto Correlation Recorder**. Mainly, the idea is to replace data for variables, therefore, we get a proper correlated script. The data we want to replace needs to match a certain regex, condition or even a criteria. @@ -330,17 +334,18 @@ The result we are looking for should be a request with a parametrized value, in The desired result will look something like: `www.my-market-place.com/cart.html?product_id=${id_product}` -Now that we have a basic idea of a replacement, lets explain the most complex and used replacement. The *Regex Correlation Replacement* which accepts three parameters: +Now that we have a basic idea of a replacement, lets explain the most complex and used replacement. The _Regex Correlation Replacement_ which accepts three parameters: 1. **regex**: the regex needed to match the data to be replaced on a request. 2. **replacementString**: this field is used to set JMeter Functions, or even literals to be used on the comparison of the replacement match value (if value is not ignored). 3. **ignore value**: this check will determine if the match will be compared against all the JMeter Variables or even the execution of a function that can be declared on the `replacementString` field. When is checked, it will replace without comparing. -> Below is shown all the possible scenarios. Each scenario contains an *Objective* which will explain the problem we want to achieve. *Pre-loaded variables* will set us in a current variable context, in consideration of generating those variables is mandatory to read the section [variable-generation](#variable-generation). *Context* will provide all necessary information for the scenario, as a global configuration will work under the domain `www.my-market-place.com`. The *Visualization* will show the configuration made on the replacement in order to achieve the desired result. +> Below is shown all the possible scenarios. Each scenario contains an _Objective_ which will explain the problem we want to achieve. _Pre-loaded variables_ will set us in a current variable context, in consideration of generating those variables is mandatory to read the section [variable-generation](#variable-generation). _Context_ will provide all necessary information for the scenario, as a global configuration will work under the domain `www.my-market-place.com`. The _Visualization_ will show the configuration made on the replacement in order to achieve the desired result. ### Replace single parameter for a variable in request + | | Description | -|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Objective | replace a parameter of a request for a JMeter Variable. | | Pre-loaded variables | `ID` = 2 | | Context | Request is `/cart.html?product_id=2` | @@ -349,44 +354,48 @@ Now that we have a basic idea of a replacement, lets explain the most complex an | Replacement result | `www.my-market-place.com/cart.html?product_id=${ID}` | ### Replace multiple parameters for variables in request + | | Description | -|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Objective | replace multiple parameters of a request for JMeter Variables. | -| Pre-loaded variables | `ID_1` = 2, `ID_2` = 3, `ID_3` = 4, `ID_SESSION` = rP/tHk | +| Pre-loaded variables | `ID_1` = 2, `ID_2` = 3, `ID_3` = 4, `ID_SESSION` = rP/tHk | | Context | Request is `/cart.html?product_id=2&product_id=4` | -| Visualization | ![multiple_parameter_replacement](./assets/multiple-parameter-replacement.png) | +| Visualization | ![multiple_parameter_replacement](./assets/multiple-parameter-replacement.png) | | Overall | For this multi replacement, the regex will match twice (two appearances of `product_id`), therefore, each matched value will be replaced for the variables containing same value. | | Replacement result | `www.my-market-place.com/cart.html?product_id=${ID_1}&product_id=${ID_3}` | ### Replace a parameter for the result of a variable transformation in request + | | Description | -|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Objective | replace a parameter in request that uses a pre-loaded variable but transformed. | -| Pre-loaded variables | `ID` = 2, `ID_SESSION` = rP/tHk | -| Context | Request is `/index.html?session=rP%2FtHk%3CtsR%21v%3E`. In this particular case, the session id is extracted decoded (*ID_SESSION* value) , but on the request it is encoded. Therefore, the stored variable will be different to the matched value on the request. Because of that, we need to use the field `replacementString` in order to make that transformation. For this example we are using a JMeter Function called [urlencode](https://jmeter.apache.org/usermanual/functions.html#__urlencode) | -| Visualization | ![single-transformed-replacement](./assets/single-transformed-replacement.png) | +| Pre-loaded variables | `ID` = 2, `ID_SESSION` = rP/tHk | +| Context | Request is `/index.html?session=rP%2FtHk%3CtsR%21v%3E`. In this particular case, the session id is extracted decoded (_ID_SESSION_ value) , but on the request it is encoded. Therefore, the stored variable will be different to the matched value on the request. Because of that, we need to use the field `replacementString` in order to make that transformation. For this example we are using a JMeter Function called [urlencode](https://jmeter.apache.org/usermanual/functions.html#__urlencode) | +| Visualization | ![single-transformed-replacement](./assets/single-transformed-replacement.png) | | Overall | Since the replacement string is not empty, the plugin will execute (if executable, could also be a literal) the content. The result of the execution will be used to compare against the regex replacement matched value. When those values match, the replacement is made by placing the content of replacementString on the request. | | Replacement result | `www.my-market-place.com/index.html?session=${__urlencode(${ID_SESSION})}` | ### Replace multiple parameters for the result of a variable transformation in request -| | Description | -|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Objective | replace a parameter in request that uses pre-loaded variables but transformed. | -| Pre-loaded variables | `prod_1=red car`, `prod_2=blue car` | -| Context | Request is `delete.html?identifier=red+car&indetifier=blue+car`. In this case, we have to replace two parameters of the request. The value that will be placed on the request, needs to be encoded. Since the pre-loaded variables are not encoded, we need to make a transformation | -| Visualization | ![multiple-transformed-replacement](./assets/multiple-transformed-replacement.png) | -| Overall | Similar to the previous scenario, in order to proper replace for variables, we have to make a transformation, that will be done by calling the [__urlencode](https://jmeter.apache.org/usermanual/functions.html#__urlencod) function provided by JMeter. Since the pre-loaded variables are result of a multiple extraction. The replacement string will have the variable name without the suffix. The plugin automatically will detect that and it will access to all the stored values for that reference variable name. | -| Replacement result | `www.my-market-place.com/index.html?identifier=${__urlencode(${prod_1})}&identifier=${__urlencode(${prod_2})}` | + +| | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Objective | replace a parameter in request that uses pre-loaded variables but transformed. | +| Pre-loaded variables | `prod_1=red car`, `prod_2=blue car` | +| Context | Request is `delete.html?identifier=red+car&indetifier=blue+car`. In this case, we have to replace two parameters of the request. The value that will be placed on the request, needs to be encoded. Since the pre-loaded variables are not encoded, we need to make a transformation | +| Visualization | ![multiple-transformed-replacement](./assets/multiple-transformed-replacement.png) | +| Overall | Similar to the previous scenario, in order to proper replace for variables, we have to make a transformation, that will be done by calling the [\_\_urlencode](https://jmeter.apache.org/usermanual/functions.html#__urlencod) function provided by JMeter. Since the pre-loaded variables are result of a multiple extraction. The replacement string will have the variable name without the suffix. The plugin automatically will detect that and it will access to all the stored values for that reference variable name. | +| Replacement result | `www.my-market-place.com/index.html?identifier=${__urlencode(${prod_1})}&identifier=${__urlencode(${prod_2})}` | ### Replace single parameter ignoring matched value -| | Description | -|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Objective | replace a parameter in request that uses pre-loaded variables but transformed. | -| Pre-loaded variables | No variables used for this case | -| Context | Request is `/main.html?time=1516540541624`. This request contains a parameter which is the current time in milliseconds, therefore, if we had that value stored in a variable it will not work, since we need to set a request with the current time. Therefore we will use the function [__time()](https://jmeter.apache.org/usermanual/functions.html#__time) provided by JMeter | -| Visualization | ![ignore_value_replacement](./assets/ignore-value-replacement.png) | -| Overall | It is not possible to compare values in order to achieve our objective, therefore we need to set the current time neglecting the previous value. For that reason the ignore value is checked, it will not execute and compare the replacement string content. | -| Replacement result | `www.my-market-place.com/main.html?time=${__time()}` | + +| | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Objective | replace a parameter in request that uses pre-loaded variables but transformed. | +| Pre-loaded variables | No variables used for this case | +| Context | Request is `/main.html?time=1516540541624`. This request contains a parameter which is the current time in milliseconds, therefore, if we had that value stored in a variable it will not work, since we need to set a request with the current time. Therefore we will use the function [\_\_time()](https://jmeter.apache.org/usermanual/functions.html#__time) provided by JMeter | +| Visualization | ![ignore_value_replacement](./assets/ignore-value-replacement.png) | +| Overall | It is not possible to compare values in order to achieve our objective, therefore we need to set the current time neglecting the previous value. For that reason the ignore value is checked, it will not execute and compare the replacement string content. | +| Replacement result | `www.my-market-place.com/main.html?time=${__time()}` | ## List of Correlation Replacements @@ -396,19 +405,19 @@ In case none of the following Replacements fits the desired behavior your applic **Regex** -Similarly to the *Regex Correlation Extractor*, this one also receives a Regular Expression in order to find where the stored value is going to be replaced. Additionally, if a regex extractor with multivalued was added, the replacement will be applied automatically. It will look for a variable with same value as the request match in order to make the replacement. In short, no need to configure replacement to work with a multi-value or single-value. +Similarly to the _Regex Correlation Extractor_, this one also receives a Regular Expression in order to find where the stored value is going to be replaced. Additionally, if a regex extractor with multivalued was added, the replacement will be applied automatically. It will look for a variable with same value as the request match in order to make the replacement. In short, no need to configure replacement to work with a multi-value or single-value. ![Regex Correlation Replacement](./assets/regex-correlation-replacement.png) **JSON** -Similarly to the *JSON Correlation Extractor*, this one also receives a JSONPath Expression in order to find where the stored value is going to be replaced. Additionally, if a JSONPath extractor with multivalued was added, the replacement will be applied automatically. It will look for a variable with same value as the request match in order to make the replacement. In short, no need to configure replacement to work with a multi-value or single-value. +Similarly to the _JSON Correlation Extractor_, this one also receives a JSONPath Expression in order to find where the stored value is going to be replaced. Additionally, if a JSONPath extractor with multivalued was added, the replacement will be applied automatically. It will look for a variable with same value as the request match in order to make the replacement. In short, no need to configure replacement to work with a multi-value or single-value. ![JSON Correlation Replacement](./assets/json-correlation-replacement.png) -For examples of using JSONPath expressions, refer to the *JSON Correlation Extractor* documentation. +For examples of using JSONPath expressions, refer to the _JSON Correlation Extractor_ documentation. -The logic behind **Replacement string** and **Ignore value** is the same as *Regex Correlation Replacement*. Go to the documentation related to **Variable Replacement** for usage examples. +The logic behind **Replacement string** and **Ignore value** is the same as _Regex Correlation Replacement_. Go to the documentation related to **Variable Replacement** for usage examples. **Siebel Counter** @@ -416,8 +425,8 @@ This Correlation Replacement replaced the matched regex with a counter that hold **Siebel Row Id** -This replacement adds *_rowId* to the Reference Variable name before each replacement, and search the value of the regex on rows of the Siebel Context. After this, it behaves like a regular RegEx Replacement using the Siebel Context +This replacement adds _\_rowId_ to the Reference Variable name before each replacement, and search the value of the regex on rows of the Siebel Context. After this, it behaves like a regular RegEx Replacement using the Siebel Context **SiebelRowParams** -Similarly to the rest of the Correlation that involves Regex, this Replacement will receive a Regular Expression as param, its going to search for the first occurrence of the first group of (), inside the Siebel Context values, extracted previously by the SiebelRow's CorrelationExtractor, and replace the respective value following the formula `RefVar` + _ + `RowNumber`. +Similarly to the rest of the Correlation that involves Regex, this Replacement will receive a Regular Expression as param, its going to search for the first occurrence of the first group of (), inside the Siebel Context values, extracted previously by the SiebelRow's CorrelationExtractor, and replace the respective value following the formula `RefVar` + \_ + `RowNumber`. diff --git a/docs/src/guide/custom-extensions/README.md b/docs/src/guide/custom-extensions/README.md index ad91ea5..7f127d2 100644 --- a/docs/src/guide/custom-extensions/README.md +++ b/docs/src/guide/custom-extensions/README.md @@ -19,9 +19,9 @@ These are the minimum requisites that you will need to start: ## Dependencies Before we begin with the elements that are required to create a Correlation Extension, we need to -add the Correlation Recorder as dependency. To do that, you need to add the following to your pom.xml: +add the Auto Correlation Recorder as dependency. To do that, you need to add the following to your pom.xml: -1. The Correlation Recorder dependency +1. The Auto Correlation Recorder dependency 2. The JMeter dependency An example of a basic pom.xml file would be: @@ -190,4 +190,4 @@ Review these links for a further understanding of correlating concepts and examp * [Siebel's Custom Extension explained](siebel_extension_explanations.md): an explanation of Siebel CRM’s Custom Extension. * [Extensions and useful methods in the Flow](the_flow_explanation.md): detailed explanation of how correlation works. -* [Examples](https://github.com/Blazemeter/CorrelationRecorder/tree/master/examples): basic structure for a Correlation Extension. \ No newline at end of file +* [Examples](https://github.com/Blazemeter/CorrelationRecorder/tree/master/examples): basic structure for a Correlation Extension. diff --git a/docs/src/guide/custom-extensions/custom-extensions.md b/docs/src/guide/custom-extensions/custom-extensions.md index ca96317..6291f6f 100644 --- a/docs/src/guide/custom-extensions/custom-extensions.md +++ b/docs/src/guide/custom-extensions/custom-extensions.md @@ -19,9 +19,9 @@ These are the minimum requisites that you will need to start: # Correlation Rule Structure Before we begin with the elements that are required to create a Correlation Extension, we need to - add the Correlation Recorder as dependency. To do that, you need to add the following to your pom.xml: + add the Auto Correlation Recorder as dependency. To do that, you need to add the following to your pom.xml: -1. The Correlation Recorder dependency +1. The Auto Correlation Recorder dependency 2. The JMeter dependency An example of a basic pom.xml file would be: @@ -190,4 +190,4 @@ Review these links for a further understanding of correlating concepts and examp * [Siebel's Custom Extension explained](siebel_extension_explanations.md): an explanation of Siebel CRM’s Custom Extension. * [Extensions and useful methods in the Flow](the_flow_explanation.md): detailed explanation of how correlation works. -* [Examples](https://github.com/Blazemeter/CorrelationRecorder/tree/master/examples): basic structure for a Correlation Extension. \ No newline at end of file +* [Examples](https://github.com/Blazemeter/CorrelationRecorder/tree/master/examples): basic structure for a Correlation Extension. diff --git a/docs/src/guide/custom-extensions/siebel_extension_explanations.md b/docs/src/guide/custom-extensions/siebel_extension_explanations.md index b3025e3..38e5577 100644 --- a/docs/src/guide/custom-extensions/siebel_extension_explanations.md +++ b/docs/src/guide/custom-extensions/siebel_extension_explanations.md @@ -18,13 +18,13 @@ While the user is moving from one point of the page to another, some data is sen Those values don’t come in a format that will allow you to correlate them easily because they may vary on position, on the way they are formed, even by the separator and the values represented in them. -Because of this, the default core tooling that comes with the Correlation Recorder Plugin needed to be customized, allowing the users: +Because of this, the default core tooling that comes with the Auto Correlation Recorder Plugin needed to be customized, allowing the users: * To stop using complex scripts at the start of recording to correlate those values * To ease the customization of the Correlation Rules when using this protocol Reduce the boilerplate to test each one of their scenarios. -In the following sections, we will talk on how the Correlation Recorder handles the customization of the default set of Correlation Extractors and Correlation Replacements (Correlation Components, for short) in order to tackle the complexity of correlating dynamic data inside a Siebel CRM environment. +In the following sections, we will talk on how the Auto Correlation Recorder handles the customization of the default set of Correlation Extractors and Correlation Replacements (Correlation Components, for short) in order to tackle the complexity of correlating dynamic data inside a Siebel CRM environment. ## Structure of the extension diff --git a/docs/src/guide/custom-extensions/the_flow_explanation.md b/docs/src/guide/custom-extensions/the_flow_explanation.md index c6c5317..55ce28f 100644 --- a/docs/src/guide/custom-extensions/the_flow_explanation.md +++ b/docs/src/guide/custom-extensions/the_flow_explanation.md @@ -25,7 +25,7 @@ Now, on a detailed point of view, let's talk about each one of the steps of proc ### Proxy #### Deliver Recorded Sampler -For the Correlation Recorder Plugin, the Proxy is handled by `CorrelationProxyControl.java`, who receives an HTTPSamplerBase (the recorded Sampler), and the SampleResult (the request and the response), process and sends it to the CorrelationEngine to be processed. +For the Auto Correlation Recorder Plugin, the Proxy is handled by `CorrelationProxyControl.java`, who receives an HTTPSamplerBase (the recorded Sampler), and the SampleResult (the request and the response), process and sends it to the CorrelationEngine to be processed. All that occurs in the deliverSampler method. diff --git a/docs/src/guide/installation-configuration.md b/docs/src/guide/installation-configuration.md index 18e21b5..ee34f6c 100644 --- a/docs/src/guide/installation-configuration.md +++ b/docs/src/guide/installation-configuration.md @@ -6,31 +6,31 @@ prev: /guide/ # Installation and Configuration Guide -This guide will walk you through the process of installing the Correlation Recorder plugin for JMeter. - It's quick and easy, but you will need to make sure you have a few prerequisites before you start. +This guide will walk you through the process of installing the Auto Correlation Recorder plugin for JMeter. +It's quick and easy, but you will need to make sure you have a few prerequisites before you start. ## Prerequisites 1. **JMeter**: If you haven't done so already, download and install JMeter. You can find the latest version of - JMeter [here](https://jmeter.apache.org/download_jmeter.cgi). + JMeter [here](https://jmeter.apache.org/download_jmeter.cgi). 2. **JMeter Plugins Manager**: Ensure that you have installed the JMeter Plugins Manager before installing - the Correlation Recorder plugin. Learn how to install it in [this article.](https://jmeter-plugins.org/install/Install/) + the Auto Correlation Recorder plugin. Learn how to install it in [this article.](https://jmeter-plugins.org/install/Install/) ## Installation Follow these steps for an automatic installation of the latest version: 1. Launch **JMeter** and open the **JMeter Plugins Manager**. -2. In the Available Plugins tab, search and select "**BlazeMeter - Correlation Recorder Plugin**". +2. In the Available Plugins tab, search and select "**BlazeMeter - Auto Correlation Recorder Plugin**". 3. Click the "**Apply Changes and Restart JMeter**" button and wait for the installation process to complete. -Once JMeter restarts, the Correlation Recorder plugin will be installed. You can verify this by opening the - Plugins Manager and checking the Installed Plugins tab. +Once JMeter restarts, the Auto Correlation Recorder plugin will be installed. You can verify this by opening the +Plugins Manager and checking the Installed Plugins tab. ## Configuration Before we jump right into recording, let's take a look at the basic configuration options available for the - Correlation Recorder plugin. +Auto Correlation Recorder plugin. ### Local configurations @@ -44,20 +44,17 @@ Before we jump right into recording, let's take a look at the basic configuratio _If you have already configured the local proxy, you can skip this section._ We need to configure the _local proxy_, otherwise, **you will not be able to record - any requests**. To do so, take a look at the "Configure your browser to use the JMeter Proxy" section in the - [JMeter documentation](https://jmeter.apache.org/usermanual/jmeter_proxy_step_by_step.pdf). +any requests**. To do so, take a look at the "Configure your browser to use the JMeter Proxy" section in the +[JMeter documentation](https://jmeter.apache.org/usermanual/jmeter_proxy_step_by_step.pdf). ::: warning If the server you are recording is running in your local machine, you will need to configure your browser to - allow recording of local requests. +allow recording of local requests. In such case, you will need to search for "How to configure the JMeter proxy to record local requests" and follow - the instructions for your browser. +the instructions for your browser. In **Firefox**, for instance, go to `about:config` and set `network.proxy.allow_hijacking_localhost` to true. ::: After this, you should be able to start recording. - - - diff --git a/docs/src/guide/installation-guide.md b/docs/src/guide/installation-guide.md index 8e4ac25..4b9bdfb 100644 --- a/docs/src/guide/installation-guide.md +++ b/docs/src/guide/installation-guide.md @@ -19,7 +19,7 @@ Before attempting to install the plugin, make sure you have the following prereq 1. **JMeter**: If you haven't done so already, download and install JMeter. You can find the latest version of JMeter [here](https://jmeter.apache.org/download_jmeter.cgi). 2. **JMeter Plugins Manager**: Ensure that you have installed the JMeter Plugins Manager before installing - the Correlation Recorder plugin. Learn how to install it in [this article.](https://jmeter-plugins.org/install/Install/) + the Auto Correlation Recorder plugin. Learn how to install it in [this article.](https://jmeter-plugins.org/install/Install/) These two downloads are all you need to get started. @@ -28,7 +28,7 @@ These two downloads are all you need to get started. If you want to use the plugin with BlazeMeter, you will also need to have the following: 1. A BlazeMeter account. If you don't have one, you can [sign up for free](https://accounts.blazemeter.com/). -2. A BlazeMeter api-key. If you don't have one, you can learn how to generate it from this article [BlazeMeter Api Key](https://guide.blazemeter.com/hc/en-us/articles/13329040973073-BlazeMeter-API-keys-). +1. A BlazeMeter api-key. If you don't have one, you can learn how to generate it from this article [BlazeMeter Api Key](https://guide.blazemeter.com/hc/en-us/articles/13329040973073-BlazeMeter-API-keys-). ## Installation @@ -38,33 +38,33 @@ you can also do it manually. This section will cover both methods. ### With Plugin Manager 1. Launch **JMeter** and open the **JMeter Plugins Manager**. -2. In the Available Plugins tab, search and select "**BlazeMeter - Correlation Recorder Plugin**". -3. Click the "**Apply Changes and Restart JMeter**" button and wait for the installation process to complete. +1. In the Available Plugins tab, search and select "**BlazeMeter - Auto Correlation Recorder Plugin**". +1. Click the "**Apply Changes and Restart JMeter**" button and wait for the installation process to complete. -Once JMeter restarts, the Correlation Recorder plugin will be installed. +Once JMeter restarts, the Auto Correlation Recorder plugin will be installed. ### Manually -1. Go to the [Correlation Recorder plugin page](https://jmeter-plugins.org/?search=BlazeMeter%20-%20Correlation%20Recorder%20Plugin) and download the +1. Go to the [Auto Correlation Recorder plugin page](https://jmeter-plugins.org/?search=BlazeMeter%20-%20Correlation%20Recorder%20Plugin) and download the latest version of the plugin, with the dependencies. -2. Place the Plugin jar in the ext folder of your JMeter installation. The ext folder is usually located in +1. Place the Plugin jar in the ext folder of your JMeter installation. The ext folder is usually located in `/lib/ext`. -3. Place the dependencies jars in the lib folder of your JMeter installation. The lib folder is usually located in +1. Place the dependencies jars in the lib folder of your JMeter installation. The lib folder is usually located in `/lib`. -4. Restart JMeter. +1. Restart JMeter. ## Verifying You can verify the plugin being installed by opening the Plugins Manager and checking the Installed Plugins tab. Search for -the Correlation Recorder plugin and make sure it is listed there. +the Auto Correlation Recorder plugin and make sure it is listed there. -Another way to ensure the plugin is properly installed, is by attempting to load the Correlation Recorder template. To do so, +Another way to ensure the plugin is properly installed, is by attempting to load the Auto Correlation Recorder template. To do so, follow these steps: 1. Launch **JMeter** and open the **File** menu. -2. Select the **Templates** option and then click on **Load**. -3. Search for the **Correlation Recorder** template and click on **Open**. -4. If the template loads successfully, the plugin is properly installed. +1. Select the **Templates** option and then click on **Load**. +1. Search for the **Auto Correlation Recorder** template and click on **Open**. +1. If the template loads successfully, the plugin is properly installed. ## Updating @@ -78,18 +78,18 @@ In case there is a new version of the plugin, the name of the extension will be If you want to uninstall the plugin, you can do so by following these steps: 1. Launch **JMeter** and open the **JMeter Plugins Manager**. -2. In the Installed Plugins tab, search and select "**BlazeMeter - Correlation Recorder Plugin**". -3. Uncheck the plugin and click the "**Apply Changes and Restart JMeter**" button. -4. Wait for the uninstallation process to complete. -5. Restart JMeter. +1. In the Installed Plugins tab, search and select "**BlazeMeter - Auto Correlation Recorder Plugin**". +1. Uncheck the plugin and click the "**Apply Changes and Restart JMeter**" button. +1. Wait for the uninstallation process to complete. +1. Restart JMeter. ## Configuration -Before we jump right into recording, let's take a look at the basic configuration options available for the Correlation Recorder plugin. +Before we jump right into recording, let's take a look at the basic configuration options available for the Auto Correlation Recorder plugin. ### Properties -Here is a list of properties that you need to configure in order to use the Correlation Recorder plugin: +Here is a list of properties that you need to configure in order to use the Auto Correlation Recorder plugin: 1. Disable redirect disabling: Set the `proxy.redirect.disabling` property to false in your `user.properties` file. This is required for a proper and automatic correlation experience. @@ -145,41 +145,41 @@ JMeter and configure your web browser to use that proxy. #### 1. **Configure JMeter Proxy** 1. Open JMeter and create a new Test Plan. -2. Right-click on the Test Plan and select "Add" > "Threads (Users)" > "Thread Group". -3. Right-click on the Thread Group and select "Add" > "Logic Controller" > "Recording Controller". -4. Right-click on the Recording Controller and select "Add" > "Sampler" > "HTTP(S) Test Script Recorder". -5. In the HTTP(S) Test Script Recorder, click on the "Start" button to start the proxy server. -6. Click on the "HTTP(S) Test Script Recorder" element in the tree view and configure the following settings: -7. Set the "Target Controller" to the Recording Controller you created in step 3. -8. Set the "Port" to an available port (e.g. 8888). -9. Set the "Grouping" to "Put each group in a new transaction controller". -10. Click on the "SSL Manager" button and create a new SSL certificate. +1. Right-click on the Test Plan and select "Add" > "Threads (Users)" > "Thread Group". +1. Right-click on the Thread Group and select "Add" > "Logic Controller" > "Recording Controller". +1. Right-click on the Recording Controller and select "Add" > "Sampler" > "HTTP(S) Test Script Recorder". +1. In the HTTP(S) Test Script Recorder, click on the "Start" button to start the proxy server. +1. Click on the "HTTP(S) Test Script Recorder" element in the tree view and configure the following settings: +1. Set the "Target Controller" to the Recording Controller you created in step 3. +1. Set the "Port" to an available port (e.g. 8888). +1. Set the "Grouping" to "Put each group in a new transaction controller". +1. Click on the "SSL Manager" button and create a new SSL certificate. #### **2. Configure Web Browser** 1. Open Chrome/Firefox/Opera and go to the settings menu. -2. Search for "proxy" or "network settings". -3. Under the "Proxy" section, select "Manual proxy configuration". -4. In the "HTTP Proxy" field, enter "localhost" and the port number you set in step 6 of the JMeter configuration (e.g. 8888). -5. Click on the "OK" button to save the settings. +1. Search for "proxy" or "network settings". +1. Under the "Proxy" section, select "Manual proxy configuration". +1. In the "HTTP Proxy" field, enter "localhost" and the port number you set in step 6 of the JMeter configuration (e.g. 8888). +1. Click on the "OK" button to save the settings. #### **3. Record Traffic** 1. In JMeter, click on the "Start" button in the HTTP(S) Test Script Recorder to start recording. -2. In your web browser, navigate to the website you want to record. -3. Perform the actions you want to record (e.g. filling out forms, clicking links). -4. In JMeter, click on the "Stop" button to stop recording. +1. In your web browser, navigate to the website you want to record. +1. Perform the actions you want to record (e.g. filling out forms, clicking links). +1. In JMeter, click on the "Stop" button to stop recording. #### macOS ##### 1. **Configure JMeter Proxy** 1. Open JMeter and create a new Test Plan. -2. Right-click on the Test Plan and select "Add" > "Threads (Users)" > "Thread Group". -3. Right-click on the Thread Group and select "Add" > "Logic Controller" > "Recording Controller". -4. Right-click on the Recording Controller and select "Add" > "Sampler" > "HTTP(S) Test Script Recorder". -5. In the HTTP(S) Test Script Recorder, click on the "Start" button to start the proxy server. -6. Click on the "HTTP(S) Test Script Recorder" element in the tree view and configure the following settings: +1. Right-click on the Test Plan and select "Add" > "Threads (Users)" > "Thread Group". +1. Right-click on the Thread Group and select "Add" > "Logic Controller" > "Recording Controller". +1. Right-click on the Recording Controller and select "Add" > "Sampler" > "HTTP(S) Test Script Recorder". +1. In the HTTP(S) Test Script Recorder, click on the "Start" button to start the proxy server. +1. Click on the "HTTP(S) Test Script Recorder" element in the tree view and configure the following settings: - Set the "Target Controller" to the Recording Controller you created in step 3. - Set the "Port" to an available port (e.g. 8888). diff --git a/docs/src/guide/knonw-issues.md b/docs/src/guide/knonw-issues.md index 1eb3cb3..63199db 100644 --- a/docs/src/guide/knonw-issues.md +++ b/docs/src/guide/knonw-issues.md @@ -3,13 +3,15 @@ This section contains a list of known issues and workarounds. ## 1. Correlation History is isolated + After a recording or a correlation process is done and, the Test Plan is saved, if you open it again, - the Correlation History of that "session" is not associated to the Test Plan anymore. This impacts the correlation - process, as there is no Original Recording JMX or JTL associated to the Correlation History for the "current" session. +the Correlation History of that "session" is not associated to the Test Plan anymore. This impacts the correlation +process, as there is no Original Recording JMX or JTL associated to the Correlation History for the "current" session. ### Workaround: Manually feeding the files to the Correlation Process -#### Correlating by Correlation Template +#### Correlating by Correlation Template + 1. You need to open the correlation history JSON file stored at `jmeter/bin/History/` 2. Take the path of the `recordingTraceFilepath` in the `Original Recording` step. 3. Use that path in the JTL file selector in the "Select Correlation Template" window. @@ -17,30 +19,34 @@ After a recording or a correlation process is done and, the Test Plan is saved, This will enforce the use of the JTL file you want to use for the correlation process for that "session". #### Correlating by Replay and Comparison + Take the steps from the previous section, but instead of feeding the JTL file to the JTL file selector, - set it as the JTL file in the View result tree for the "bzm - Correlation Recorder" sampler. +set it as the JTL file in the View result tree for the "bzm - Auto Correlation Recorder" sampler. This will use the back method of the Correlating by Replay and Comparison method of using that auxiliary JTL file to - perform the correlation process. - +perform the correlation process. ## 2. Manual Replay Correlation Analysis Issue After Choosing 'No' to Wizard Prompt + We are aware that there is an issue where, if you click "No" when the Automatic Correlation Wizard offers - to generate suggestions after recording, manually opening the wizard, replaying, and selecting the Correlation - method may not trigger the analysis. +to generate suggestions after recording, manually opening the wizard, replaying, and selecting the Correlation +method may not trigger the analysis. We recommend selecting "Yes" when the wizard prompts you to generate suggestions to avoid this issue. -## 3. GUI crash and console error logging null pointer. +## 3. GUI crash and console error logging null pointer. + We have identified an issue with java 1.8 primarily happening on macOS when using this plugin. - We have fixed the issue in the table renderer, but there can still be some cases where this might happen. - In case you are getting a GUI crash and null pointer references in jmeter console, you might want to consider - upgrading java version. +We have fixed the issue in the table renderer, but there can still be some cases where this might happen. +In case you are getting a GUI crash and null pointer references in jmeter console, you might want to consider +upgrading java version. If you are getting this error or a similar one: -``` - java.lang.NullPointerException: null + +``` + java.lang.NullPointerException: null at com.blazemeter.jmeter.correlation.gui.RulesTableGui$CustomCellRenderer.getTableCellRendererComponent(RulesTableGui.java:178) ~[jmeter-bzm-correlation-recorder-2.2.1.jar:?] at javax.swing.JTable$AccessibleJTable.getAccessibleChild(JTable.java:7037) ~[?:1.8.0_345] ``` -We recommend using java 11 or higher. \ No newline at end of file + +We recommend using java 11 or higher. diff --git a/docs/src/guide/templates/create.md b/docs/src/guide/templates/create.md index c2575b0..882eced 100644 --- a/docs/src/guide/templates/create.md +++ b/docs/src/guide/templates/create.md @@ -36,7 +36,7 @@ If you have Correlation Suggestions generated from your Test Plan, you can expor To do so, you need to: 1. Make a Recording and generate Correlation Suggestions (by any method) -2. Click on the "Export Suggestions" button in the Correlation Recorder Plugin +2. Click on the "Export Suggestions" button in the Auto Correlation Recorder Plugin 3. Select the Rules you want to save as a Template (eliminate the rest) 4. Click on "Save Template" and fill in the required fields 5. Click on "Save" @@ -47,4 +47,4 @@ Note: If you are generating Suggestions from a Template that you have access to Another way to create a Template is by loading different Templates into the Plugin and manually editing them to fit your use case. This is useful when you want to combine different Templates into a single one or when you want to create a Template from scratch. When you are done editing the Template, you can save it as a new one. -The Correlation Recorder Plugin do not keep track of the Templates you load, except from the last one, so you need to make sure you save them in the proper Repository. \ No newline at end of file +The Auto Correlation Recorder Plugin do not keep track of the Templates you load, except from the last one, so you need to make sure you save them in the proper Repository. diff --git a/docs/src/guide/templates/readme.md b/docs/src/guide/templates/readme.md index b9759a7..4c685ea 100644 --- a/docs/src/guide/templates/readme.md +++ b/docs/src/guide/templates/readme.md @@ -4,7 +4,7 @@ next: /guide/templates/create.md # Correlation Templates -The Templates are part of the core functionalities of the Correlation Recorder Plugin. They are the structure that groups a set of Correlation Rules inside the Plugin for various uses. +The Templates are part of the core functionalities of the Auto Correlation Recorder Plugin. They are the structure that groups a set of Correlation Rules inside the Plugin for various uses. In this section, you will learn about: @@ -15,7 +15,7 @@ In this section, you will learn about: ## Definitions -A Correlation Template, or a Template for shorts, is the structure used to group a set of Correlation Rules inside the Correlation Recorder Plugin for different purposes, such as: +A Correlation Template, or a Template for shorts, is the structure used to group a set of Correlation Rules inside the Auto Correlation Recorder Plugin for different purposes, such as: * Sharing with coworkers * Analyzing the recordings @@ -99,7 +99,7 @@ When you load a Template to the Plugin, you manually edit the configurations the To load a Template to the Plugin, you must: -1. Load the Correlation Recorder Plugin +1. Load the Auto Correlation Recorder Plugin 2. Click on the "Load Template" button 3. Select the Template from the list of Installed and Available (*) 4. Click on the "Load" button @@ -117,7 +117,7 @@ To keep your local Repository up to date, please remember to click the "Refresh" If anyone gave you the JSON file related to a Template, you could import it into your local Repository by adding the file to your `correlation-template` folder, located in `/bin/.` after that, you force a manual sync so the Plugin to index it as local. ### Delete Templates -Currently, the Correlation Recorder Plugin does not support Deleting Templates, neither from your local Repository nor any other external repository. +Currently, the Auto Correlation Recorder Plugin does not support Deleting Templates, neither from your local Repository nor any other external repository. You can delete your local repository Templates by manually deleting the correlation-templates folder in the bin folder inside your JMeter installation folder; however, this is not advisable, and you must do it at your own risk. @@ -137,4 +137,4 @@ Always sync your repositories before analyzing your recordings to have the lates There are some limitations when using Templates: 1. You can't edit BlazeMeter built-in Enterprise Templates -2. You can't overwrite versions of any Template (regardless of the type) \ No newline at end of file +2. You can't overwrite versions of any Template (regardless of the type) diff --git a/docs/src/guide/troubleshooting.md b/docs/src/guide/troubleshooting.md index 8fd86f0..50a9059 100644 --- a/docs/src/guide/troubleshooting.md +++ b/docs/src/guide/troubleshooting.md @@ -6,11 +6,12 @@ prev: /guide/best-practices.md # Troubleshooting In this section you will find information about: + - [Common issues and solutions](#common-issues-and-solutions) - [Debugging tips](#debugging-tips) - [FAQ](#faq) -Most of these issues, if not all, can be solved by: +Most of these issues, if not all, can be solved by: - Ensuring your plugin is appropriately [configured](/guide/installation-guide.html#configuration) - Ensuring that your Test Plan aligns [consistently with the recording](#the-replay-is-not-consistent-with-the-recording). @@ -49,7 +50,8 @@ The most common debugging tips are: - Alternatively, the opposite is also possible: add all the elements to the Test Plan, in cases where you might end up filtering requests that could contain important information for the correlation. This does not occur that often with the default filters added to the template, but if you find yourself simply unable to locate a value (neither in the recording nor the replay), it could be possible that it was filtered. ## How to properly report an issue -If by the end of the debugging process you are still not able to find the root cause of the issue, you can always + +If by the end of the debugging process you are still not able to find the root cause of the issue, you can always request help. We encourage you ask for help in the following ways: 1. **Prepare the information following the steps in the next section** @@ -57,10 +59,12 @@ request help. We encourage you ask for help in the following ways: 3. Alternatively, you can create an issue in the [GitHub repository](https://github.com/Blazemeter/CorrelationRecorder/issues) of the plugin, and get assistance by the Open source community. ### How to prepare the information + In order to properly report an issue, we need to have as much information as possible. This is why we encourage you to follow the next steps: #### Gather system information + Make sure to include relevant information about your system and environment, such as: Operating system (e.g. Windows, macOS, Linux) @@ -68,34 +72,38 @@ Browser and version (if applicable) Java version (if applicable) Other relevant software versions - #### Describe the issue + Provide a clear and concise description of the issue you are experiencing. Include any error messages or unexpected behavior that you have observed. #### Steps to reproduce + Provide a step-by-step guide to reproduce the issue. Include any relevant information, such as the test scenario you were running, the specific action you were performing, or the data you were using. #### Expected behavior + Describe what you expected to happen when performing the steps outlined in the previous section. #### Actual behavior + Describe what actually happened when performing the steps outlined in the previous section. #### Additional information + Include any additional information that you think might be relevant or helpful in diagnosing the issue. This could include screenshots, log files, or any other relevant details. By following these steps and providing as much detail as possible, you can help ensure that your issue is properly diagnosed and resolved. - ## Guides ### Checking your JMeter configuration + One of the many reason as why the Templates or Rules do not work is because the plugin is not properly configured. This means that the plugin might be missing critical configuration in order to work properly. Make sure you have followed the instructions in the [Installation Guide](/guide/installation-guide.html) and the [Configuration Guide](/guide/installation-guide.html#configuration) in order to properly configure the plugin. - ### Checking your Test Plan for consistency + One of the many reason as why the Templates or Rules do not work is because the Test Plan is not consistent. This means that the Test Plan is not being executed in the same way as it was recorded. This can happen for a variety of reasons, but the most common ones are: @@ -104,30 +112,27 @@ This can happen for a variety of reasons, but the most common ones are: - The Test Plan is missing elements that were present in the recording. - The Test Plan has elements that are disabled and are relevant in the recording. - ### Checking the server responses + Another common reason as why the Templates or Rules do not work is because the responses from the server are totally different from the recording. This means that the server is not responding with the same values as it was recorded. This can happen for a variety of reasons, but the most common ones are: -- The server returns a different response due to: +- The server returns a different response due to: - previous requests not being properly correlated. - the Test Plan not being consistent. - Additional configuration's required to run the Test Plan. - The server needs Javascript to be executed in order to return the correct response. - - - - ## FAQ ### The value that I need to Correlate does not appear in the Tree View -This is a pretty common issue that can affect the capabilities of you or the plugin to correlate a value. + +This is a pretty common issue that can affect the capabilities of you or the plugin to correlate a value. The most common reasons are: -1. Cookies and cached values are not being cleared before recording. +1. Cookies and cached values are not being cleared before recording. 2. Requests are being filtered on recording. Can these be fixed? Yes, they can. Here is how: @@ -138,15 +143,16 @@ The short recommendation for this problem is: **Always clear your cookies and ca **Explanation:** -If your browser has **cached values** or **cookies** from previous sessions, it is possible that the value you are trying +If your browser has **cached values** or **cookies** from previous sessions, it is possible that the value you are trying to correlate **is not being sent to JMeter** from the server (because your browser already has the value stored and -use it directly). +use it directly). This is why we always **recommend** to _clear your cookies and cached values before recording_ or _make a new Incognito session in your browser_ each time you record. #### Requests are being filtered on recording -If the Request are being filtered on recording, it is possible that the server is sending the request to JMeter, + +If the Request are being filtered on recording, it is possible that the server is sending the request to JMeter, but it is not being stored since it matches the filtering configurations. By default, these filtered request won't appear in the Recording's View Result tree. However, you can disable this @@ -160,14 +166,14 @@ Along the possible issues this can cause, the most common ones are: - The plugin will identify values in requests that is not part of the Test Plan and will make incorrect suggestions. This will give the impression of a value being correlated when it is not. - The plugin will identify the appearance of a value more times than it should. This will give the impression of a value being more important than it actually is. - The analysis (either by Templates or by Automatic detection) will take longer than usual since it will have to go through all the requests in the View Result Tree, even the ones that are not part of the Test Plan. -::: + ::: Before jumping into conclusions, let's test the hypothesis that the request is being filtered. -**Check if the request appears in the Recording JTL:** +**Check if the request appears in the Recording JTL:** -1. Go to your Test Plan -2. Click in the "bzm - Correlation Recorder" element +1. Go to your Test Plan +2. Click in the "bzm - Auto Correlation Recorder" element 3. Click the "View Results Tree" element Either manually review the list of elements or use the search field to find the request you are looking for. @@ -176,22 +182,22 @@ If the request does not appear in the recording JTL, it might have been filtered If the request is present in the recording JTL, it was not filtered. ::: tip -If the request is present in the Recording JTL but the name appears between brackets ([]), it means that the request was filtered, and you have the notify children option enabled. +If the request is present in the Recording JTL but the name appears between brackets ([]), it means that the request was filtered, and you have the notify children option enabled. ::: **Disable the filtering of requests in the Recording JTL:** If you validated that the request is being filtered, you can disable the filtering of requests in the Recording JTL by following these steps: -1. Go to the Request filtering tab (Test Plan > bzm - Correlation Recorder > Requests Filtering +1. Go to the Request filtering tab (Test Plan > bzm - Auto Correlation Recorder > Requests Filtering tab). 2. Check the "Notify Child Listeners of filtered samplers" option at the bottom of the element in the "Notify Child Listeners of filtered samplers" section. 3. Clear the recording (Test Plan > Recording Controller > Clear all the recorded samples). -4. Clear the Recording JTL (Test Plan > bzm - Correlation Recorder > View Results Tree > +4. Clear the Recording JTL (Test Plan > bzm - Auto Correlation Recorder > View Results Tree > Right Click > Clear). 5. Record again. -Now, when you check the Recording's View Result Tree, you should see all the requests that are being sent to JMeter. +Now, when you check the Recording's View Result Tree, you should see all the requests that are being sent to JMeter. The ones that are being filtered will appear between brackets ([]), while the ones that are not being filtered will appear normally (without the wrapping brackets). @@ -206,22 +212,24 @@ that the request is not being filtered. Likewise, we highly encourage you to fine tune the filtering configuration to ensure that the request is not being filtered rather than removing the filtering altogether. Having extra requests in the Recording will only make the analysis slower and suggest values that are not relevant or should not be correlated. ::: - ## Your regular expression is not matching the value you are trying to correlate + More often than not, the regular expression that you are using to correlate a value is not matching the value you are -trying to correlate. +trying to correlate. Depending on which part of the Correlation Rule you are configuring or testing, you might need to use a different mechanism to validate that the regular expression is matching the value you are trying to correlate. ### For Extraction + You can test your Regex inside JMeter by going into your Recording's View Result Tree do one of the following: 1. Search by Regular exp. 2. Use the "RegExp Tester" view. ### For Replacement -By default, the Plugin will concatenate both the `name of the argument` and `value` with `:`, when evaluating the replacement. + +By default, the Plugin will concatenate both the `name of the argument` and `value` with `:`, when evaluating the replacement. For instance: If the value you want to correlate appears in the HTTP Sampler as `wpnonce` (in name's column) and `123ABC` (in value's column), when the plugin tries to match the Regex, it will do it against `wpnonce: 123ABC`. @@ -231,6 +239,7 @@ Even if your Regex matches the value you are trying to correlate, in the request ::: ## How to confirm the value is being extracted correctly + If you are not sure if the value is being extracted correctly, you can use the "Debug Post-Processor" to confirm it. To do this, you need to: @@ -245,4 +254,4 @@ If your Regex Extractor is located inside the Request #1, the value will appear If the variable **is not present** in the Debug Sampler, it means that the **regex is not matching** any value in the recording until that point and that **you don't have a default value assigned to it**. If the variable **is present** but the **value is "NOT_FOUND"**, it means that the regex **is not matching** any value. -If the variable **is present** but the value **is not the one that you want**, it means **you need to improve** either **the Regex** or **the configuration** of the Extractor. \ No newline at end of file +If the variable **is present** but the value **is not the one that you want**, it means **you need to improve** either **the Regex** or **the configuration** of the Extractor. diff --git a/docs/src/guide/using-the-plugin.md b/docs/src/guide/using-the-plugin.md index 476c29f..e8dd1e6 100644 --- a/docs/src/guide/using-the-plugin.md +++ b/docs/src/guide/using-the-plugin.md @@ -4,7 +4,9 @@ prev: /guide/installation-guide.md --- # Usage -In this page, we will explain the most common scenario when using the Correlation Recorder plugin, here you will: + +In this page, we will explain the most common scenario when using the Auto Correlation Recorder plugin, here you will: + - Learn how to [identify dynamic parameters](/guide/using-the-plugin.html#identifying-dynamic-parameters) in your test scripts - Learn about Correlation Rules @@ -13,36 +15,37 @@ You might also be interested in other usages such as: - Storing your Rules in Correlation [Templates](/guide/correlation-templates.md) - Managing your Correlation [Repositories](/guide/correlation-repositories.md) - ## Identifying dynamic parameters -Either if you are new to the usage of JMeter or not, you will find that the Correlation Recorder plugin will help you - to identify dynamic parameters in your test scripts, as they can be hard to find. The plugin will help you to - identify them and create correlation rules for them. + +Either if you are new to the usage of JMeter or not, you will find that the Auto Correlation Recorder plugin will help you +to identify dynamic parameters in your test scripts, as they can be hard to find. The plugin will help you to +identify them and create correlation rules for them. There are three ways to properly identify dynamic parameters in your test scripts: -1. **Using the replay and compare feature**: This will replay your current test plan and obtain the parameters from - the requests that fail (those are very likely changing in each iteration), and display those for you. Correlations - will be created automatically for you. -2. **Using the correlation templates**: This will use a set of pre-defined correlation templates that have been - specifically designed for different applications. You can use them to identify dynamic parameters in your test - scripts and automatically create correlations for them. Local Correlation Templates are also supported. +1. **Using the replay and compare feature**: This will replay your current test plan and obtain the parameters from + the requests that fail (those are very likely changing in each iteration), and display those for you. Correlations + will be created automatically for you. +2. **Using the correlation templates**: This will use a set of pre-defined correlation templates that have been + specifically designed for different applications. You can use them to identify dynamic parameters in your test + scripts and automatically create correlations for them. Local Correlation Templates are also supported. 3. **Manually**: You can manually identify dynamic parameters in your test scripts, and manually correlating them. In this guide, we will focus on the first two methods, as they are the most effective ones. ## Correlation Rules -Correlation Rules are the core of the Correlation Recorder plugin. They are the ones that will help you to identify - dynamic parameters in your test scripts and correlate them. -You can create your own Rules or use the ones created by BlazeMeter or your team. +Correlation Rules are the core of the Auto Correlation Recorder plugin. They are the ones that will help you to identify +dynamic parameters in your test scripts and correlate them. + +You can create your own Rules or use the ones created by BlazeMeter or your team. You create them by yourself, there are two ways: 1. By using the [Replay and Compare](/guide/after-recording.html#by-replay-and-compare) feature 2. By creating the [Correlation Rules manually](/guide/correlation-rules.md) -The [Replay and Compare](/guide/after-recording.html#by-replay-and-compare) is a more exploratory approach, where the plugin attempts to automatically detect the dynamic values from request that failed, while [Correlation Rules manually](/guide/correlation-rules.md) is more effective, as you should know exactly what you are trying to correlate. +The [Replay and Compare](/guide/after-recording.html#by-replay-and-compare) is a more exploratory approach, where the plugin attempts to automatically detect the dynamic values from request that failed, while [Correlation Rules manually](/guide/correlation-rules.md) is more effective, as you should know exactly what you are trying to correlate. We recommend using [Replay and Compare](/guide/after-recording.html#by-replay-and-compare) to identify potential dynamic values, their appearances in both responses and requests, and general rules to correlate then, and then fine tune those rules to properly correlate them. @@ -50,12 +53,12 @@ If you are interested in using the Rules created by others, you can use the [Cor ## Validating and testing the correlation rules -Once a correlation rule has been created, you can validate it to make sure it works as expected. To do so, you +Once a correlation rule has been created, you can validate it to make sure it works as expected. To do so, you the comparison by "Correlation Rules" and "Correlation Templates" in the "Correlation Wizard" window. To do so, first, save your Correlation Rules as a Correlation Template, then, click the "Correlation Wizard" button - and select the "Correlation Templates" option. Select the template you just saved and click "Next". The plugin will - apply the Correlation Template to your recording and, by the end of the analysis, the Correlation Suggestion window will be displayed, showing you the dynamic values detected from the Correlation Template you just used. +and select the "Correlation Templates" option. Select the template you just saved and click "Next". The plugin will +apply the Correlation Template to your recording and, by the end of the analysis, the Correlation Suggestion window will be displayed, showing you the dynamic values detected from the Correlation Template you just used. ::: tip warning If you are using the "Correlation Templates" option, remember that the plugin will apply every Correlation Template @@ -67,17 +70,16 @@ values detected from all the Correlation Templates you selected (not just the la ## Applying correlation rules to test scripts Regardless of the method that was used for the creation of the Rules, the plugin will allow the appliance of - those rules in two different ways: +those rules in two different ways: 1. **[After the recording is done](/guide/using-the-plugin.html#applying-correlation-rules-after-the-recording-is-done)** (recommended) 2. **[During the recording](/guide/using-the-plugin.html#during-the-recording-legacy)** (legacy) ### Applying correlation rules after the recording is done -Since the release of the Correlation Recorder v2, we encourage the usage of this method to apply Correlation Rules, - as it is the faster and more reliable way to do so. To apply Correlation Rules after the recording is done, you - need to follow these steps: - +Since the release of the Auto Correlation Recorder v2, we encourage the usage of this method to apply Correlation Rules, +as it is the faster and more reliable way to do so. To apply Correlation Rules after the recording is done, you +need to follow these steps: #### **TL;DR** @@ -97,6 +99,7 @@ that it works as expected. 1. Open the Correlation Wizard To open the Correlation Wizard, you can either: + - Accept the replay report Dialog, after the recording. - Click on the **Correlation Wizard** button in the **Correlation** tab. @@ -128,7 +131,7 @@ If you want to know more about Enterprise Correlation Templates, please contact 4. Add the JTL file of the recording (if it isn't already loaded) -By default, the plugin loads the JTL file that is found in the View Result Tree of the "bzm - Correlation Recorder" element. +By default, the plugin loads the JTL file that is found in the View Result Tree of the "bzm - Auto Correlation Recorder" element. If you want to use a different JTL file, you can click on the "Browse" button and select the file you want to use. ::: warning @@ -159,33 +162,34 @@ The second method is still supported, but it is not recommended, as it is slower ### **During the recording** (legacy) As mentioned before, this method is not recommended when testing your Correlation Rules, as it takes more time to test - them, however, if you are sure your Correlation Rules are properly configured, the steps are pretty simple: +them, however, if you are sure your Correlation Rules are properly configured, the steps are pretty simple: -1. Select the "Enable Correlation (Legacy)" checkbox in the "bzm - Correlation Recorder" element. +1. Select the "Enable Correlation (Legacy)" checkbox in the "bzm - Auto Correlation Recorder" element. 2. Start the recording. 3. Once the recording is done, your correlations should be applied to your Test Plan. You dont need to do anything else, as the rules should be applied directly in your Test Plan. You can replay and see - the final result of your Test Plan. +the final result of your Test Plan. ::: tip warning If you enable this check box, do the recording and then attempt to apply any of the Post Recording methods, we can't - assure those will work properly, since the recording will contain elements that are already correlated or modified, - which might cause issues when identifying the dynamic values. +assure those will work properly, since the recording will contain elements that are already correlated or modified, +which might cause issues when identifying the dynamic values. ::: ## Using the History Manager -During the workflow with the Correlation Recorder, we usually record flows and then correlate messages, do tests, and investigate if we did our correlations correctly. + +During the workflow with the Auto Correlation Recorder, we usually record flows and then correlate messages, do tests, and investigate if we did our correlations correctly. To make this job easier, the history manager arises. -This tool automatically saves checkpoints after relevant situations such as applying correlations, making a reply of our saved flow or after saving our original recording. After these saves are done, we can easily restore a version of our test plan with a few clicks and analyze the steps we did. +This tool automatically saves checkpoints after relevant situations such as applying correlations, making a reply of our saved flow or after saving our original recording. After these saves are done, we can easily restore a version of our test plan with a few clicks and analyze the steps we did. ### View the History -This feature allow us to see all the iterations we did since our original recording. The date we did them and a few details. +This feature allow us to see all the iterations we did since our original recording. The date we did them and a few details. -To see the history we need to go to the Correlation Tab in the bzm-Correlation Recorder sampler and then click the Hisotry Button. +To see the history we need to go to the Correlation Tab in the bzm-Auto Correlation Recorder sampler and then click the Hisotry Button. ![History Manager Presentation](./assets/using-the-plugin-history-1.png) @@ -195,9 +199,9 @@ Once we click the history button, we will see this window ### Restore an Iteration -With this feature you are going to be able to select one iteration and restore your test plan at the point the iteration was saved. +With this feature you are going to be able to select one iteration and restore your test plan at the point the iteration was saved. -You just need to select one iteration and click the Restore button. After that you will see this message: +You just need to select one iteration and click the Restore button. After that you will see this message: ![Restore Iteration](./assets/using-the-plugin-history-3.png) @@ -212,10 +216,11 @@ You are able to delete the iterations you consider useless in your history. You With this feature you are able to save and share the whole history. When you click the esport button, a zip file will be generated into the History folder of the bin folder where you have installed Jmeter. This zip file share the bin folder structure. To see a history shared with you, you can do it from two ways: + 1. You can extract its content in another bin folder and complement folders instead of substitute them. 2. Open the zip file and copy every fil into its corresponding folder inside the bin folder. Then open the Test Plan associated with that history (usually it is shared outside the zip file) and go to the history. -![History Zip File](./assets/using-the-plugin-history-4.png) \ No newline at end of file +![History Zip File](./assets/using-the-plugin-history-4.png)