Improved error handling when Chrome Connection can not be established…

… and provided hints.

docs/troubleshooting.md

@@ -0,0 +1,11 @@
+Troubleshooting
+===============
+
+1. Chrome Crashed unexpectedly
+------------------------------
+
+When the shm size is too low, chrome is likely to crash randomly. 
+The solution is increasing SHM size until the crashes no longer occur (or mounting /dev/shm:/dev/shm to the container)
+Sometimes increasing SHM size is not possible (gitlab.com shared runners, for example gitlab-org/gitlab-runner#1454
+Running with vendor/bin/behat --rerun || vendor/bin/behat --rerun is a good workaround for this and other hiccups. 
+Since it'll cause behat to rerun only the failed scenarios and only fail the build if they fail again.

src/ChromeBrowser.php

@@ -44,7 +44,7 @@ public function start()
         if (null === $versionInfo) {
             throw new \RuntimeException(
                 sprintf(
-                    'Could not fetch version information from %s. Please check if Chrome is running.',
+                    'Could not fetch version information from %s. Please check if Chrome is running. Please see docs/troubleshooting.md if Chrome crashed unexpected.',
                     $this->http_uri.'/json/version'
                 )
             );

src/ChromePage.php

@@ -56,6 +56,15 @@ public function waitForLoad()
                     return $this->page_ready;
                 });
             } catch (StreamReadException $exception) {
+                if ($exception->isTimedOut() && false === $this->canDevToolsConnectionBeEstablished()) {
+                    throw new \RuntimeException(
+                        sprintf(
+                            'Chrome is unreachable via "%s" and might have crashed. Please see docs/troubleshooting.md',
+                            $this->getUrl()
+                        )
+                    );
+                }
+
                 if (!$exception->isEof() && $exception->isTimedOut()) {
                     $this->waitForLoad();
                 }

src/DevToolsConnection.php

@@ -22,6 +22,22 @@ public function __construct($url, $socket_timeout = null)
         $this->socket_timeout = $socket_timeout;
     }
 
+    public function canDevToolsConnectionBeEstablished()
+    {
+        $options = ['fragment_size' => 2000000]; # Chrome closes the connection if a message is sent in fragments
+        if (is_numeric($this->socket_timeout) && $this->socket_timeout > 0) {
+            $options['timeout'] = (int) $this->socket_timeout;
+        }
+        $client = new Client($this->url, $options);
+
+        return $client->isConnected();
+    }
+
+    protected function getUrl()
+    {
+        return $this->url;
+    }
+
     public function connect($url = null)
     {
         $url = $url == null ? $this->url : $url;