layout	doc
title	PhpBrowser Module - Codeception - Documentation

PhpBrowser Module

For additional reference, please review the source

Uses Guzzle to interact with your application over CURL. Module works over CURL and requires PHP CURL extension to be enabled.

Use to perform web acceptance tests with non-javascript browser.

If test fails stores last shown page in 'output' dir.

Status

Maintainer: davert
Stability: stable
Contact: davert.codecept@mailican.com
Works with Guzzle

Please review the code of non-stable modules and provide patches if you have issues.

Configuration

url required - start url of your app
curl - curl options
headers - ...
cookies - ...
auth - ...
verify - ...
.. those and other Guzzle Request options

Example (`acceptance.suite.yml`)

modules:
   enabled: [PhpBrowser]
   config:
      PhpBrowser:
         url: 'http://localhost'
         auth: ['admin', '123345]
         curl:
             CURLOPT_RETURNTRANSFER: true

Public Properties

guzzle - contains Guzzle client instance: \GuzzleHttp\Client
client - Symfony BrowserKit instance.

All SSL certification checks are disabled by default. Use Guzzle request options to configure certifications and others.

amHttpAuthenticated

Authenticates user for HTTP_AUTH

param $username
param $password

amOnPage

Opens the page. Requires relative uri as parameter

Example:

{% highlight php %}

amOnPage('/'); // opens /register page $I->amOnPage('/register'); ?>

{% endhighlight %}

param $page

amOnSubdomain

Sets 'url' configuration parameter to hosts subdomain. It does not open a page on subdomain. Use amOnPage for that

{% highlight php %}

amOnSubdomain('user'); $I->amOnPage('/'); // moves to http://user.mysite.com/ ?>

{% endhighlight %}

param $subdomain

@return mixed

attachFile

Attaches file from Codeception data directory to upload field.

Example:

{% highlight php %}

attachFile('input[@type="file"]', 'prices.xls'); ?>

{% endhighlight %}

param $field
param $filename

checkOption

Ticks a checkbox. For radio buttons use selectOption method.

Example:

{% highlight php %}

checkOption('#agree'); ?>

{% endhighlight %}

param $option

click

Perform a click on link or button. Link or button are found by their names or CSS selector. Submits a form if button is a submit type.

If link is an image it's found by alt attribute value of image. If button is image button is found by it's value If link or button can't be found by name they are searched by CSS selector.

The second parameter is a context: CSS or XPath locator to narrow the search.

Examples:

{% highlight php %}

click('Logout'); // button of form $I->click('Submit'); // CSS button $I->click('#form input[type=submit]'); // XPath $I->click('//form/*[@type=submit]'); // link in context $I->click('Logout', '#nav'); // using strict locator $I->click(['link' => 'Login']); ?>

{% endhighlight %}

param $link
param $context

dontSee

Check if current page doesn't contain the text specified. Specify the css selector to match only specific region.

Examples:

{% highlight php %}

dontSee('Login'); // I can suppose user is already logged in $I->dontSee('Sign Up','h1'); // I can suppose it's not a signup page $I->dontSee('Sign Up','//body/h1'); // with XPath ?>

{% endhighlight %}

param $text
param null $selector

dontSeeCheckboxIsChecked

Assert if the specified checkbox is unchecked. Use css selector or xpath to match.

Example:

{% highlight php %}

dontSeeCheckboxIsChecked('#agree'); // I suppose user didn't agree to terms $I->seeCheckboxIsChecked('#signup_form input[type=checkbox]'); // I suppose user didn't check the first checkbox in form. ?>

{% endhighlight %}

param $checkbox

dontSeeCookie

Checks that cookie doesn't exist

param $cookie

@return mixed

dontSeeCurrentUrlEquals

Checks that current url is not equal to value. Unlike dontSeeInCurrentUrl performs a strict check.

{% highlight php %}

dontSeeCurrentUrlEquals('/'); ?>

{% endhighlight %}

param $uri

dontSeeCurrentUrlMatches

Checks that current url does not match a RegEx value

{% highlight php %}

dontSeeCurrentUrlMatches('~$/users/(\d+)~'); ?>

{% endhighlight %}

param $uri

dontSeeElement

Checks if element does not exist (or is visible) on a page, matching it by CSS or XPath You can also specify expected attributes of this element.

Example:

{% highlight php %}

dontSeeElement('.error'); $I->dontSeeElement('//form/input[1]'); $I->dontSeeElement('input', ['name' => 'login']); $I->dontSeeElement('input', ['value' => '123456']); ?>

{% endhighlight %}

param $selector

dontSeeInCurrentUrl

Checks that current uri does not contain a value

{% highlight php %}

dontSeeInCurrentUrl('/users/'); ?>

{% endhighlight %}

param $uri

dontSeeInField

Checks that an input field or textarea doesn't contain value. Field is matched either by label or CSS or Xpath Example:

{% highlight php %}

dontSeeInField('Body','Type your comment here'); $I->dontSeeInField('form textarea[name=body]','Type your comment here'); $I->dontSeeInField('form input[type=hidden]','hidden_value'); $I->dontSeeInField('#searchform input','Search'); $I->dontSeeInField('//form/*[@name=search]','Search'); $I->seeInField(['name' => 'search'], 'Search'); ?>

{% endhighlight %}

param $field
param $value

dontSeeInTitle

Checks that page title does not contain text.

param $title

@return mixed

dontSeeLink

Checks if page doesn't contain the link with text specified. Specify url to narrow the results.

Examples:

{% highlight php %}

dontSeeLink('Logout'); // I suppose user is not logged in ?>

{% endhighlight %}

param $text
param null $url

dontSeeOptionIsSelected

Checks if option is not selected in select field.

{% highlight php %}

dontSeeOptionIsSelected('#form input[name=payment]', 'Visa'); ?>

{% endhighlight %}

param $selector
param $optionText

@return mixed

executeInGuzzle

Low-level API method. If Codeception commands are not enough, use Guzzle HTTP Client methods directly

Example:

{% highlight php %}

executeInGuzzle(function (\GuzzleHttp\Client $client) { $client->get('/get', ['query' => ['foo' => 'bar']]); }); ?>

{% endhighlight %}

It is not recommended to use this command on a regular basis. If Codeception lacks important Guzzle Client methods, implement them and submit patches.

param callable $function

fillField

Fills a text field or textarea with value.

Example:

{% highlight php %}

fillField("//input[@type='text']", "Hello World!"); $I->fillField(['name' => 'email'], 'jon@mail.com'); ?>

{% endhighlight %}

param $field
param $value

grabAttributeFrom

Grabs attribute value from an element. Fails if element is not found.

{% highlight php %}

grabAttributeFrom('#tooltip', 'title'); ?>

{% endhighlight %}

param $cssOrXpath
param $attribute
internal param $element @return mixed

grabCookie

Grabs a cookie value.

param $cookie

@return mixed

grabFromCurrentUrl

Takes a parameters from current URI by RegEx. If no url provided returns full URI.

{% highlight php %}

grabFromCurrentUrl('~$/user/(\d+)/~'); $uri = $I->grabFromCurrentUrl(); ?>

{% endhighlight %}

param null $uri
internal param $url @return mixed

grabTextFrom

Finds and returns text contents of element. Element is searched by CSS selector, XPath or matcher by regex.

Example:

{% highlight php %}

grabTextFrom('h1'); $heading = $I->grabTextFrom('descendant-or-self::h1'); $value = $I->grabTextFrom('~

{% endhighlight %}

param $cssOrXPathOrRegex

@return mixed

grabValueFrom

param $field

@return array|mixed|null|string

resetCookie

Unsets cookie

param $cookie

@return mixed

see

Check if current page contains the text specified. Specify the css selector to match only specific region.

Examples:

{% highlight php %}

see('Logout'); // I can suppose user is logged in $I->see('Sign Up','h1'); // I can suppose it's a signup page $I->see('Sign Up','//body/h1'); // with XPath ?>

{% endhighlight %}

param $text
param null $selector

seeCheckboxIsChecked

Assert if the specified checkbox is checked. Use css selector or xpath to match.

Example:

{% highlight php %}

seeCheckboxIsChecked('#agree'); // I suppose user agreed to terms $I->seeCheckboxIsChecked('#signup_form input[type=checkbox]'); // I suppose user agreed to terms, If there is only one checkbox in form. $I->seeCheckboxIsChecked('//form/input[@type=checkbox and @name=agree]'); ?>

{% endhighlight %}

param $checkbox

seeCookie

Checks that cookie is set.

param $cookie

@return mixed

seeCurrentUrlEquals

Checks that current url is equal to value. Unlike seeInCurrentUrl performs a strict check.

{% highlight php %}

seeCurrentUrlEquals('/'); ?>

{% endhighlight %}

param $uri

seeCurrentUrlMatches

Checks that current url is matches a RegEx value

{% highlight php %}

seeCurrentUrlMatches('~$/users/(\d+)~'); ?>

{% endhighlight %}

param $uri

seeElement

Checks if element exists on a page, matching it by CSS or XPath. You can also specify expected attributes of this element.

{% highlight php %}

seeElement('.error'); $I->seeElement('//form/input[1]'); $I->seeElement('input', ['name' => 'login']); $I->seeElement('input', ['value' => '123456']); // strict locator in first arg, attributes in second $I->seeElement(['css' => 'form input'], ['name' => 'login']); ?>

{% endhighlight %}

param $selector
param array $attributes @return

seeInCurrentUrl

Checks that current uri contains a value

{% highlight php %}

seeInCurrentUrl('home'); // to match: /users/1 $I->seeInCurrentUrl('/users/'); ?>

{% endhighlight %}

param $uri

seeInField

Checks that an input field or textarea contains value. Field is matched either by label or CSS or Xpath

Example:

{% highlight php %}

seeInField('Body','Type your comment here'); $I->seeInField('form textarea[name=body]','Type your comment here'); $I->seeInField('form input[type=hidden]','hidden_value'); $I->seeInField('#searchform input','Search'); $I->seeInField('//form/*[@name=search]','Search'); $I->seeInField(['name' => 'search'], 'Search'); ?>

{% endhighlight %}

param $field
param $value

seeInTitle

Checks that page title contains text.

{% highlight php %}

seeInTitle('Blog - Post #1'); ?>

{% endhighlight %}

param $title

@return mixed

seeLink

Checks if there is a link with text specified. Specify url to match link with exact this url.

Examples:

{% highlight php %}

seeLink('Logout'); // matches Logout $I->seeLink('Logout','/logout'); // matches Logout ?>

{% endhighlight %}

param $text
param null $url

seeOptionIsSelected

Checks if option is selected in select field.

{% highlight php %}

seeOptionIsSelected('#form input[name=payment]', 'Visa'); ?>

{% endhighlight %}

param $selector
param $optionText

@return mixed

seePageNotFound

Asserts that current page has 404 response status code.

seeResponseCodeIs

Checks that response code is equal to value provided.

param $code

@return mixed

selectOption

Selects an option in select tag or in radio button group.

Example:

{% highlight php %}

selectOption('form select[name=account]', 'Premium'); $I->selectOption('form input[name=payment]', 'Monthly'); $I->selectOption('//form/select[@name=account]', 'Monthly'); ?>

{% endhighlight %}

Can select multiple options if second argument is array:

{% highlight php %}

selectOption('Which OS do you use?', array('Windows','Linux')); ?>

{% endhighlight %}

param $select
param $option

sendAjaxGetRequest

If your page triggers an ajax request, you can perform it manually. This action sends a GET ajax request with specified params.

See ->sendAjaxPostRequest for examples.

param $uri
param $params

sendAjaxPostRequest

If your page triggers an ajax request, you can perform it manually. This action sends a POST ajax request with specified params. Additional params can be passed as array.

Example:

Imagine that by clicking checkbox you trigger ajax request which updates user settings. We emulate that click by running this ajax request manually.

{% highlight php %}

sendAjaxPostRequest('/updateSettings', array('notifications' => true)); // POST $I->sendAjaxGetRequest('/updateSettings', array('notifications' => true)); // GET {% endhighlight %} * `param` $uri * `param` $params #### sendAjaxRequest If your page triggers an ajax request, you can perform it manually. This action sends an ajax request with specified method and params. Example: You need to perform an ajax request specifying the HTTP method. {% highlight php %} sendAjaxRequest('PUT', /posts/7', array('title' => 'new title'); {% endhighlight %} * `param` $method * `param` $uri * `param` $params #### setCookie Sets a cookie. * `param` $cookie * `param` $value @return mixed #### setHeader __not documented__ #### submitForm Submits a form located on page. Specify the form by it's css or xpath selector. Fill the form fields values as array. Skipped fields will be filled by their values from page. You don't need to click the 'Submit' button afterwards. This command itself triggers the request to form's action. Examples: {% highlight php %} submitForm('#login', array('login' => 'davert', 'password' => '123456')); {% endhighlight %} For sample Sign Up form: {% highlight html %} Login:
Password:
Do you agree to out terms?
Select pricing plan FreePaid {% endhighlight %} I can write this: {% highlight php %} submitForm('#userForm', array('user' => array('login' => 'Davert', 'password' => '123456', 'agree' => true))); {% endhighlight %} Note, that pricing plan will be set to Paid, as it's selected on page. * `param` $selector * `param` $params #### uncheckOption Unticks a checkbox. Example: {% highlight php %} uncheckOption('#notify'); ?>

{% endhighlight %}

param $option

FilesExpand file tree

PhpBrowser.md

Latest commit

History

PhpBrowser.md

File metadata and controls

PhpBrowser Module

Status

Configuration

Example (acceptance.suite.yml)

Public Properties

amHttpAuthenticated

amOnPage

amOnSubdomain

attachFile

checkOption

click

dontSee

dontSeeCheckboxIsChecked

dontSeeCookie

dontSeeCurrentUrlEquals

dontSeeCurrentUrlMatches

dontSeeElement

dontSeeInCurrentUrl

dontSeeInField

dontSeeInTitle

dontSeeLink

dontSeeOptionIsSelected

executeInGuzzle

fillField

grabAttributeFrom

grabCookie

grabFromCurrentUrl

grabTextFrom

grabValueFrom

resetCookie

see

seeCheckboxIsChecked

seeCookie

seeCurrentUrlEquals

seeCurrentUrlMatches

seeElement

seeInCurrentUrl

seeInField

seeInTitle

seeLink

seeOptionIsSelected

seePageNotFound

seeResponseCodeIs

selectOption

sendAjaxGetRequest

sendAjaxPostRequest

Example (`acceptance.suite.yml`)