Fix and streamline capability handling

[uuf6429]

Fixes #46.

What Changed

1. Fixes code preventing us from overwriting capbalities when they're already set by php-webdriver.
2. Streamlines the flow so that it is clearer how it behaves:
   1. start with the browser-specific capabilities provided by php-webdriver
   2. add mink default capabilities
   3. add mink browser-specific default capabilities
   4. add capabilities defined by the end user
3. 'add', in this case, always overwrites existing capabilities

Remaining Questions

• How do we test this? (should we even test it?) In principle this is private behaviour and not something accessible from the outside.
• Should we be worried that this is a BC break? Existing users that have broken config would break their system, when in the past that config was unintentionally ignored.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 87.37%. Comparing base (ca55cde) to head (25d1859).
Report is 1 commits behind head on main.

✅ All tests successful. No failed tests found.

Additional details and impacted files

@@             Coverage Diff              @@
##               main      #51      +/-   ##
============================================
+ Coverage     84.40%   87.37%   +2.97%     
+ Complexity      196      195       -1     
============================================
  Files             1        1              
  Lines           500      499       -1     
============================================
+ Hits            422      436      +14     
+ Misses           78       63      -15     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• JS Bundle Analysis - Avoid shipping oversized bundles

[aik099]

How do we test this? (should we even test it?) In principle this is private behaviour and not something accessible from the outside.

Yes. We should test, that the user can override this (no matter if it came from the php-webdriver/php-webdriver library or Mink itself):

• any top-level desired capability (e.g. platform)
• any sub-level desired capability (e.g. goog:chromeOptions > binary)

Should we be worried that this is a BC break? Existing users that have broken config would break their system, when in the past that config was unintentionally ignored.

It's not a BC break.

We had similar discussions in the past about the $name argument of the switchIFrame method. According to the method's DocBlock, it should be always a string. However, we're not checking that and passing that $name argument directly to a WebDriver call. This allowed to have bonus undocumented behavior of switching frames by index.

When string argument typing was introduced people started complaining that this is a BC break, but it isn't because we've never advertised that passing frame index is even a supported behavior.

Same here: driver is supported to properly merge desired capabilities and the user is supposed to provide valid desired capabilities. If either of them doesn't do their work, then it's a bug and not a BC break 😄

[aik099]

Since we're not mocking the underlying WebDriver library to confirm, that proper desired capabilities were given at session creation time, then we should fall back to a functional test (like with timeouts) to indirectly confirm, that the correct desired capabilities were given.

@uuf6429 , any ideas?

[stof]

thus, this driver does not have a stable release yet. So there is no BC guarantee yet.

[uuf6429]

Since we're not mocking the underlying WebDriver library to confirm, that proper desired capabilities were given at session creation time

@aik099 Why not? I can simply use an anonymous subclass to test that.

Anyway, you can look at my take on it when I push it soon.

[uuf6429]

Side-note: Currently there's no way to unset top-level capabilities, except with potentially wrong values (e.g. to "unset" 'name' one would need to pass ['name' => null] - which is more like invalidation than unsetting, and might still affect selenium).

I don't know if this is significant. One possible way is to define a constant/special value as a amrker:

class WebDriver {
    public const CAPABILITY_UNSET = '{[%unset%]}';
...
    $capabilities = array_filter(
        array_merge(
            $capabilities1,
            $capabilities2,
            $capabilities3
        ),
        function ($value) {
            return $value !== self::CAPABILITY_UNSET;
        }
    );

Alternatively, a singleton (and later on, enums) could be used:

final class Capabilities
{
    private function __construct(){}

    public static function UNSET(): self
    {
        static $unset = null;
        return $unset ?? ($unset = new self());
    }
}

---

Come to think of it, we could also consider adding this functionality later if needed - it should be backword compatible.