Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge pull request #553 from stof/phpdoc

Improved the phpdoc of form actions on elements to describe the behavior
  • Loading branch information...
commit f6ca55d1d5a816402eba8aa388ac5c8431cb7e97 2 parents 74e880b + 5a97a08
@stof stof authored
View
32 src/Behat/Mink/Driver/DriverInterface.php
@@ -347,6 +347,8 @@ public function getAttribute($xpath, $name);
*
* @throws UnsupportedDriverActionException When operation not supported by the driver
* @throws DriverException When the operation cannot be done
+ *
+ * @see \Behat\Mink\Element\NodeElement::getValue
*/
public function getValue($xpath);
@@ -358,6 +360,8 @@ public function getValue($xpath);
*
* @throws UnsupportedDriverActionException When operation not supported by the driver
* @throws DriverException When the operation cannot be done
+ *
+ * @see \Behat\Mink\Element\NodeElement::setValue
*/
public function setValue($xpath, $value);
@@ -368,6 +372,8 @@ public function setValue($xpath, $value);
*
* @throws UnsupportedDriverActionException When operation not supported by the driver
* @throws DriverException When the operation cannot be done
+ *
+ * @see \Behat\Mink\Element\NodeElement::check
*/
public function check($xpath);
@@ -378,11 +384,13 @@ public function check($xpath);
*
* @throws UnsupportedDriverActionException When operation not supported by the driver
* @throws DriverException When the operation cannot be done
+ *
+ * @see \Behat\Mink\Element\NodeElement::uncheck
*/
public function uncheck($xpath);
/**
- * Checks whether checkbox checked located by it's XPath query.
+ * Checks whether checkbox or radio button located by it's XPath query is checked.
*
* @param string $xpath
*
@@ -390,11 +398,13 @@ public function uncheck($xpath);
*
* @throws UnsupportedDriverActionException When operation not supported by the driver
* @throws DriverException When the operation cannot be done
+ *
+ * @see \Behat\Mink\Element\NodeElement::isChecked
*/
public function isChecked($xpath);
/**
- * Selects option from select field located by it's XPath query.
+ * Selects option from select field or value in radio group located by it's XPath query.
*
* @param string $xpath
* @param string $value
@@ -402,6 +412,8 @@ public function isChecked($xpath);
*
* @throws UnsupportedDriverActionException When operation not supported by the driver
* @throws DriverException When the operation cannot be done
+ *
+ * @see \Behat\Mink\Element\NodeElement::selectOption
*/
public function selectOption($xpath, $value, $multiple = false);
@@ -414,6 +426,8 @@ public function selectOption($xpath, $value, $multiple = false);
*
* @throws UnsupportedDriverActionException When operation not supported by the driver
* @throws DriverException When the operation cannot be done
+ *
+ * @see \Behat\Mink\Element\NodeElement::isSelected
*/
public function isSelected($xpath);
@@ -455,6 +469,8 @@ public function rightClick($xpath);
*
* @throws UnsupportedDriverActionException When operation not supported by the driver
* @throws DriverException When the operation cannot be done
+ *
+ * @see \Behat\Mink\Element\NodeElement::attachFile
*/
public function attachFile($xpath, $path);
@@ -560,7 +576,7 @@ public function executeScript($script);
/**
* Evaluates JS script.
*
- * The "return" keyword is optional in the script passed as argument. Driver implementation
+ * The "return" keyword is optional in the script passed as argument. Driver implementations
* must accept the expression both with and without the keyword.
*
* @param string $script
@@ -608,12 +624,14 @@ public function resizeWindow($width, $height, $name = null);
public function maximizeWindow($name = null);
/**
- * Submits the form.
- *
- * @param string $xpath Xpath.
+ * Submits the form.
+ *
+ * @param string $xpath Xpath.
*
* @throws UnsupportedDriverActionException When operation not supported by the driver
* @throws DriverException When the operation cannot be done
- */
+ *
+ * @see \Behat\Mink\Element\NodeElement::submitForm
+ */
public function submitForm($xpath);
}
View
44 src/Behat/Mink/Element/Element.php
@@ -92,12 +92,7 @@ protected function getSelectorsHandler()
}
/**
- * Checks whether element with specified selector exists.
- *
- * @param string $selector selector engine name
- * @param string|array $locator selector locator
- *
- * @return Boolean
+ * {@inheritdoc}
*/
public function has($selector, $locator)
{
@@ -105,9 +100,7 @@ public function has($selector, $locator)
}
/**
- * Checks if an element is still valid.
- *
- * @return boolean
+ * {@inheritdoc}
*/
public function isValid()
{
@@ -115,14 +108,7 @@ public function isValid()
}
/**
- * Waits for an element(-s) to appear and returns it.
- *
- * @param int $timeout Maximal allowed waiting time in milliseconds.
- * @param callable $callback Callback, which result is both used as waiting condition and returned.
- * Will receive reference to `this element` as first argument.
- *
- * @return mixed
- * @throws \InvalidArgumentException When invalid callback given.
+ * {@inheritdoc}
*/
public function waitFor($timeout, $callback)
{
@@ -147,12 +133,7 @@ public function waitFor($timeout, $callback)
}
/**
- * Finds first element with specified selector.
- *
- * @param string $selector selector engine name
- * @param string|array $locator selector locator
- *
- * @return NodeElement|null
+ * {@inheritdoc}
*/
public function find($selector, $locator)
{
@@ -162,22 +143,7 @@ public function find($selector, $locator)
}
/**
- * Finds all elements with specified selector.
- *
- * Valid selector engines are named, xpath, css, named_partial and named_exact.
- *
- * 'named' is a pseudo selector engine which prefers an exact match but
- * will return a partial match if no exact match is found.
- *
- * 'xpath' is a pseudo selector engine supported by SelectorsHandler.
- *
- * Full selector engines implement SelectorInterface and are instantiated
- * by a SelectorsHandler.
- *
- * @param string $selector selector engine name
- * @param string|array $locator selector locator
- *
- * @return NodeElement[]
+ * {@inheritdoc}
*/
public function findAll($selector, $locator)
{
View
22 src/Behat/Mink/Element/ElementInterface.php
@@ -36,17 +36,19 @@ public function getXpath();
public function getSession();
/**
- * Checks whether element with specified selector exists.
+ * Checks whether element with specified selector exists inside the current element.
*
* @param string $selector selector engine name
* @param string|array $locator selector locator
*
* @return Boolean
+ *
+ * @see ElementInterface::findAll for the supported selectors
*/
public function has($selector, $locator);
/**
- * Checks if an element is still valid.
+ * Checks if an element still exists in the DOM.
*
* @return boolean
*/
@@ -65,22 +67,34 @@ public function isValid();
public function waitFor($timeout, $callback);
/**
- * Finds first element with specified selector.
+ * Finds first element with specified selector inside the current element.
*
* @param string $selector selector engine name
* @param string|array $locator selector locator
*
* @return NodeElement|null
+ *
+ * @see ElementInterface::findAll for the supported selectors
*/
public function find($selector, $locator);
/**
- * Finds all elements with specified selector.
+ * Finds all elements with specified selector inside the current element.
+ *
+ * Valid selector engines are named, xpath, css, named_partial and named_exact.
+ *
+ * 'named' is a pseudo selector engine which prefers an exact match but
+ * will return a partial match if no exact match is found.
+ * 'xpath' is a pseudo selector engine supported by SelectorsHandler.
+ *
+ * More selector engines can be registered in the SelectorsHandler.
*
* @param string $selector selector engine name
* @param string|array $locator selector locator
*
* @return NodeElement[]
+ *
+ * @see NamedSelector for the locators supported by the named selectors
*/
public function findAll($selector, $locator);
View
45 src/Behat/Mink/Element/NodeElement.php
@@ -58,6 +58,8 @@ public function getParent()
/**
* Returns current node tag name.
*
+ * The value is always returned in lowercase to allow an easy comparison.
+ *
* @return string
*/
public function getTagName()
@@ -66,7 +68,19 @@ public function getTagName()
}
/**
- * Returns element value.
+ * Returns the value of the form field.
+ *
+ * For checkbox fields, the value is a boolean indicating whether the checkbox is checked.
+ * For radio buttons, the value is the value of the selected button in the radio group
+ * or null if no button is selected.
+ * For single select boxes, the value is the value of the selected option.
+ * For multiple select boxes, the value is an array of selected option values.
+ * for file inputs, the return value is undefined given that browsers don't allow accessing
+ * the value of file inputs for security reasons. Some drivers may allow accessing the
+ * path of the file set in the field, but this is not required if it cannot be implemened.
+ * For textarea elements and all textual fields, the value is the content of the field.
+ *
+ * Calling this method on other elements than form fields is not allowed.
*
* @return mixed
*/
@@ -76,9 +90,13 @@ public function getValue()
}
/**
- * Sets node value.
+ * Sets the value of the form field.
+ *
+ * Calling this method on other elements than form fields is not allowed.
*
* @param string $value
+ *
+ * @see NodeElement::getValue for the format of the value for each type of field
*/
public function setValue($value)
{
@@ -174,7 +192,9 @@ public function uncheck()
}
/**
- * Checks whether current node is checked if it's a checkbox field.
+ * Checks whether current node is checked if it's a checkbox or radio field.
+ *
+ * Calling this method on any other elements is not allowed.
*
* @return Boolean
*/
@@ -184,12 +204,19 @@ public function isChecked()
}
/**
- * Selects current node specified option if it's a select field.
+ * Selects specified option for select field or specified radio button in the group
+ *
+ * If the current node is a select box, this selects the option found by its value or
+ * its text.
+ * If the current node is a radio button, this selects the radio button with the given
+ * value in the radio button group of the current node.
+ *
+ * Calling this method on any other elements is not allowed.
*
* @param string $option
- * @param Boolean $multiple
+ * @param Boolean $multiple whether the option should be added to the selection for multiple selects
*
- * @throws ElementNotFoundException
+ * @throws ElementNotFoundException when the option is not found in the select box
*/
public function selectOption($option, $multiple = false)
{
@@ -213,6 +240,8 @@ public function selectOption($option, $multiple = false)
/**
* Checks whether current node is selected if it's a option field.
*
+ * Calling this method on any other elements is not allowed.
+ *
* @return Boolean
*/
public function isSelected()
@@ -223,6 +252,8 @@ public function isSelected()
/**
* Attach file to current node if it's a file input.
*
+ * Calling this method on any other elements than file input is not allowed.
+ *
* @param string $path path to file (local)
*/
public function attachFile($path)
@@ -309,6 +340,8 @@ public function keyUp($char, $modifier = null)
/**
* Submits the form.
+ *
+ * Calling this method on anything else than form elements is not allowed.
*/
public function submit()
{
View
26 src/Behat/Mink/Element/TraversableElement.php
@@ -20,7 +20,7 @@
abstract class TraversableElement extends Element
{
/**
- * Finds element by it's id.
+ * Finds element by its id.
*
* @param string $id element id
*
@@ -34,7 +34,7 @@ public function findById($id)
}
/**
- * Checks whether document has a link with specified locator.
+ * Checks whether element has a link with specified locator.
*
* @param string $locator link id, title, text or image alt
*
@@ -78,7 +78,7 @@ public function clickLink($locator)
}
/**
- * Checks whether document has a button (input[type=submit|image|button|reset], button) with specified locator.
+ * Checks whether element has a button (input[type=submit|image|button|reset], button) with specified locator.
*
* @param string $locator button id, value or alt
*
@@ -122,7 +122,7 @@ public function pressButton($locator)
}
/**
- * Checks whether document has a field (input, textarea, select) with specified locator.
+ * Checks whether element has a field (input, textarea, select) with specified locator.
*
* @param string $locator input id, name or label
*
@@ -154,6 +154,8 @@ public function findField($locator)
* @param string $value value
*
* @throws ElementNotFoundException
+ *
+ * @see NodeElement::setValue
*/
public function fillField($locator, $value)
{
@@ -167,11 +169,13 @@ public function fillField($locator, $value)
}
/**
- * Checks whether document has a checkbox with specified locator, which is checked.
+ * Checks whether element has a checkbox with specified locator, which is checked.
*
* @param string $locator input id, name or label
*
* @return Boolean
+ *
+ * @see NodeElement::isChecked
*/
public function hasCheckedField($locator)
{
@@ -181,11 +185,13 @@ public function hasCheckedField($locator)
}
/**
- * Checks whether document has a checkbox with specified locator, which is unchecked.
+ * Checks whether element has a checkbox with specified locator, which is unchecked.
*
* @param string $locator input id, name or label
*
* @return Boolean
+ *
+ * @see NodeElement::isChecked
*/
public function hasUncheckedField($locator)
{
@@ -231,7 +237,7 @@ public function uncheckField($locator)
}
/**
- * Checks whether document has a select field with specified locator.
+ * Checks whether element has a select field with specified locator.
*
* @param string $locator select id, name or label
*
@@ -252,6 +258,8 @@ public function hasSelect($locator)
* @param Boolean $multiple select multiple options
*
* @throws ElementNotFoundException
+ *
+ * @see NodeElement::selectOption
*/
public function selectFieldOption($locator, $value, $multiple = false)
{
@@ -265,7 +273,7 @@ public function selectFieldOption($locator, $value, $multiple = false)
}
/**
- * Checks whether document has a table with specified locator.
+ * Checks whether element has a table with specified locator.
*
* @param string $locator table id or caption
*
@@ -285,6 +293,8 @@ public function hasTable($locator)
* @param string $path path to file
*
* @throws ElementNotFoundException
+ *
+ * @see NodeElement::attachFile
*/
public function attachFileToField($locator, $path)
{

0 comments on commit f6ca55d

Please sign in to comment.
Something went wrong with that request. Please try again.