Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@tilln
tilln committed Sep 6, 2020
1 parent 04f9df5 commit 5deb78e
Show file tree
Hide file tree
Showing 2 changed files with 99 additions and 14 deletions.
113 changes: 99 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ This plugin makes JMeter behave a little more like a browser: form fields are au

![HTTP Form Manager](https://raw.githubusercontent.com/tilln/jmeter-formman/master/docs/before.png)

HTTP form POST parameters are extracted at runtime from HTML responses and added to HTTP sampler parameters
HTTP form parameters are extracted at runtime from HTML responses and added to HTTP sampler parameters
(similar to JMeter's [HTML Link Parser](http://jmeter.apache.org/usermanual/component_reference.html#HTML_Link_Parser)).

![HTTP Form Manager](https://raw.githubusercontent.com/tilln/jmeter-formman/master/docs/after.png)
Expand All @@ -32,7 +32,7 @@ Extract the [zip package](https://jmeter-plugins.org/files/packages/tilln-formma

### Via Manual Download

Copy the [jmeter-formman jar file](https://github.com/tilln/jmeter-formman/releases/download/1.0-SNAPSHOT/jmeter-formman-1.0-SNAPSHOT.jar)
Copy the [jmeter-formman jar file](https://github.com/tilln/jmeter-formman/releases/download/1.0/jmeter-formman-1.0.jar)
into JMeter's lib/ext directory and restart JMeter.

Usage
Expand Down Expand Up @@ -69,12 +69,20 @@ Normally these form parameters would be extracted into JMeter variables via
[CSS/JQuery Extractors](http://jmeter.apache.org/usermanual/component_reference.html#CSS/JQuery_Extractor)
and then added to the subsequent HTTP sampler, as in the screenshot above.

The HTTP Form Manager can replace those extractors and list of parameters,
The *HTTP Form Manager* can replace those extractors and list of parameters,
reducing the parameter list to just the username and password elements.
It can be especially useful for parameter names that are generated dynamically by the application and change all the time.

The plugin will copy all form parameters to the sampler, except the ones that are already defined in the sampler
(the username and password in the screenshot).

### Multiple Forms

Suppose the HTML response contains more than one form, then the URL path and method are used to determine which parameters to extract and send.
Suppose the HTML response contains more than one form, then the plugin needs to determine which form to copy from.

There are several options for identifying which form should match the current sampler.

##### Example: By sampler URL

```html
<html>
Expand All @@ -93,14 +101,16 @@ Suppose the HTML response contains more than one form, then the URL path and met
</html>
```

If the HTTP Sampler path matches form1 and the method is POST, then the parameters `__VIEWSTATE` and `submit` will be dynamically added as follows:
If the HTTP Sampler's *Path* matches `/form1` and the *Method* is POST, then the parameters `__VIEWSTATE` and `submit` will be copied as follows:

|Parameter |Value |Added by|
|-----------|-------|--------|
|__VIEWSTATE|value1 |plugin |
|submit |submit1|plugin |

Should both forms have the same URL path and method, then the value of the submit element needs to be included in the parameter list to determine which form to send:
##### Example: By submit element

Should both forms have the same URL path and method, then the value of the submit element may be used instead:

```html
<html>
Expand All @@ -109,44 +119,119 @@ Should both forms have the same URL path and method, then the value of the submi
<input type="hidden" name="__VIEWSTATE" value="value1" />
...
<input type="submit" name="submit" value="submit1" />
<input type="submit" name="other-submit" value="cancel" />
</form>
<form method="post" action="/form1">
<input type="hidden" name="__VIEWSTATE" value="value2" />
...
<input type="submit" name="submit" value="submit2" />
<input type="submit" name="other-submit" value="cancel" />
</form>
</body>
</html>
```

The plugin will try to match the form's submit element's name and value to a sampler parameter, so if the user added `submit1` the plugin adds `value1` for `__VIEWSTATE`:
The plugin will try to match the form's submit element's name and value to a sampler parameter.
So if the user added `submit1` the plugin adds `value1` for `__VIEWSTATE`:

|Parameter |Value |Added by|
|-----------|-------|--------|
|__VIEWSTATE|value1 |plugin |
|submit |submit1|user |
|__VIEWSTATE|value1 |plugin |

However, if the user added `other-submit` both forms would match and therefore no modification performed.

If there is no match, nothing will be added and the parameter list will not be modified at all.
##### Example: By sampler parameters

### Multiple Submit Elements
A unique set of parameters can also be used to identify the form, for instance if the submit elements have the same value.

```html
<html>
<body>
<form method="post" action="/form1">
<input type="hidden" name="__VIEWSTATE" value="value1" />
...
<input type="text" name="param1" value="text1" />
<input type="submit" name="submit" value="submit" />
</form>
<form method="post" action="/form1">
<input type="hidden" name="__VIEWSTATE" value="value2" />
...
<input type="text" name="param2" value="text2" />
<input type="submit" name="submit" value="submit" />
</form>
</body>
</html>
```

The plugin will try to find a form that contains all of the user-defined parameters.
So if the user added `param2` the plugin would copy `__VIEWSTATE` and `submit` from the second form:

|Parameter |Value |Added by|
|-----------|-------|--------|
|param2 |text2 |user |
|__VIEWSTATE|value2 |plugin |
|submit |submit |plugin |

##### Example: By CSS selector

A CSS selector expression may also be used that uniquely identifies one of the forms.

```html
<html>
<body>
<form method="post" action="/form1">
<input type="hidden" name="__VIEWSTATE" value="value1" />
...
<input type="submit" name="submit" value="submit1" />
</form>
<form method="post" action="/form1">
<input type="hidden" name="__VIEWSTATE" value="value2" />
...
<input type="submit" name="submit" value="submit2" />
</form>
</body>
</html>
```

The selector `[value=submit2]` would identify the second form, whereas `[name=submit]` would be ambiguous as both forms match.

In case a form has more than one submit element, none is added by the plugin but the user is expected to add one to the parameter list.

Configuration
-------------

![Configuration](https://raw.githubusercontent.com/tilln/jmeter-formman/master/docs/config.png)

* "Clear form data each iteration?": Whether to discard any stored form input data when starting a new thread iteration (default: true).
* Options:
* "Clear form data each iteration?": Whether to discard any stored form input data when starting a new thread iteration (default: true).
This avoids copying no longer relevant parameters e.g. when a new user session starts.

* "Content-Type": Ignore sampler responses that don't match this Content-Type (default: text/html).
* Form Identification:
If a response contains multiple forms, the following options can be used, in any combination,
to uniquely identify which form to copy parameters from:
* "By sampler URL": Consider only forms with the same URL and method (POST or GET) as in the sampler.
* "By sampler parameters": Consider only forms that contain all the samplers given parameters (name and value).
* "By submit element": Consider only forms that contain the sampler's given submit element.
* "By CSS selector": Consider only forms that contain elements selected by a CSS expression (unless empty).

All of these options will be used in conjunction to narrow down a set of forms.
If there is no match or more than one match, nothing will be copied, and the sampler's parameter list will not be modified at all.

* Sampler Modification:
* "Copy form parameters": Whether to copy form parameters from the identified form to the sampler (default: true).
* "Copy form URL": Whether to copy the URL of the identified form to the sampler (default: false).
Useful if the form URL is not static, e.g. contains dynamic query parameters.

By default, only HTTP Sampler responses with Content-Type *text/html* will be considered.
The JMeter Property `jmeter.formman.contentType` can be used to redefine that, e.g. *application/xhtml+xml*.

Limitations
-----------

* Form parameters that are not part of the previous HTML response, or are added or modified by JavaScript, need to be correlated manually as usual.

* The plugin has no effect if a form cannot be determined unambiguously (i.e. multiple forms with identical URLs and submit elements).
* The plugin has no effect if a form cannot be determined unambiguously.

* Button attributes formaction, formmethod, form are not supported.

* Usage of more than one HTTP Form Manager in a sampler's scope is untested.
Binary file modified docs/config.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 5deb78e

Please sign in to comment.