BrowserStack PHPUnit Documentation

Getting Started

Note: Refer our sample repo on Github: phpunit-browserstack

BrowserStack supports Selenium automated tests using PHPUnit, and running your tests on our cloud setup is simple and straightforward. Get started with a sample test, which opens Google's homepage, searches for ‘BrowserStack’, and asserts for the title of the search results page. For the code to run successfully on your machine, please ensure that the following libraries have been installed:

# Install using composer
php composer.phar install phpunit/phpunit-selenium

Here is a sample test case written for running with PHPUnit.

class SingleTest extends BrowserStackTest {

    public function testGoogle() {
        self::$driver->get("https://www.google.com/ncr");
        $element = self::$driver->findElement(WebDriverBy::name("q"));
        $element->sendKeys("BrowserStack");
        $element->submit();
        $this->assertEquals('BrowserStack - Google Search', self::$driver->getTitle());
    }

}

To actually run the test case, we need to integrate with BrowserStack as follows.

Integration with BrowserStack

Note: Running your PHPUnit tests on BrowserStack requires a username and an access key.

To obtain your username and access keys, sign up for a Free Trial or purchase a plan.

Integration of PHPUnit with BrowserStack is made possible by use of following module:

$config_file = getenv('CONFIG_FILE');
if(!$config_file) $config_file = 'config/single.conf.json';
$GLOBALS['CONFIG'] = json_decode(file_get_contents($config_file), true);

$GLOBALS['BROWSERSTACK_USERNAME'] = getenv('BROWSERSTACK_USERNAME');
if(!$GLOBALS['BROWSERSTACK_USERNAME']) $GLOBALS['BROWSERSTACK_USERNAME'] = $CONFIG['user'];

$GLOBALS['BROWSERSTACK_ACCESS_KEY'] = getenv('BROWSERSTACK_ACCESS_KEY');
if(!$GLOBALS['BROWSERSTACK_ACCESS_KEY']) $GLOBALS['BROWSERSTACK_ACCESS_KEY'] = $CONFIG['key'];

class BrowserStackTest extends PHPUnit_Framework_TestCase
{
    protected static $driver;
    protected static $bs_local;

    public static function setUpBeforeClass()
    {
        $CONFIG = $GLOBALS['CONFIG'];
        $task_id = getenv('TASK_ID') ? getenv('TASK_ID') : 0;

        $url = "https://" . $GLOBALS['BROWSERSTACK_USERNAME'] . ":" . $GLOBALS['BROWSERSTACK_ACCESS_KEY'] . "@" . $CONFIG['server'] ."/wd/hub";
        $caps = $CONFIG['environments'][$task_id];

        foreach ($CONFIG["capabilities"] as $key => $value) {
            if(!array_key_exists($key, $caps))
                $caps[$key] = $value;
        }

        if(array_key_exists("browserstack.local", $caps) && $caps["browserstack.local"])
        {
            $bs_local_args = array("key" => $GLOBALS['BROWSERSTACK_ACCESS_KEY']);
            self::$bs_local = new BrowserStack\Local();
            self::$bs_local->start($bs_local_args);
        }

        self::$driver = RemoteWebDriver::create($url, $caps);
    }

    public static function tearDownAfterClass()
    {
        self::$driver->quit();
        if(self::$bs_local) self::$bs_local->stop();
    }
}

The module reads from config file where you need to put the BrowserStack Hub URL and credentials.

{
  "server": "hub-cloud.browserstack.com",
  "user": "USERNAME",
  "key": "ACCESS_KEY",

  "capabilities": {
    "browserstack.debug": true
  },

  "environments": [{
    "browser": "chrome"
  }]
}

Run your test on BrowserStack using following command:

# Run using composer
composer single

Configuring capabilities

To run your tests on BrowserStack Automate, the tests have to be run on remote machines. Therefore, the capabilities of the WebDriver have to be changed accordingly.

Setting your operating system, browser, and screen resolution

Using the drop-down menus, select a combination of operating system, browser, and screen resolution. To see the order of precedence for the capabilities, please read about parameter override rules here.

1. Select an OS

Windows 7

2. Select a browser

Windows XP

3. Select a resolution

1024 x 768

"environments": [{
  "os": "Windows",
  "os_version": "7",
  "browser": "IE",
  "browser_version": "8.0',
  "resolution": "1024x768"
}]

Note: If browser_version capability is not set, the test will run on the latest version of the browser set by browser capability.

Run tests on mobile browsers

You can run your Selenium test scripts on iOS and Android emulators by specifying the version and device in the input capabilities. These capabilities are browserName and device. The following example has iPhone selected as the browserName, and iPhone 5 as the device.

"environments": [{
  "browserName": "iPhone",
  "platform": "MAC',
  "device": "iPhone 5"
}]

For a list of all supported devices, visit the Browsers and Platforms page.

Note: We have recently launched a real device cloud for Selenium testing in beta. Please contact support@browserstack.com for access.

Builds and projects

Keep track of all your automated tests using the build and project capabilities. Group your tests into builds, and builds further into projects.

"capabilities": {
  "build": "version1",
  "project": "newintropage"
}

