Merge pull request #142 from blinkreaction/develop

Release 1.4.1

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.4.1 (2016-07-01)
+
+- Hotfixes
+  - Addressed an issue with php5 vs php7 supervisord service name
+  - Account that winpty executable was renamed in 0.3.0 to "winpty.exe"
+  - Added ability to stop Drude system containers with dsh
+  - Stop docker daemon before running prerequsite updates on Ubuntu to prevent client-server difference error
+- Documentation updates
+  - Massive updates to [Behat docs](docs/behat.md)
+    - PHPStorm integration
+    - Use hosts's Selenium server and browsers 
+  - phpcs docs updates
+
+
 ## 1.4.0 (2016-06-10)
 
 - dsh v1.20.0

VERSION

@@ -1 +1 @@
-1.4.0
+1.4.1

bin/dsh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-DSH_VERSION=1.20.0
+DSH_VERSION=1.20.3
 
 # Console colors
 red='\033[0;91m'
@@ -455,6 +455,23 @@ _stop_containers ()
 		# stop all but system containers (--label "group=system")
 		docker ps --format '{{.ID}} {{.Label "group"}}' | grep -v 'system' | xargs docker stop
 	fi
+	if [[ "$1" == "proxy" ]] ; then
+		echo-green 'Stopping Drude HTTP/HTTPS reverse proxy service...'
+		docker stop vhost-proxy
+		return
+	fi
+
+	if [[ "$1" == "dns" ]] ; then
+		echo-green 'Stopping Drude DNS service...'
+		docker stop dns
+		return
+	fi
+
+	if [[ "$1" == "ssh-agent" ]] ; then
+		echo-green 'Stopping Drude ssh-agent service...'
+		docker stop ssh-agent
+		return
+	fi
 	docker_compose stop
 }
 
@@ -701,7 +718,7 @@ up ()
 down ()
 {
 	check_dsh_environment
-	_stop_containers $@
+	_stop_containers "$@"
 }
 
 # Stop Vagrant box
@@ -914,16 +931,17 @@ install_ubuntu ()
 	fi
 
 	echo-green "Installing Docker..."
-	curl -sSL https://get.docker.com/ | sh && \
-	sudo usermod -aG docker $(whoami) && \
+	sudo service docker stop && \
+		curl -sSL https://get.docker.com/ | sh && \
+		sudo usermod -aG docker $(whoami)
 	sudo docker version
-	if_failed "Docker installation/upgrade failed."
+	if_failed "Docker installation/upgrade has failed."
 
 	echo-green "Installing Docker Compose..."
 	sudo curl -L https://github.com/docker/compose/releases/download/1.7.1/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose && \
 	sudo chmod +x /usr/local/bin/docker-compose && \
 	docker-compose --version
-	if_failed "Docker Compose installation/upgrade failed."
+	if_failed "Docker Compose installation/upgrade has failed."
 
 	echo-green "Adding a subnet for Drude..."
 	# Make sure we don't do this twice
@@ -1249,8 +1267,10 @@ _run ()
 		# Workaround - run docker exec via winpty (console.exe) to get a tty console in cygwin.
 		if is_binary_found 'console'; then
 			winpty_cmd='console'
+		elif is_binary_found 'winpty'; then
+			winpty_cmd='winpty'
 		else
-			echo-red 'Winpty (console.exe) binary missing.'
+			echo-red 'Winpty binary is missing.'
 			echo 'Run "dsh install prerequisites" to install it.'
 			exit 1
 		fi
@@ -1523,7 +1543,11 @@ _set_cli_uid ()
 			echo-green "Reseting permissions on /var/www..."
 			docker exec -u root $(get_container_id cli) chown -R docker:users /var/www
 			echo-green "Restarting php daemon..."
-			docker exec -u root $(get_container_id cli) supervisorctl restart php5-fpm
+			# TODO: Remove. This code is to support legacy cli image version, where php5-fpm service name was used.
+			local php_service='php-fpm';
+			local local res=$(docker exec $(get_container_id cli) grep "program:php5-fpm" /etc/supervisor/conf.d/supervisord.conf)
+			if [[ "$res" != '' ]]; then php_service='php5-fpm'; fi
+            docker exec -u root $(get_container_id cli) supervisorctl restart $php_service
 		else
 			echo-green "Container and host uids already match ($container_uid)."
 		fi

docs/behat.md

@@ -10,7 +10,7 @@ Drude expects your Behat tests to be in `tests/behat` folder of the project repo
 >       \_ composer.json
 >       \_ composer.lock
 
