Core Step setRadioButton
Description
Provides the ability to check radio buttons in HTML forms.
The radio button to set will be determined by finding the appropriate form followed by finding the appropriate field on that form.
Simple Form Selection: in many cases, your page will only have one form - that form will be used - you don't need to worry about trying to select the form.
Tricky Form Selection: if no last response is available, the step fails. Otherwise, the form to use is chosen as follows:
- If an explicit formName is given and the named form has a suitable field, that is used.
- If the current form has been previously set and it has a suitable field, that is used.
- All forms from the last response are searched until one is found with a suitable field.
If no such form is found, the step fails. If a form is found, it is then considered as the current form for future steps.
Simple Field Selection: in many cases, only one field will match the name and value of the field you are interested in. In these cases, you don't need to worry about the remaining details for selecting fields.
Tricky Field Selection: if a suitable form is found, the field is chosen as follows:
- First find all potential fields on the selected form having the correct name.
- Remove any fields which don't match the specified value (if specified).
- Fail if no fields remain or if the specified fieldIndex doesn't correspond to any of the found fields (i.e. is out of range).
- If fieldIndex is specified, return the corresponding field.
- Return the first field found.
NOTE: if you need, you can verify the value of a radio button using the storeInputFieldAttribute step with attributeName='checked'. It should return checked if the radio button is checked and false otherwise.
Parameters
- description
- Required? no
- The description of this test step.
- fieldIndex
- Required? no, default is the first field found that matches criteria
- The index of the field of interest (starting at 0) if more than one field matches criteria. Ignored if htmlId or xpath is used.
- forLabel
- Required? yes/no
- The text of the label field associated with the input field of interest. One of forLabel, htmlId, name, or xpath is required.
- formName
- Required? no, default is the last form selected using 'selectForm', otherwise searches all forms
- The name of the form containing the field of interest. Ignored if htmlId is used.
- htmlId
- Required? yes/no
- The id of the input field of interest. One of forLabel, htmlId, name, or xpath is required.
- name
- Required? yes/no
- The name of the input field of interest. One of forLabel, htmlId, name, or xpath is required.
- save
- Required? no
- A shorthand: save='prefixName' is the same as savePrefix='prefixName' saveResponse='true'.
- savePrefix
- Required? no, default is the 'savePrefix' parameter as specified in <config>.
- A name prefix can be specified for making a permanent copy of received responses. A unique number and the file extension (depending on the MIME-Type) will be appended. The resultpath attribute of the <config> element is used for determining the location of the saved result.
- saveResponse
- Required? no
- Whether to make a permanent copy of received responses. Overrides the default value set in the <config> element.
- value
- Required? yes/no
- The value to use to find the desired radio-button. Must be specified if name is specified.
- xpath
- Required? yes/no
- The xpath of the input field of interest. One of forLabel, htmlId, name, or xpath is required.
Inline Text
The inline text is all the text between the start tag ( <setRadioButton> ) and the end tag ( </setRadioButton> ), including blanks, tabs or newlines. Using a pair of start/end tags ( <setRadioButton> </setRadioButton> ) has not the same behavior than the seemingly equivalent empty element tag ( <setRadioButton/> ).
- Required? no
- An alternative to the attribute value for e.g. large TextAreas.
Details
NOTE: there is no facility to unset a radio button. This is not normally needed. When you set a radio button, all radio buttons with the same name in the same form are 'unset' automatically. So either no radio buttons have been selected (if your application didn't provide a default) or exactly one is set. The only time you need to worry about the no radio button case is if your application doesn't provide a default. If this is the case, simply load the page in question, don't explicitly set any radio buttons, and perform your tests.
Advanced Note: strictly speaking it is possible that via greasemonkey scripts, proxies or other means, someone could maliciously (or via accident) remove a checked setting on a radio button even if your application always provided a default. So you should make your application do something graceful in those cases and we may need to eventually provide an <forceUnsetRadioButton> step to allow testing of this very rare scenario.
See also: the storeInputFieldAttribute and selectForm steps.