Update the README and documentation

README.md

@@ -1,5 +1,41 @@
-This is the fork of MinkExtension library that supports PHP `>=7.4` and supports Symfony `>=4.4`.
+# MinkExtension
 
-For the documentation, please [refer to the original repository](https://github.com/Behat/MinkExtension).
+MinkExtension is an integration layer between Behat 3.0+ and Mink 1.5+
+and it provides:
+
+* Additional services for Behat (``Mink``, ``Sessions``, ``Drivers``).
+* ``Behat\MinkExtension\Context\MinkAwareContext`` which provides ``Mink``
+  instance for your contexts.
+* Base ``Behat\MinkExtension\Context\MinkContext`` context which provides base
+  step definitions and hooks for your contexts or subcontexts. Or it could be
+  even used as context on its own.
+
+## Docs
+
+[Official documentation](doc/index.md).
+
+## Translated languages
+
+For now exist 11 translated languages: `cs`,`de`,`es`,`fr`,`ja`,`nl`,`pl`,`pt`,`ro`,`ru`,`sv`.
+
+**Note:** The `ja`,`nl` and `sv` are outdated.
+
+#### How to add a new translated language?
+
+If you want to translate another language, you can use as reference the `ru` language file under
+[translations folder](https://github.com/Behat/MinkExtension/tree/master/i18n).
+
+**Important:** The filename must match with the same translated language name in [Behat](https://github.com/Behat/Behat/blob/master/i18n.php) and [Gherkin](https://github.com/Behat/Gherkin/blob/master/i18n.php) in order to work correctly.
+
+If the language does not exist in [Gherkin](https://github.com/Behat/Gherkin/blob/master/i18n.php), 
+you should consider [contributing to Gherkin translations](https://github.com/Behat/Gherkin/blob/master/CONTRIBUTING.md#contributing-to-gherkin-translations).
+
+## Copyright
+
+Copyright (c) 2012 Konstantin Kudryashov (ever.zet). See LICENSE for details.
+
+## Contributors
+
+* Konstantin Kudryashov [everzet](http://github.com/everzet) [lead developer]
+* Other [awesome developers](https://github.com/Behat/MinkExtension/graphs/contributors)
 
-No updates other than Symfony compatibility will be provided, but this fork _might_ be synchronised with the original repository in the future.

doc/index.md

@@ -1,38 +1,19 @@
 # Mink Extension
 
-You can use Behat to describe anything, that you can describe in business
-logic. It's tools, gui applications, web applications. The most interesting part
-is web applications. First, behavioral testing already exists in the web world -
-it's called functional or acceptance testing. Almost all popular frameworks
-and languages provide functional testing tools. Today we'll talk about how to
-use Behat for functional testing of web applications. [Mink](http://mink.behat.org)
-is a tool exactly for that and this extension provides integration for it.
-
-Basically, MinkExtension is an integration layer between Behat 3.0+ and Mink 1.4+
-and it provides:
-
-* Additional services for Behat (`Mink`, `Sessions`, `Drivers`).
-* `Behat\MinkExtension\Context\MinkAwareContext` which provides a `Mink`
-  instance for your contexts.
-* Base `Behat\MinkExtension\Context\MinkContext` context which provides base
-  step definitions and hooks for your contexts or subcontexts. Or it could be
-  even used as context on its own.
+This extension allows you to use the [Mink](https://mink.behat.org) browser emulator
+abstraction with [Behat](https://github.com/Behat/Behat), a BDD tool for PHP.
 
-## Installation
-
-This extension requires:
-
-* Behat 3.0+
-* Mink 1.4+
-
-### Through Composer
+Together, this allows you to do functional and acceptance testing of web applications. 
+You can write behavior-driven tests for web applications using natural language 
+descriptions and run them against different browsers and drivers without changing
+your test code.
 
-The easiest way to keep your suite updated is to use [Composer](http://getcomposer.org):
+## Installation
 
-1. Install with composer:
+1. Installation with Composer:
 
     ```bash
-    $ composer require --dev behat/mink-extension
+    $ composer require --dev friends-of-behat/mink-extension
     ```
 
 2. Activate the extension by specifying its class in your `behat.yml`:
@@ -46,12 +27,12 @@ The easiest way to keep your suite updated is to use [Composer](http://getcompos
           base_url:  'http://example.com'
           sessions:
             default:
-              goutte: ~
+              browserkit_http: ~
     ```
 
 ## Usage
 
-After installing the extension, there are 4 usage options available:
+After installing the extension, there are four usage options available:
 
 1. Extending `Behat\MinkExtension\Context\RawMinkContext` in your feature suite.
    This will give you the ability to use a preconfigured `Mink` instance with some
@@ -118,8 +99,8 @@ this `$mink` instance will be preconfigured based on the settings you've provide
 
 ## Configuration
 
-MinkExtension comes with a flexible configuration system, that gives you
-the ability to configure Mink inside Behat to fulfil all your needs.
+MinkExtension comes with a flexible configuration system that gives you
+the ability to configure Mink inside Behat from your `behat.yml` file.
 
 ### Sessions
 
@@ -134,7 +115,7 @@ default:
                 first_session:
                     selenium2: ~
                 second_session:
-                    goutte: ~
+                    browserkit_http: ~
                 third_session:
                     selenium2: ~
 ```
@@ -168,11 +149,20 @@ javascript).
 
 ### Drivers
 
-First of all, there are drivers enabling configuration. MinkExtension comes
-with support for 7 drivers out of the box:
+Configuration settings depend on the Mink driver being used. Out of the box, MinkExtension can configure the following Mink drivers:
+
+* **Symfony `BrowserKit` with Symfony `HttpClient`** - headless driver without JavaScript support. In order to use it, install [`behat/mink-browserkit-driver`](https://packagist.org/packages/behat/mink-browserkit-driver) and [`symfony/http-client`](https://packagist.org/packages/symfony/http-client) through Composer. Then, modify your `behat.yml` profile:
+
+    ```yaml
+    default:
+        extensions:
+            Behat\MinkExtension:
+                sessions:
+                    my_session:
+                        browserkit_http: ~
+    ```
 
-* `GoutteDriver` - headless driver without JavaScript support. In order to use
-  it, modify your `behat.yml` profile:
+* **GoutteDriver** - headless driver without JavaScript support. In order to use it, install [`behat/mink-goutte-driver`](https://packagist.org/packages/behat/mink-goutte-driver) through Composer. Then, modify your `behat.yml` profile:
 
     ```yaml
     default:
@@ -215,8 +205,7 @@ with support for 7 drivers out of the box:
                                   ssl.certificate_authority: false
       ```
 
-* `Selenium2Driver` - javascript driver. In order to use it, modify your
-  `behat.yml` profile:
+* **Selenium2Driver** - javascript driver. In order to use it, install [`behat/mink-selenium2-driver`](https://packagist.org/packages/behat/mink-selenium2-driver) through Composer. Then, modify your `behat.yml` profile:
 
     ```yaml
     default:
@@ -227,9 +216,8 @@ with support for 7 drivers out of the box:
                         selenium2: ~
     ```
 
-* `SauceLabsDriver` - special flavor of the Selenium2Driver configured to use the
-  selenium2 hosted installation of saucelabs.com. In order to use it, modify your
-  `behat.yml` profile:
+* **SauceLabsDriver** - special flavor of the Selenium2Driver configured to use the
+  selenium2 hosted installation of saucelabs.com. This uses Selenium2Driver, so make sure you have [`behat/mink-selenium2-driver`](https://packagist.org/packages/behat/mink-selenium2-driver) installed. Then, modify your `behat.yml` profile:
 
     ```yaml
     default:
@@ -240,9 +228,8 @@ with support for 7 drivers out of the box:
                         sauce_labs: ~
     ```
 
-* `BrowserStackDriver` - special flavor of the Selenium2Driver configured to use the
-  selenium2 hosted installation of browserstack.com. In order to use it, modify your
-  `behat.yml` profile:
+* **BrowserStackDriver** - special flavor of the Selenium2Driver configured to use the
+  selenium2 hosted installation of browserstack.com. This uses Selenium2Driver, so make sure you have [`behat/mink-selenium2-driver`](https://packagist.org/packages/behat/mink-selenium2-driver) installed. Then, modify your `behat.yml` profile:
 
     ```yaml
     default:
@@ -253,8 +240,7 @@ with support for 7 drivers out of the box:
                         browser_stack: ~
     ```
 
-* `SeleniumDriver` - javascript driver. In order to use it, modify your `behat.yml`
-  profile:
+* **SeleniumDriver** - javascript driver. In order to use it, install [`behat/mink-selenium-driver`](https://packagist.org/packages/behat/mink-selenium-driver) through Composer. Then, modify your `behat.yml` profile:
 
     ```yaml
     default:
@@ -265,8 +251,7 @@ with support for 7 drivers out of the box:
                         selenium: ~
     ```
 
-* `SahiDriver` - javascript driver. In order to use it, modify your `behat.yml`
-  profile:
+* **SahiDriver** - javascript driver. In order to use it, install [`behat/mink-sahi-driver`](https://packagist.org/packages/behat/mink-sahi-driver) through Composer. Then, modify your `behat.yml` profile:
 
     ```yaml
     default:
@@ -277,8 +262,7 @@ with support for 7 drivers out of the box:
                         sahi: ~
     ```
 
-* `ZombieDriver` - zombie.js javascript headless driver. In order to use it, modify
-  your `behat.yml` profile:
+* **ZombieDriver** - zombie.js javascript headless driver. In order to use it, install [`behat/mink-zombie-driver`](https://packagist.org/packages/behat/mink-zombie-driver) through Composer. Then, modify your `behat.yml` profile:
 
     ```yaml
     default:
@@ -291,18 +275,6 @@ with support for 7 drivers out of the box:
                             node_modules_path: /usr/local/lib/node_modules/
     ```
 
-> [!NOTE]
-> The phar version of Mink comes bundled with all 5 drivers and you don't need to do
-> anything except enabling them in order to use them.
-
-But if you're using Composer, you need to install drivers that you need first:
-
-- GoutteDriver - `behat/mink-goutte-driver`
-- SeleniumDriver - `behat/mink-selenium-driver`
-- Selenium2Driver (also used for SauceLabs and BrowserStack) - `behat/mink-selenium2-driver`
-- SahiDriver - `behat/mink-sahi-driver`
-- ZombieDriver - `behat/mink-zombie-driver`
-
 > [!NOTE]
 > All drivers share the same API, which means that you could use multiple drivers
 > for the same suite - whichever one fits your needs for concrete scenarios. Don't
@@ -336,3 +308,43 @@ There's other useful parameters, that you can use to configure your suite:
   name.
 * `mink_loader` - path to a file loaded to make Mink available (useful when
   using the PHAR archive for Mink, useless when using Composer)
+
+## Adding your own or other drivers
+
+If you have another Mink driver implementation that you would like to use, 
+you can create your own `DriverFactory` implementation. Then, create a Behat
+extension class and use it to register your driver factory with this extension
+here along the lines of:
+
+```php
+<?php
+
+namespace My\Mink\DriverPackage;
+
+use Behat\MinkExtension\ServiceContainer\MinkExtension;
+use Behat\Testwork\ServiceContainer\Extension as ExtensionInterface;
+use Behat\Testwork\ServiceContainer\ExtensionManager;
+
+class MyMinkDriverExtension implements ExtensionInterface
+{
+    // ... other ExtensionInterface methods omitted for brevity 
+
+    public function initialize(ExtensionManager $extensionManager): void
+    {
+        if (null !== $minkExtension = $extensionManager->getExtension('mink')) {
+            /* @var $minkExtension MinkExtension */
+            $minkExtension->registerDriverFactory(new MyDriverFactory());
+        }
+    }
+}
+```
+
+Your driver factory defines the driver name, which can be used to configure
+_your_ driver in the `behat.yml` file just like the other drivers shown above.
+
+> [!TIP]
+> If you would like to see a real-world example, have a look at the [SymfonyExtension](https://github.com/FriendsOfBehat/SymfonyExtension). 
+> In its [extension class](https://github.com/FriendsOfBehat/SymfonyExtension/blob/3ed86d77923be089d67d952e7b75af48fec42e22/src/ServiceContainer/SymfonyExtension.php#L102),
+> it registers a `SymfonyDriver` under the driver name `symfony`. That driver can be used
+> to make requests directly against a Symfony Kernel, without the overhead of HTTP network
+> requests and within the same PHP process that is running Behat.