Note: Allowed characters include uppercase and lowercase letters, digits, spaces, colons, periods, and underscores. Other characters, like hyphens or slashes are not allowed.

Self-signed certificates

To avoid invalid certificate errors while testing on BrowserStack Automate, set the acceptSslCerts capability in your test to true.

"capabilities": {
  "acceptSslCerts": true
}

Enable and Disable Pop-ups

IE

To enable the popups in IE, use the browserstack.ie.enablePopups capability.

"capabilities": {
  "browserstack.ie.enablePopups": true
}

Safari

To enable the popups in Safari, use the browserstack.safari.enablePopups capability.

"capabilities": {
  "browserstack.safari.enablePopups": true
}

Debugging

Logs

To debug failed tests, BrowserStack provides you with raw logs, which are the console logs from the browser tests; visual logs, which capture successive screenshots of the test; and text logs to display all the steps that were performed by the test.

Live screencast

With live screencast, view ongoing tests to debug the functionality of features that are being tested. The generated videos can be recorded and downloaded for later viewing.

Logs and the live screencast help you to compare and detect any changes that may have occurred since a similar test was last run. Debugging is set to false by default. To enable logs, set the BrowserStack custom capability browserstack.debug to true.

"capabilities": {
  "browserstack.debug": true
}

Video recording

Videos are recorded for every BrowserStack Automate test. This feature helps you to verify and debug failed tests, confirm the functionality of tested features, and download videos for later viewing.

Note: Video recording increases test execution time slightly. You can disable this feature by setting the browserstack.video capability to false.

"capabilities": {
  "browserstack.video": false
}

Other capabilities

BrowserStack supports the full complement of Selenium capabilities, as well as, some custom ones.

Running Local Test

To test a private server with PHPUnit on BrowserStack, install local bindings.

# Install using composer
php composer.phar install browserstack/browserstack-local

Then update config file and set the browserstack.local capability to true.

{
  "server": "hub-cloud.browserstack.com",
  "user": "USERNAME",
  "key": "ACCESS_KEY",

  "capabilities": {
    "browserstack.local": true
  },

  "environments": [{
    "browser": "chrome"
  }]
}

Here is a sample test case written for running local with PHPUnit.

class LocalTest extends BrowserStackTest {

    public function testLocal() {
      self::$driver->get("http://bs-local.com:45691/check");
      $this->assertContains('Up and running', self::$driver->getPageSource(), '', true);
    }

}

Run your local test on BrowserStack using following command:

# Run using composer
composer local

Running Parallel Tests

To run tests on multiple browsers in parallel with PHPUnit on BrowserStack, modify the config file as below:

{
  "server": "hub-cloud.browserstack.com",
  "user": "USERNAME",
  "key": "ACCESS_KEY",

  "capabilities": {
    "browserstack.debug": true
  },

  "environments": [{
    "browser": "chrome"
  },{
    "browser": "firefox"
  },{
    "browser": "safari"
  },{
    "browser": "internet explorer"
  }]
}

Capabilities for each environment can be customised as explained earlier.

You need the following custom script to launch the tests in parallel.

$config_file = getenv('CONFIG_FILE');
if(!$config_file) $config_file = 'config/single.conf.json';
$GLOBALS['CONFIG'] = json_decode(file_get_contents($config_file), true);

$GLOBALS['BROWSERSTACK_USERNAME'] = getenv('BROWSERSTACK_USERNAME');
if(!$GLOBALS['BROWSERSTACK_USERNAME']) $GLOBALS['BROWSERSTACK_USERNAME'] = $CONFIG['user'];

$GLOBALS['BROWSERSTACK_ACCESS_KEY'] = getenv('BROWSERSTACK_ACCESS_KEY');
if(!$GLOBALS['BROWSERSTACK_ACCESS_KEY']) $GLOBALS['BROWSERSTACK_ACCESS_KEY'] = $CONFIG['key'];

$CONFIG = $GLOBALS['CONFIG'];
$procs = array();

foreach ($CONFIG['environments'] as $key => $value) {
    $cmd = "TASK_ID=$key vendor/bin/phpunit tests/single_test.php 2>&1\n";
    print_r($cmd);

    $procs[$key] = popen($cmd, "r");
}

foreach ($procs as $key => $value) {
    while (!feof($value)) { 
        print fgets($value, 4096);
    }
    pclose($value);
}

Run your tests in parallel on BrowserStack using following command:

# Run using composer
composer parallel

PHPUnit

Getting Started

Integration with BrowserStack

Configuring capabilities

Setting your operating system, browser, and screen resolution

Run tests on mobile browsers

Builds and projects

Self-signed certificates

Enable and Disable Pop-ups

Debugging

Other capabilities

Running Local Test

Running Parallel Tests

Additional Notes

REST API

Queuing

Support Automate PHPUnit

PHPUnit

Getting Started

Integration with BrowserStack

Configuring capabilities

Setting your operating system, browser, and screen resolution

Run tests on mobile browsers

Builds and projects

Self-signed certificates

Enable and Disable Pop-ups

Debugging

Other capabilities

Running Local Test

Running Parallel Tests

Additional Notes

REST API

Queuing