diff --git a/.gitattributes b/.gitattributes index 60c56bf..cea7f33 100644 --- a/.gitattributes +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index ade6d88..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,3 +0,0 @@ -## 1.0.0 / unreleased - -Initial release of the driver diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2f89721 --- /dev/null +++ b/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). diff --git a/README.md b/README.md index 3414c0c..506a3fd 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ # 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) @@ -7,9 +8,32 @@ [![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 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 - ``` diff --git a/composer.json b/composer.json index e8f1a03..7a1be21 100644 --- a/composer.json +++ b/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" + ] } }