Initial commit

.gitignore

@@ -0,0 +1,6 @@
+/.php_cs.cache
+/.php_cs
+/composer.phar
+/composer.lock
+/phpunit.xml
+/vendor/

.php_cs.dist

@@ -0,0 +1,57 @@
+<?php
+
+$header = <<<'HEADER'
+This file is part of the Panthère project.
+
+(c) Kévin Dunglas <[email protected]>
+
+For the full copyright and license information, please view the LICENSE
+file that was distributed with this source code.
+HEADER;
+
+$finder = PhpCsFixer\Finder::create()->in(__DIR__);
+
+return PhpCsFixer\Config::create()
+    ->setRiskyAllowed(true)
+    ->setRules([
+        '@Symfony' => true,
+        '@Symfony:risky' => true,
+        'array_syntax' => [
+            'syntax' => 'short',
+        ],
+        'braces' => [
+            'allow_single_line_closure' => true,
+        ],
+        'declare_strict_types' => true,
+        'header_comment' => [
+            'header' => $header,
+            'location' => 'after_open',
+        ],
+        'modernize_types_casting' => true,
+        'native_function_invocation' => true,
+        'no_extra_consecutive_blank_lines' => [
+            'break',
+            'continue',
+            'curly_brace_block',
+            'extra',
+            'parenthesis_brace_block',
+            'return',
+            'square_brace_block',
+            'throw',
+            'use',
+        ],
+        'no_useless_else' => true,
+        'no_useless_return' => true,
+        'ordered_imports' => true,
+        'phpdoc_add_missing_param_annotation' => [
+            'only_untyped' => true,
+        ],
+        'phpdoc_order' => true,
+        'psr4' => true,
+        'semicolon_after_instruction' => true,
+        'strict_comparison' => true,
+        'strict_param' => true,
+        'ternary_to_null_coalescing' => true,
+    ])
+    ->setFinder($finder)
+;

LICENSE

