Provides finders of web elements for WebDriver and WebElement. More...

Inheritance diagram for Xi\Test\Selenium\HasWebElements:

Public Member Functions
	find ($matcher, $format= 'css')
	Finds a subelement by a CSS selector or XPath expression.
	tryFind ($matcher, $format= 'css')
	Finds a subelement by a CSS selector or XPath expression, returns null if not found.
	findAll ($matcher, $format= 'css')
	Finds a set of subelements by a CSS selector or XPath expression.
	findByText ($text)
	Finds a (sub)element that immediately contains the given text.
	findAllByText ($text)
	Finds all subelements that immediately contain the given text.
	tryFindByText ($text)
	Finds a (sub)element that immediately contains the given text, returns null if not found.
	findByLabel ($labelText)
	Finds a subelement pointed to by a label tag's for attribute.
	fillInByLabels (array $labelsToValues)
	Given an array, finds elements whose labels correspond to the keys and fills in the values.
	findTableRowWithText ($text, $noHeaderAndFooter=true)
	Finds a 'tr' element that contains a subelement whose text is $text.
	tryFindTableRowWithText ($text, $noHeaderAndFooter=true)
	findAllTableRowsWithText ($text, $noHeaderAndFooter=true)
	Finds all 'tr' elements that contain a subelement whose text is $text.
	waitForElement ($matcher, $timeout, $format= 'css')
	Waits for a subelement appear for an extended period of time.
	waitForText ($text, $timeout)
	Waits for text to appear in a subelement.
	withImplicitWait ($func, $timeout=null)
	Sets an implicit wait of $timeout, calls $func, then restores the previous implicit wait.
Protected Member Functions
	findByTextImpl ($mode, $text)
	findImpl ($mode, $expr, $format)
	getSession ()
	makeRelativePostRequest ($relPath, $params)
	createWebElement ($elementId)

Detailed Description

Provides finders of web elements for WebDriver and WebElement.

Definition at line 7 of file HasWebElements.php.

Member Function Documentation

Xi\Test\Selenium\HasWebElements::find	(	$	matcher,
		$	format = `'css'`
	)

Finds a subelement by a CSS selector or XPath expression.

Parameters:

string	$matcher	The matcher, format depending on $format.
string	$format	Either 'css' or 'xpath'. Default: 'css'.

Returns:: WebElement The matched element. Never null.

Exceptions:

SeleniumException if an error occurred or no element matched

Definition at line 17 of file HasWebElements.php.

    {
        return $this->findImpl('one', $matcher, $format);
    }

Xi\Test\Selenium\HasWebElements::tryFind	(	$	matcher,
		$	format = `'css'`
	)

Finds a subelement by a CSS selector or XPath expression, returns null if not found.

Parameters:

string	$matcher	The matcher, format depending on $format.
string	$format	Either 'css' or 'xpath'. Default: 'css'.

Returns:: WebElement The matched element, or null if not found.

Exceptions:

SeleniumException if an error occurred

Definition at line 30 of file HasWebElements.php.

    {
        return $this->findImpl('tryOne', $matcher, $format);
    }

Xi\Test\Selenium\HasWebElements::findAll	(	$	matcher,
		$	format = `'css'`
	)

Finds a set of subelements by a CSS selector or XPath expression.

Parameters:

string	$matcher	The matcher, format depending on $format.
string	$format	Either 'css' or 'xpath'. Default: 'css'.

Returns:: WebElement[] The (possibly empty) set of matched elements.

Definition at line 42 of file HasWebElements.php.

    {
        return $this->findImpl('all', $matcher, $format);
    }

Xi\Test\Selenium\HasWebElements::findByText ( $ text )

Finds a (sub)element that immediately contains the given text.

Note that, unlike the selector-based find methods, this method may return the current element.

It only finds text that is not interrupted by tags. This limitation may be removed in a future version.

Parameters:

string $text The text to search for.

Returns:: WebElement The element that contained the text as a substring.

Exceptions:

SeleniumException when the text cannot be found

Definition at line 58 of file HasWebElements.php.

    {
        return $this->findByTextImpl('one', $text);
    }

Xi\Test\Selenium\HasWebElements::findAllByText ( $ text )

Finds all subelements that immediately contain the given text.

Note that, unlike the selector-based find methods, this method may return the current element.

It only finds text that is not interrupted by tags. This limitation may be removed in a future version.

Parameters:

string $text The text to search for.

Returns:: WebElement[] The elements that contained the text as a substring.

Definition at line 73 of file HasWebElements.php.

    {
        return $this->findByTextImpl('all', $text);
    }

Xi\Test\Selenium\HasWebElements::tryFindByText ( $ text )

