Allow passing NodeElement to/from JS scripts

[mvorisek]

merge after #353

no BC break (\Behat\Mink\Driver\DriverInterface interface cannot be updated in behat/mink v1.x, see related discussion minkphp/Mink#826, but this can be easily overcome by using @var phpdoc in the code, see example below)

serializing elements is natively supported by W3C WebDriver [1] and already fully supported by instaclick/php-webdriver [2] since v1.4.13

[1] https://w3c.github.io/webdriver/#executing-script
[2] instaclick/php-webdriver#110

example usage:

// expecting:
// a) $minkSession with working \WebDriver\Session driver
// b) loaded webpage with at least one <div> element with some ID attribute

$dumpElementFx = function ($v) {
    return $v instanceof \Behat\Mink\Element\NodeElement
        ? 'NodeElement: ' . $v->getXpath()
        : $v;
};

/** @var \Behat\Mink\Driver\Selenium2Driver */
$driver = $minkSession->getDriver();

$element = $driver->find('//div')[0]; // returns instance of \Behat\Mink\Element\NodeElement
var_dump($dumpElementFx($element));

$jsResult = $driver->evaluateScript(
    'return (function (elem) { return [elem, elem.id]; })(arguments[0])',
    [$element],
);

// will dump array with:
// [0] (new) instance of \Behat\Mink\Element\NodeElement to demonstrate conversion from php to webdriver and back
// [1] ID of given element extracted by JS
var_dump(array_map(fn ($v) => $dumpElementFx($v), $jsResult));

$jsResult = $driver->evaluateScript(
    'return (function (elem) { return [elem, elem.id]; })(arguments[0])',
    [$jsResult[0]],
);

// dump must be the same, but this time, element passed to a Selenium2Driver::evaluateScript had no xpath
var_dump(array_map(fn ($v) => $dumpElementFx($v), $jsResult));

outputs:

string(23) "NodeElement: (//div)[1]"
array(2) {
  [0]=>
  string(252) "NodeElement: webdriver-element--JZPOYwW6bl1bVmyK--aHR0cDovLzEyNy4wLjAuMTo0NDQ0L3dkL2h1Yi9zZXNzaW9uL2U0YjFlYWYyYTdmNTkzNjhlMWVkNTcxN2Y3YzlkNGZkL2VsZW1lbnQvYWU3YWI4ZTUtZGFlNS00NjA1LWFlZmUtYTgwZDg2YjY2ZmEy--YWU3YWI4ZTUtZGFlNS00NjA1LWFlZmUtYTgwZDg2YjY2ZmEy"
  [1]=>
  string(10) "atk_layout"
}
array(2) {
  [0]=>
  string(252) "NodeElement: webdriver-element--JZPOYwW6bl1bVmyK--aHR0cDovLzEyNy4wLjAuMTo0NDQ0L3dkL2h1Yi9zZXNzaW9uL2U0YjFlYWYyYTdmNTkzNjhlMWVkNTcxN2Y3YzlkNGZkL2VsZW1lbnQvYWU3YWI4ZTUtZGFlNS00NjA1LWFlZmUtYTgwZDg2YjY2ZmEy--YWU3YWI4ZTUtZGFlNS00NjA1LWFlZmUtYTgwZDg2YjY2ZmEy"
  [1]=>
  string(10) "atk_layout"
}

[codecov]

Codecov Report

Merging #352 (6c3cd06) into master (5d15043) will decrease coverage by 2.77%.
The diff coverage is 65.30%.

@@             Coverage Diff              @@
##             master     #352      +/-   ##
============================================
- Coverage     90.02%   87.25%   -2.78%     
- Complexity      150      161      +11     
============================================
  Files             1        1              
  Lines           421      455      +34     
============================================
+ Hits            379      397      +18     
- Misses           42       58      +16     

Impacted Files	Coverage Δ
src/Selenium2Driver.php	87.25% <65.30%> (-2.78%)	⬇️

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[mvorisek]

@stof I need to add a test, but can you please review this PR briefly?