@@ -0,0 +1,21 @@
+The MIT license
+
+Copyright (c) 2018-present Kévin Dunglas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,152 @@
+# Panthère
+**A browser testing and web scrapping library for [PHP](https://php.net) and [Symfony](https://symfony.com)**
+
+*Panthère* is a convenient standalone library to scrape websites and to run end to end tests **using real browsers**.
+
+Because it leverages [the W3C's WebDriver protocol](https://www.w3.org/TR/webdriver/) to drive native web browsers such
+as Google Chrome and Firefox, Panthère is super powerful.
+
+Because it implements the popular Symfony's [BrowserKit](https://symfony.com/doc/current/components/browser_kit.html) and
+[DomCrawler](https://symfony.com/doc/current/components/dom_crawler.html) APIs, Panthère is very easy to use, and contains
+all features you need to test your apps. It will sound familiar if you ever created [a functional test for a Symfony app](https://symfony.com/doc/current/testing.html#functional-tests):
+the API is exactly the same!
+Keep in mind that Panthère doesn't depend of Symfony, it's a standalone library.
+
+Because Panthère automatically finds your local installation of Chrome and launches it (thanks to [ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/)),
+you don't have anything to install on your computer: no Selenium server nor obscure driver.
+In test mode, Panthère automatically starts your application using [the PHP built-in web-server](http://php.net/manual/en/features.commandline.webserver.php).
+Focus on writing your tests or web-scrapping scenario, Panthère takes care of everything else.
+
+## Install
+
+Use [Composer](https://getcomposer.org/) to install Panthère in your project:
+
+    composer req dunglas/panthere
+
+## Basic Usage
+
+```php
+<?php
+
+require __DIR__.'/vendor/autoload.php';
+
+$client = new \Panthere\Client();
+$crawler = $client->request('GET', 'http://api-platform.com'); // Yes, this website is 100% in JavaScript
+
+$link = $crawler->selectLink('Support')->link();
+$crawler = $client->click($link);
+
+// Wait for an element to be rendered
+$client->getWebDriver()->wait()->until(
+    \Facebook\WebDriver\WebDriverExpectedCondition::visibilityOfElementLocated(\Facebook\WebDriver\WebDriverBy::className('support'))
+);
+
+echo $crawler->filter('.support')->text();
+$client->getWebDriver()->takeScreenshot('screen.png'); // Yeah, screenshot!
+
+$client->stop();
+```
+
+## Testing Usage
+
+The `PanthereTestCase` class allows you to easily write E2E tests. It automatically starts your app using the built-in PHP
+web server and let you crawl it using Panthère.
+It extends [PHPUnit](https://phpunit.de/)'s `TestCase` and provide all testing tools you're used to.
+
+```php
+<?php
+
+use Panthere\PanthereTestCase;
+
+class E2eTest extends PanthereTestCase
+{
+    public function testMyApp()
+    {
+        $client = static::createPanthereClient(); // Your app is automatically started using the built-in web server
+        $crawler = $client->request('GET', static::$baseUri.'/mypage'); // static::$baseUri contains the base URL
+
+        $this->assertContains('My Title', $crawler->filter('title')->text()); // You can use any PHPUnit assertion
+    }
+}
+```
+
+To run this test:
+
+    phpunit tests/E2eTest.php
+
+### A Polymorph Feline
+
+If you are testing a Symfony application, `PanthereTestCase` automatically extends the `WebTestCase` class. It means that
+you can easily create functional tests executing directly the kernel of your application and accessing all your existing
+services. Unlike the Panthère's client, the Symfony's testing client doesn't support JavaScript or taking screenshots, but
+it is super-fast!
+
+Alternatively (and even for non-Symfony apps), Panthère can also leverage the [Goutte](https://github.com/FriendsOfPHP/Goutte)
+web scrapping library. Goutte is an intermediate between the Symfony's test client and the Panthère one: it sends real HTTP
+requests, is fast and can browse any webpage, not only the ones of the application under test.
+But, because it is entirely written in PHP, Goutte doesn't support JavaScript and other advanced features.
+
+The fun part is that the 3 libraries implement the exact same API, so you can switch from one to another just by calling
+the appropriate factory method, and find the good trade off for every single test case (do I need JavaScript, do I need
+to authenticate to an external SSO server, do I want to access the kernel of the current request...).
+
+```php
+<?php
+
+use Panthere\PanthereTestCase;
+
+class E2eTest extends PanthereTestCase
+{
+    public function testMyApp()
+    {
+        $symfonyClient = static::createClient(); // A cute kitty: the Symfony's functional test too
+        $goutteClient = static::createGoutteClient(); // An agile lynx: Goutte
+        $panthereClient = static::createGoutteClient(); // A majestic Panther
+
+        // Both Goutte and Panthère benefits from the built-in HTTP server
+
+        // enjoy the same API for the 3 felines
+        // $*client->request('GET', '...')
+
+        $kernel = static::createKernel(); // You can also access to the app's kernel
+
+        // ...
+    }
+}
+```
+
+## Features
+
+Unlike testing and web scrapping libraries you're used to, Panthère:
+
+* executes the JavaScript code contained in webpages
+* supports all everything that Chrome (or Firefox) implements
+* can take screenshots
+* can wait for the appearance of elements loaded asynchronously 
+* lets you run your own JS code or XPath queries in the context of the loaded page
+* supports custom [Selenium server](https://www.seleniumhq.org) installations
+* supports remote browser testing services including [SauceLabs](https://saucelabs.com/) and [BrowserStack](https://www.browserstack.com/)
+
+## Documentation
+
+Because Panthère implements the API of popular, it already has an extensive documentation:
+
+* For the `Client` class, read [the BrowserKit's documentation](https://symfony.com/doc/current/components/browser_kit.html)
+* For the `Crawler` class, read [the DomCrawler's documentation](https://symfony.com/doc/current/components/dom_crawler.html)
+* For Webdriver, read [the Facebook's PHP WebDriver documentation](https://github.com/facebook/php-webdriver)
+
+## Limitations
+
+The following features are not currently supported:
+
+* Crawling XML documents (only HTML is supported)
+* Updating existing documents (browsers are mostly used to consume data, not to create webpages)
+* Setting form values using the multidimensional PHP array syntax
+* Methods returning an instance of `\DOMElement` (because this library uses `WebDriverElement` internally)
+* Selecting invalid choices in select
+
+Pull Requests are welcome to fill the remaining gaps!
+
+## Credits
+
+Created by [Kévin Dunglas](https://dunglas.fr). Sponsored by [Les-Tilleuls.coop](https://les-tilleuls.coop).

bin/README.md

@@ -0,0 +1,3 @@
+# External Vendors
+
+Chromedriver: https://sites.google.com/a/chromium.org/chromedriver/downloads

composer.json

@@ -0,0 +1,40 @@
+{
+  "name": "dunglas/panthere",
+  "type": "library",
+  "description": "A browser testing and web scrapping library for PHP and Symfony.",
+  "keywords": ["scrapping", "E2E", "testing", "webdriver", "selenium", "symfony"],
+  "homepage": "https://dunglas.fr",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "Kévin Dunglas",
+      "email": "[email protected]",
+      "homepage": "https://dunglas.fr"
+    }
+  ],
+  "require": {
+    "php": ">=7.2",
+    "facebook/webdriver": "^1.5",
+    "symfony/browser-kit": "^4.0",
+    "symfony/process": "^4.0"
+  },
+  "autoload": {
+    "psr-4": { "Panthere\\": "src/" }
+  },
+  "autoload-dev": {
+    "psr-4": { "Panthere\\Tests\\": "tests/" }
+  },
+  "extra": {
+    "branch-alias": {
+      "dev-master": "1.0.x-dev"
+    }
+  },
+  "config": {
+    "sort-packages": true
+  },
+  "require-dev": {
+    "fabpot/goutte": "^3.2",
+    "phpunit/phpunit": "^7.0",
+    "symfony/framework-bundle": "^4.0"
+  }
+}

examples/basic.php

@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * This file is part of the Panthère project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+require __DIR__.'/../vendor/autoload.php';
+
+use Facebook\WebDriver\WebDriverBy;
+use Facebook\WebDriver\WebDriverExpectedCondition;
+use Panthere\Client;
+
+$client = new Client();
+$crawler = $client->request('GET', 'http://api-platform.com'); // Yes, this website is 100% in JavaScript
+
+$link = $crawler->selectLink('Support')->link();
+$crawler = $client->click($link);
+
+// Wait for an element
+$client->getWebDriver()->wait()->until(
+    WebDriverExpectedCondition::visibilityOfElementLocated(WebDriverBy::className('support'))
+);
+
+echo $crawler->filter('.support')->text();
+$client->getWebDriver()->takeScreenshot('screen.png');
+
+$client->stop();

phpunit.xml.dist

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- http://phpunit.de/manual/4.1/en/appendixes.configuration.html -->
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.3/phpunit.xsd"
+         backupGlobals="false"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+>
+    <testsuites>
+        <testsuite name="Project Test Suite">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist processUncoveredFilesFromWhitelist="true">
+            <directory>.</directory>
+            <exclude>
+                <directory>tests</directory>
+                <directory>vendor</directory>
+            </exclude>
+        </whitelist>
+    </filter>
+</phpunit>