Finds a (sub)element that immediately contains the given text, returns null if not found.

Note that, unlike the selector-based find methods, this method may return the current element.

It only finds text that is not interrupted by tags. This limitation may be removed in a future version.

Parameters:

string $text The text to search for.

Returns:: WebElement|null The element that contained the text as a substring, or null if not found.

Definition at line 88 of file HasWebElements.php.

    {
        return $this->findByTextImpl('tryOne', $text);
    }

Xi\Test\Selenium\HasWebElements::findByTextImpl	(	$	mode,
		$	text
	)		`[protected]`

Definition at line 93 of file HasWebElements.php.

    {
        $expr = '//*[contains(text(),\'' . addslashes($text) . '\')]';
        return $this->findImpl($mode, $expr, 'xpath');
    }

Xi\Test\Selenium\HasWebElements::findByLabel ( $ labelText )

Finds a subelement pointed to by a label tag's for attribute.

Parameters:

string $labelText The text of the label whose element to search for.

Returns:: WebElement The element the label with the given text points to with its `for` attribute.

Exceptions:

SeleniumException if the label cannot be found or it does not point to a valid element

Definition at line 106 of file HasWebElements.php.

    {
        $element = $this->findByText($labelText);
        if ($element->getTagName() != 'label') {
            throw new SeleniumException("Tag with text '$labelText' was not a label but a " . $element->getTagName());
        }
        $for = $element->getAttribute('for');
        if (empty($for)) {
            throw new SeleniumException("Label with text '$labelText' has no for attribute");
        }
        return $this->find('#' . $for);
    }

Xi\Test\Selenium\HasWebElements::fillInByLabels ( array $ labelsToValues )

Given an array, finds elements whose labels correspond to the keys and fills in the values.

This makes the common case of filling in large forms more convenient.

Parameters:

array $labelsToValues An array where keys are valid for findByLabel and values are valid for fillIn().

Exceptions:

SeleniumException if some label cannot be found or it does not point to a valid element

Definition at line 127 of file HasWebElements.php.

    {
        foreach ($labelsToValues as $key => $value) {
            try {
                $this->findByLabel($key)->fillIn($value);
            } catch (SeleniumException $e) {
                throw new SeleniumException("Failed to fill in '$key' with '$value'", $e->getCode(), $e);
            }
        }
    }

Xi\Test\Selenium\HasWebElements::findTableRowWithText	(	$	text,
		$	noHeaderAndFooter = `true`
	)

Finds a 'tr' element that contains a subelement whose text is $text.

It only finds text that is not interrupted by tags. This limitation may be removed in a future version.

Parameters:

array	$text	The text to search for.
boolean	$noHeaderAndFooter	Whether to ignore rows in thead and tfoot (tbody is still optional). Defaults to true.

Returns:: WebElement

Exceptions:

SeleniumException if such a row cannot be found

Definition at line 149 of file HasWebElements.php.

    {
        $results = $this->findAllTableRowsWithText($text, $noHeaderAndFooter);
        if (!empty($results)) {
            return array_shift($results);
        } else {
            throw new SeleniumException("Failed to find a table row with the given text");
        }
    }

Xi\Test\Selenium\HasWebElements::tryFindTableRowWithText	(	$	text,
		$	noHeaderAndFooter = `true`
	)

Definition at line 159 of file HasWebElements.php.

    {
        $results = $this->findAllTableRowsWithText($text, $noHeaderAndFooter);
        if (!empty($results)) {
            return array_shift($results);
        } else {
            return null;
        }
    }

Xi\Test\Selenium\HasWebElements::findAllTableRowsWithText	(	$	text,
		$	noHeaderAndFooter = `true`
	)

Finds all 'tr' elements that contain a subelement whose text is $text.

It only finds text that is not interrupted by tags. This limitation may be removed in a future version.

Parameters:

array	$text	The text to search for.
boolean	$noHeaderAndFooter	Whether to ignore rows in thead and tfoot (tbody is still optional). Defaults to true.

Returns:: WebElement[]

Definition at line 179 of file HasWebElements.php.

    {
        $results = array();
        foreach ($this->findAllByText($text) as $elemWithText) {
            $ancestor = null;

            $ancestors = $elemWithText->getAncestors();
            while (!empty($ancestors)) {
                $ancestor = array_shift($ancestors);
                if ($ancestor->getTagName() == 'tr') {
                    break;
                } else {
                    $ancestor = null;
                }
            }

            if ($ancestor) {
                if ($noHeaderAndFooter) {
                    $tags = $ancestor->getAncestorTags();
                    $ok = !in_array('thead', $tags) && !in_array('tfoot', $tags);
                } else {
                    $ok = true;
                }
                if ($ok) {
                    $results[] = $ancestor;
                }
            }
        }
        return $results;
    }

