Set custom capabilities

"Capabilities" describes desired aspects of the browser where tests should be run. For example platform name, browser windows size, whether insecure SSL certificates should be accepted etc. - see W3C WebDriver specification.

Capabilities could only be specified before the browser is started - so you cannot modify them from inside the test (or from setUp() method), because the browser is already instantiated.

Steward provides several options how to define custom capabilities - each option is suitable for different use-case.

Command line (CLI) options

ℹ️ Available since Steward 2.0.

This is the simplest solution. You pass the capability you want to use to the run command by --capability option in a format --capability=capabilityName:capabilityValue. Some examples:

# Simple capability
$ ./vendor/bin/steward run staging firefox --capability="screenResolution:1280x800"

# Multiple capabilities
$ ./vendor/bin/steward run staging firefox --capability="platform:Windows 10" --capability="screenResolution:1280x800"

# Browser version MUST be defined as a string - encapsulate it into quotes so it is not casted to a number
$  ./vendor/bin/steward run staging microsoftedge --capability="version:'14.14393'"

CLI options are most usable when you just need to pass a simple option or when the options differs each run (for example you could have separate test runs for Windows 10 and Windows 7 - so you just change the CLI option of each job on you continuous integration server).

Implement custom capabilities resolver

ℹ️ Available since Steward 2.2.

If you need more complex logic (or when defining many command line options makes the run command definition to complicated) or when you need some global capabilities which don't differ between runs, you can implement CustomCapabilitiesResolverInterface.

First, configure Steward to use your adjusted capabilities resolver class using steward.yml configuration file:

# steward.yml
capabilities_resolver: My\Steward\CustomCapabilitiesResolver

See separate wiki page for more information about the steward.yml configuration file.

Now you may need to set-up Composer autoloader, so that Steward can find your class. Your composer.json file may look like this:

...
    "autoload": {
        "psr-4": {
          "My\\Steward\\": "src/",
          "My\\Tests\\": "tests/"
        }
    }
...

Example how to define capability for all cases

<?php
// src/CustomCapabilitiesResolver.php

namespace My\Steward;

use Facebook\WebDriver\Remote\DesiredCapabilities;
use Lmc\Steward\ConfigProvider;
use Lmc\Steward\Selenium\CustomCapabilitiesResolverInterface;
use Lmc\Steward\Test\AbstractTestCase;

class CustomCapabilitiesResolver implements CustomCapabilitiesResolverInterface
{
    public function __construct(ConfigProvider $config)
    {
    }

    public function resolveDesiredCapabilities(AbstractTestCase $test, DesiredCapabilities $capabilities)
    {
        $capabilities->setCapability('pageLoadStrategy', 'normal');
    }

    public function resolveRequiredCapabilities(AbstractTestCase $test, DesiredCapabilities $capabilities)
    {
        return $capabilities;
    }
}

Example how to define capability for tests run in specific browser:

<?php
// src/CustomCapabilitiesResolver.php

namespace My\Steward;

use Facebook\WebDriver\Remote\DesiredCapabilities;
use Facebook\WebDriver\Remote\WebDriverBrowserType;
use Lmc\Steward\ConfigProvider;
use Lmc\Steward\Selenium\CustomCapabilitiesResolverInterface;
use Lmc\Steward\Test\AbstractTestCase;

class CustomCapabilitiesResolver implements CustomCapabilitiesResolverInterface
{
    /** @var ConfigProvider */
    private $config;

    public function __construct(ConfigProvider $config)
    {
        $this->config = $config;
    }

    public function resolveDesiredCapabilities(AbstractTestCase $test, DesiredCapabilities $capabilities)
    {
        if ($this->config->browserName === WebDriverBrowserType::IE) {
            $capabilities->setCapability('pageLoadStrategy', 'eager');
        }

        return $capabilities;
    }

    public function resolveRequiredCapabilities(AbstractTestCase $test, DesiredCapabilities $capabilities)
    {
        return $capabilities;
    }
}