-See [drude-testing](https://github.com/blinkreaction/drude-testing) repo for a good working example. This repo is used for automated tests of Drude builds.
+See [Drupal 7 sample project](https://github.com/blinkreaction/drude-d7-testing) repo for a working example.
 
 ## Docker profile example
 
@@ -52,3 +52,207 @@ Tests can be launched with `dsh` (Drude Shell):
     dsh behat
 
 This will download composer dependencies and run behat with the docker profile.
+
+## Behat (goutte-driver)
+
+Basic configuration (see [behat.common.yml](https://github.com/blinkreaction/drude-d7-testing/blob/master/tests/behat/behat.common.yml)) uses goutte as the default driver. Goutte is a very basic browser emulator. It is much faster than real browsers, but also very limited. It can make HTTP requests, but does not parse CSS, execute JS or do any rendering.
+
+Goutte can be used in many cases and does not require additional configuration/installation.
+
+## Behat (selenium2-driver)
+
+If your tests require javascript support, selenium2-driver should be used. You can set selenium2-driver as the default one.  
+Selenium2 works with real browsers, using them as zombies for testing purposes. You get a standard, feature reach, real browser, with CSS styling, JS and AJAX execution - all supported out of the box.
+
+The easiest way to enable Selenium support is to use stock Selenium docker images.  
+To do this, update `docker-compose.yml` file in your project folder as follows.
+
+```yml
+# selenium2 node
+# Uncomment the service definition section below and the link in the web service above to start using selenium2 driver for Behat tests requiring JS support.
+browser:
+  hostname: browser
+  image: selenium/standalone-chrome
+  ports:
+    - "4444"
+  environment:
+    - DOMAIN_NAME=drude-d7-testing.browser.docker
+```
+
+You can also use Firefox image: `selenium/standalone-firefox`
+
+After updating `docker-compose.yml` you have to tell Behat to use Selenium.  
+Add your selenium configuration in `behat.yml` (environment variable `DOMAIN_NAME` is used as `selenium2 wd_host`).
+
+Example:
+
+```yml
+# Docker profile.
+# For use inside the CLI container in Drude.
+docker:
+  extensions:
+    Behat\MinkExtension:
+      # URL of the site when accessed inside Drude.
+      base_url: http://drupal7.drude
+      selenium2:
+        wd_host: http://drude3-d7-testing.browser.docker:4444/wd/hub
+      # Stick with chrome by default. It's 2x faster than firefox or phantomjs (your results may vary).
+      browser_name: chrome
+    Drupal\DrupalExtension:
+      drupal:
+        # Site docroot inside Drude.
+        drupal_root: /var/www/docroot
+      drush:
+        # Site docroot inside Drude.
+        root: /var/www/docroot
+```
+
+## Behat (selenium2-driver) - using VNC
+
+If you use Selenium with a browser in a container, you can receive test screenshots but you cannot see the browser itself. Sometimes it is very useful to watch tests running in the browser (e.g. when you are creating a new test and want to see how it performs).  
+In such cases [VNC](https://en.wikipedia.org/wiki/Virtual_Network_Computing) can be used.
+
+1. Install VNC client on your computer (there are many version for all platforms).
+2. Update `docker-compose.yml` file in your project folder:
+
+```yml
+# selenium2 node
+# Uncomment the service definition section below and the link in the web service above to start using selenium2 driver for Behat tests requiring JS support.
+browser:
+  hostname: browser
+  image: selenium/standalone-chrome-debug
+  ports:
+    - "4444"
+    - "5900:5900"
+  environment:
+    - DOMAIN_NAME=drude-d7-testing.browser.docker
+```
+You have to use `selenium/standalone-chrome-debug` or `selenium/standalone-firefox-debug` images. They both include a VNC server.  
+Use `localhost:5900` as the host and `secret` as the password in your VNC client.  
+Now if you connect with the VNC client and run behat test, you will be able to see tests running in the browser inside the container.
+
+Note: If you are working with several project concurrently, it is a good idea to have a separate port per project (e.g. `5901:5900`, `5902:5900`, etc.)
+
+## Integration with PhpStorm
+
+It is possible to connect PhpStorm with the `cli` container and run behat tests from within PhpStorm.  
+PhpStorm uses ssh to connect to and use remote interpreters and tools.  
+
+1. Add the following line in `docker-compose.yml` to expose ssh-server in the `cli`container:
+
+    ```yml
+   cli:
+     ...
+     ports:
+       - "2221:22"
+     ...
+    ```
+2. Update container configuration with `dsh up`.
+3. You should now be able to connect to the `cli` container via ssh. Use username `docker` and pasword `docker`:
+
+    ```
+    ssh docker@localhost -p 2223
+    ```
+
+Note: If you are working with several project concurrently, it is a good idea to have a separate port per project (e.g. `2222:22`, `2223:22`, etc.)
+
+### Add new deployment server
+
+Open settings (menu item *File->Settings...*). In the opened window on the left side select item *Build, Execution, Deployment->Deployment*:
+
+![](img/behat-phpstorm-deployment-configure.png)
+
+Create new SFTP connection and fill-out the form. Don't forget to fill-out *Web server root URL*.  
+Press *Test SFTP connection...* button and if everything is ok, you will see that test is successful.
+
+On the second tab you should to check and correct mapping:
+
+![](img/behat-phpstorm-deployment-configure-mapping.png)
+
+Local path is path to your project on the host machine. Deployment path is `/var/www`
+
+### Add a new PHP interpreter
+
+Open settings (menu item *File->Settings...*). In the opened window on the left side select item *Languages & Frameworks->PHP*:
+
+![](img/behat-phpstorm-PHP-configuration.png)
+
+To add a new interpreter click on **...** button on *Interpreter:* line.
+
+![](img/behat-phpstorm-PHP-configuration-deployment.png)
+
+In the opened window add a new interpreter and choose **Deployment configuration** option and deployment server from select list (it should be server from previous step).
+
+### Add Behat interpreter configuration
+
+Open settings (menu item *File->Settings...*). In the opened window on the left side select item *Languages & Frameworks->PHP->Behat*:
+
+![](img/behat-phpstorm-PHP-Behat-configuration.png)
+
+Add a new PHP interpreter for Behat (it should be the interpreter from previous step).
+
+Path to Behat is the path in the `cli` container - ``/var/www/tests/behat/bin/behat`
+
+Default configuration file: `/var/www/tests/behat/behat.yml`
+
+Check that your `behat.yml` contains `wd_host` for selenium in `Behat\MinkExtension` part:
+
+![](img/behat-behat-yml.png)
+
+It should be the same as in `behat.common.yml` for `docker` part.
+
+### Add Behat debug configuration
+
+Open *Run/Debug Configurations* (menu item *Run->Edit Configurations...*). In the opened window on the left side add new Behat configuration:
+
+![](img/behat-run-debug-configuration.png)
+
+Choose Test Runner option *Defined in the configuration file*.
+
+### Run tests
+
+On the PhpStorm panel choose Behat debug configuration and run it:
+
+![](img/behat-run-tests.png)
+
+If everything is ok, you will see a window with tests result (all tests are run in this case):
+
+![](img/behat-run-window.png)
+
+You can re-run any scenario from this window. If you click on scenario or test, PhpStorm will open window with this scenario/test.
+
+You can also open folder with Behat features (`tests/behat/features` directory in your project) and
+run any feature tests by right clicking on it and choosing **Run 'feature-name'** option.
+
+![](img/behat-test-features.png)
+
+## Using host selenium2-driver
+
+You can use selenium from your host machine instead of the selenium in a container.
+
+Selenium Standalone Server is available [here](http://www.seleniumhq.org/download/).  
+WebDriver for Chrome is available [here](https://sites.google.com/a/chromium.org/chromedriver/downloads).
+
+Run selenium with Chrome webdriver:
+
+> java -jar selenium-server-standalone-2.53.0.jar -Dwebdriver.chrome.driver=/path/to/webdriver/chromedriver
+
+By default it is running on port `4444`, which can be verified by openning `http://localhost:4444/wd/hub/static/resource/hub.html` in a browser.
+
+Update `behat.yml` (set `wd_host` to point to the host machine):
+
+```yml
+# Local overrides to the default profile
+default:
+  extensions:
+    Behat\MinkExtension:
+      # URL of the site when accessed locally.
+      base_url: http://drupal7.drude
+      # Configure browser to be used. Browser must be available on wd_host.
+      browser_name: chrome
+      selenium2:
+        wd_host: http://192.168.10.1:4444/wd/hub/static/resource/hub
+...
+```
+
+`192.168.10.1` is your machine's IP in Drude subnet.

docs/phpcs.md

@@ -6,17 +6,18 @@ phpcs and phpcbf are readily available in up-to-date version of cli container.
 
 It's recommended to see how to [extend dsh with custom commands](custom-commands.md) first.
 
-From your project's root folder (where `.drude` is):
-
-1. `mkdir -p .drude/commands`  
-2. `cd .drude/commands`  
-3. `curl https://raw.githubusercontent.com/blinkreaction/drude/develop/examples/.drude/commands/phpcs -ko phpcs`
-4. `curl https://raw.githubusercontent.com/blinkreaction/drude/develop/examples/.drude/commands/phpcs.1 -ko phpcs.1`
-5. `chmod +x phpcs`
-6. `cd ../..`
-7. `dsh phpcs docroot/sites/all/modules/custom` or any path you want to run sniffer against. See `dsh help phpcs`
-8. Modify `.drude/commands/phpcs` script as you need and re-run any time with `dsh phpcs`
-9. In the same way you can create script for phpcbf as it uses the same set of parameters
+From your project's root folder (where `.drude` folder is):
+
+1. Download example `phpcs` command
+
+    ```
+    mkdir -p .drude/commands
+    curl https://raw.githubusercontent.com/blinkreaction/drude/develop/examples/.drude/commands/phpcs -ko .drude/commands/phpcs
+    chmod +x .drude/commands/phpcs
+    ```
+2. Use as `dsh phpcs docroot/sites/all/modules/custom` or any path you want to run sniffer against. See `dsh help phpcs`
+3. Modify `.drude/commands/phpcs` script as you need
+4. In the same way you can create script for `phpcbf` as it uses the same set of parameters
 
 ## Manual usage