Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve readme #19

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -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
3 changes: 0 additions & 3 deletions CHANGELOG.md

This file was deleted.

50 changes: 50 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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).
65 changes: 31 additions & 34 deletions README.md
Original file line number Diff line number Diff line change
@@ -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)
aik099 marked this conversation as resolved.
Show resolved Hide resolved
[![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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would posting a link on https://github.com/FriendsOfBehat/MinkExtension/blob/master/doc/index.rst page, that will explain how to connect this driver specifically to Behat hurt?

// cc @stof .

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's a good idea.


## 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,
Expand All @@ -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
```
10 changes: 10 additions & 0 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
uuf6429 marked this conversation as resolved.
Show resolved Hide resolved
]
}
}
Loading