Xi\Test\Selenium\HasWebElements::waitForElement	(	$	matcher,
		$	timeout,
		$	format = `'css'`
	)

Waits for a subelement appear for an extended period of time.

By default, all elements are waited for for a short while. See WebDriver::setImplicitWait().

Parameters:

string	$matcher	The matcher, format depending on $format.
int \| float	$timeout	The number of seconds to wait at most.
string	$format	Either 'css' or 'xpath'. Default: 'css'.

Returns:: WebElement The matched element. Never null.

Exceptions:

SeleniumException if an error occurred or no element matched

Definition at line 221 of file HasWebElements.php.

    {
        $self = $this;
        return $this->withImplicitWait(function() use ($self, $matcher, $format) {
            return $self->find($matcher, $format);
        }, $timeout);
    }

Xi\Test\Selenium\HasWebElements::waitForText	(	$	text,
		$	timeout
	)

Waits for text to appear in a subelement.

By default, all elements are waited for for a short while. See WebDriver::setImplicitWait().

Parameters:

string	$text	The text to wait for.
int \| float	$timeout	The number of seconds to wait at most. Has a default value.

Returns:: WebElement The element that contained the text. Never null.

Exceptions:

SeleniumException if an error occurred or the timeout elapsed.

Definition at line 239 of file HasWebElements.php.

    {
        $self = $this;
        return $this->withImplicitWait(function() use ($self, $text) {
            return $self->findByText($text);
        }, $timeout);
    }

Xi\Test\Selenium\HasWebElements::withImplicitWait	(	$	func,
		$	timeout = `null`
	)

Sets an implicit wait of $timeout, calls $func, then restores the previous implicit wait.

Throws a SeleniumException on timeout. Exceptions from $func pass through.

This is used internally to implement the `waitFor*` methods, but can also be used by client code.

By default, all elements are waited for for a short while. See WebDriver::setImplicitWait().

Parameters:

callable	$func	A callback to invoke.
int \| float	$timeout	The number of seconds to set the implicit wait to while $func executes.

Returns:: mixed The return value of $func

Exceptions:

SeleniumException	if the timeout elapses or $func throws it.
\Exception	if $func throws it.

Definition at line 263 of file HasWebElements.php.

    {
        $oldImplicitWait = $this->getSession()->getImplicitWait();
        $this->getSession()->setImplicitWait($timeout);
        try {
            $ret = call_user_func($func);
        } catch (\Exception $e) {
            $this->getSession()->setImplicitWait($oldImplicitWait);
            throw $e;
        }
        $this->getSession()->setImplicitWait($oldImplicitWait);
        return $ret;
    }

Xi\Test\Selenium\HasWebElements::findImpl	(	$	mode,
		$	expr,
		$	format
	)		`[protected]`

Definition at line 277 of file HasWebElements.php.

    {
        assert(in_array($mode, array('all', 'one', 'tryOne')));
        $fetchAll = ($mode === 'all' || $mode === 'tryOne');

        $url = $fetchAll ? '/elements' : '/element';
        $using = $this->seleniumFormat($format);
        $response = $this->makeRelativePostRequest($url, array('using' => $using, 'value' => $expr));

        if ($mode === 'all') {
            $result = array();
            foreach ($response as $responseElement) {
                $result[] = $this->createWebElement($responseElement['ELEMENT']);
            }
            return $result;
        } elseif ($mode === 'one') {
            return $this->createWebElement($response['ELEMENT']);
        } elseif ($mode === 'tryOne') {
            $first = array_shift($response);
            if ($first !== null) {
                return $this->createWebElement($first['ELEMENT']);
            } else {
                return null;
            }
        } else {
            throw new \Exception("Internal error: findImpl called with incorrect \$mode: $mode.");
        }
    }

Xi\Test\Selenium\HasWebElements::getSession ( ) [abstract, protected]

Returns:: WebDriver

Reimplemented in Xi\Test\Selenium\WebDriver, and Xi\Test\Selenium\WebElement.

Xi\Test\Selenium\HasWebElements::makeRelativePostRequest	(	$	relPath,
		$	params
	)		`[abstract, protected]`

Reimplemented in Xi\Test\Selenium\WebDriver, and Xi\Test\Selenium\WebElement.

Xi\Test\Selenium\HasWebElements::createWebElement ( $ elementId ) [abstract, protected]

Reimplemented in Xi\Test\Selenium\WebDriver, and Xi\Test\Selenium\WebElement.

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation