Improve readme

.gitattributes

@@ -6,5 +6,6 @@
 /phpunit.xml.dist           export-ignore
 /tests                      export-ignore
 /README.md                  export-ignore
+/CONTRIBUTING.md            export-ignore
 /resources/get-syn.php      export-ignore
 /docker-compose.yaml        export-ignore

CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to Mink WebDriver Classic Driver
+
+At the moment, contributions can be in the form of:
+
+1. [Reporting Bugs or Requesting Features](https://github.com/minkphp/webdriver-classic-driver/issues)
+2. [Contributing Code (as Pull Requests)](https://github.com/minkphp/webdriver-classic-driver/pulls)
+
+## Licensing
+
+The changes you contribute (as Pull Requests) will be under the same
+[MIT License](https://github.com/minkphp/webdriver-classic-driver/blob/main/LICENSE) used by this project. Needless to say, it is your responsibility that your contribution is either
+your original work or that it has been allowed by the original author.
+
+## Code Quality
+
+We use automated tools to have a general and consistent level of code quality. Simply run the following before pushing
+each commit (or at least before sending a Pull Request):
+
+```shell
+composer run lint
+```
+
+## Testing
+
+You will need [Docker](https://www.docker.com/products/docker-desktop/), [PHP 7.4](https://php.net/downloads) or higher
+and [Composer](https://getcomposer.org) running on your machine.
+
+1. Run the Selenium service (containing Chrome by default) with:
+    ```shell
+    docker compose up
+    ```
+2. Secondly, simply run the tests with:
+    ```shell
+    composer run test
+    ```
+3. You can observe and interact with the tests by visiting [`localhost:7900`](http://localhost:7900).
+
+### Additional Notes
+
+- By default, Chrome and Selenium 4 is used - but you can change that with the `SELENIUM_IMAGE` env var, e.g.:
+    ```shell
+    export SELENIUM_IMAGE=selenium/standalone-firefox:3    # Firefox and Selenium 3
+    docker compose up
+    ```
+- Tests depends on a server serving the test fixtures. `bootstrap.php` conveniently starts (and stops) such a server
+  for you while tests are running. It defaults to port `8002` for historical reasons, but can be changed with a custom
+  PHPUnit config file and changing the `WEB_FIXTURES_HOST` variable (see also the next point).
+- To customise any PHPUnit settings, make a copy of `phpunit.xml.dist` named as `phpunit.xml` and change it as needed.
+- The test setup can also work without Docker, but takes more effort (downloading and running **Selenium**, a
+  **Web Browser** and probably a **Web Driver** for your browser).

README.md

@@ -1,15 +1,39 @@
 # Mink WebDriver Classic Driver
 
+[![PHP Version](http://poser.pugx.org/mink/webdriver-classic-driver/require/php)](https://packagist.org/packages/mink/webdriver-classic-driver)
 [![Latest Stable Version](https://poser.pugx.org/mink/webdriver-classic-driver/v)](https://packagist.org/packages/mink/webdriver-classic-driver)
 [![Latest Unstable Version](https://poser.pugx.org/mink/webdriver-classic-driver/v/unstable)](https://packagist.org/packages/mink/webdriver-classic-driver)
 [![Total Downloads](https://poser.pugx.org/mink/webdriver-classic-driver/downloads)](https://packagist.org/packages/mink/webdriver-classic-driver)
 [![CI](https://github.com/minkphp/webdriver-classic-driver/actions/workflows/ci.yml/badge.svg)](https://github.com/minkphp/webdriver-classic-driver/actions/workflows/ci.yml)
 [![License](https://poser.pugx.org/mink/webdriver-classic-driver/license)](https://github.com/minkphp/webdriver-classic-driver/blob/main/LICENSE)
 [![codecov](https://codecov.io/gh/minkphp/webdriver-classic-driver/branch/main/graph/badge.svg?token=11hgqXqod9)](https://codecov.io/gh/minkphp/webdriver-classic-driver)
 
-## Usage Example
+A [php-webdriver](https://github.com/php-webdriver/php-webdriver)-based driver
+for [Mink](https://github.com/minkphp/Mink), supporting Selenium 2-4 and tested on Chrome, Firefox and Edge.
 
-``` php
+## Installation
+
+### For Mink/Standalone Usage
+
+Simply install the package with composer and check the [Standalone Usage Example](#standalone-usage-example) below.
+
+```shell
+composer require "behat/mink" "mink/webdriver-classic-driver"
+```
+
+### For Behat/BDD Usage
+
+1. Add all the relevant packages - typically this will be for testing your application, so you'd want to use `--dev`.
+    ```shell
+    composer require --dev "behat/behat" "behat/mink" "friends-of-behat/mink-extension" "mink/webdriver-classic-driver"
+    ```
+2. Configure Behat to enable the Mink Extension and set it to use this driver.
+
+## Standalone Usage Example
+
+You will need to run a WebDriver server, either using [Selenium](https://www.selenium.dev/) or the browser driver directly.
+
+```php
 <?php
 
 use Behat\Mink\Mink,
@@ -18,44 +42,17 @@ use Behat\Mink\Mink,
 
 require_once __DIR__ . '/vendor/autoload.php';
 
-$browserName = 'firefox';
-$url = 'http://example.com';
+$browserName = 'chrome';
+$url = 'https://example.com';
 
-$mink = new Mink(array(
+$mink = new Mink([
     'webdriver-classic' => new Session(new WebdriverClassicDriver($browserName)),
-));
+]);
 
 $session = $mink->getSession('webdriver-classic');
 $session->visit($url);
 
-$session->getPage()->findLink('Chat')->click();
+$session->getPage()->findLink('More information...')->click();
 ```
 
 Please refer to [MinkExtension-example](https://github.com/Behat/MinkExtension-example) for an executable example.
-
-## Installation
-
-``` bash
-composer require behat/mink mink/webdriver-classic-driver
-```
-
-## Testing
-
-1. Start WebDriver
-    1. If you have Docker installed, run
-    ```bash
-    docker run -p 4444:4444 selenium/standalone-firefox:4.18.1
-    ```
-    2. If you do not have Docker, but you have Java
-    ```bash
-    curl -L https://github.com/SeleniumHQ/selenium/releases/download/selenium-4.18.0/selenium-server-4.18.1.jar > selenium-server-4.18.1.jar
-    java -jar selenium-server-4.18.1.jar standalone
-    ```
-2. Start WebServer by running
-    ``` bash
-    ./vendor/bin/mink-test-server
-    ```
-3. Start PhpUnit
-    ```bash
-    ./vendor/bin/phpunit -v --coverage-clover=coverage.clover
-    ```

composer.json

@@ -41,5 +41,15 @@
         "branch-alias": {
             "dev-main": "1.x-dev"
         }
+    },
+    "scripts": {
+        "lint": [
+            "Composer\\Config::disableProcessTimeout",
+            "vendor/bin/phpstan"
+        ],
+        "test": [
+            "Composer\\Config::disableProcessTimeout",
+            "vendor/bin/phpunit"
+        ]
     }
 }