Selenium/Ruby/Setup instructions

Setup
Warning: this page assumes to a great extent that you're comfortable at the command line; have an okay understanding of PHP, MediaWiki, and in some cases git; and are willing to do a little bit of hacking around to understand key Ruby things.

Before you get started, you really ought to read stuff on the Cucumber site, though. Cucumber is the major ATDD technology in use for browser testing for many MediaWiki developers.

User
Create an account on beta labs if you don't already have one.

Git
Create a Gerrit account. Creation of a GitHub account is optional, but recommended.

On Mac install GitHub for Mac. Run the GitHub app and at the Configure Git step of the startup wizard click Install Command Line Tools button.

On Ubuntu install git with.

On Windows install GitHub for Windows. After the installation a Git Shell shortcut will appear on your desktop, and that will open a command line shell with Git configured.

Setup MediaWiki-Vagrant virtual machine
Tested on OS X 10.8.4 and Ubuntu 13.04 64-bit.

The easiest way to set up a MediaWiki server against which to run Cucumber tests is to use the MediaWiki-Vagrant virtual machine. Additionally, install the latest version of XQuartz on your Mac OS X host operating system. After setting it up, you'll be able to access a MediaWiki web server from localhost:8080 with a browser on your host operating system. Your host operating system is in effect connecting to a web server inside the virtual machine.

Setup your computer
You will need a few things setup in order to run the browser tests for MediaWiki using your host operating system.

Browser
Install Firefox (if you do not already have it installed). Firefox is required for the browser automation tool Selenium.

Selenium
A web browser automation tool, Selenium is a Firefox add-on that allows you to automate actions within your browser. You don't necessarily need the add-on to actually run Cucumber tests, but it aids in the workflow of generating ATDD tests.

Install Selenium IDE from http://www.seleniumhq.org/projects/ide/

Ruby
To run the tests you will need Ruby. The easiest way to install Ruby on Linux/Unix/Mac is RVM and on Windows RubyInstaller.

Bundler

The use of the mediawiki-selenium gem pivotal to ATDD on MediaWiki is predicated on installation of the Bundler gem. After having installed RVM on your host operating system, cd down into vagrant/mediawiki using Terminal. You will be told at that point to use rvm to install a particular version of Ruby:

So run that command as told. This will download and setup Ruby at the appropriate version so that it can be used when in this directory. rvm nicely lets you run multiple version of Ruby. If you're wondering how Terminal knew to have you run that rvm command to get that particular version of Ruby, peek at. The Gemfile hints at the required Ruby version.

Now that you've obtained the version of Ruby needed for use while in this directory, install Bundler:

Now that you've setup Bundler, while still in vagrant/mediawiki, run the following command. This command will get the other gems needed for executing browser tests, such as mediawiki_api, mediawiki_selenium, and rubocop.

Code
If you want to understand how the gems retrieved by Bundler actually work, you will want to read their source code on https://rubygems.org/.

Before you start reading their source code, though, in all practicality you should first look at the documentation of Page Object first, as it's used heavily in the MediaWiki Cucumber browser tests.

Now that you have things installed
After going through all of this installation stuff, you are probably eager to actually see what Cucumber does. If you've followed the instructions you should be able to cd down into vagrant/mediawiki/tests/browser and run the following command.

When you run this command, Cucumber will spawn a Firefox browser and examine the links on the main page on en.wikipedia.beta.wmflabs.org...at least if there isn't something broken in the gem dependencies or some other quirk. Sometimes stuff gets out of sync, so sorry about that if it's the case.

If you wanted to run this test against a different domain name, as the mediawiki-selenium documentation recommends, you would need to change the  environment variable before running the cucumber test. For example, to run the test against your local MediaWiki-Vagrant instance you might use the following before running :

Warning: be careful when running tests against production! And to run the test against production, you might use the following:

Warning: be careful when running tests against production! Just saying. You really don't want to run tests that might change something significant on a production server, so make sure what you're doing is safe for the wiki against which you're running tests.

Setup for testing with other browsers
It is possible to run tests with other browsers (e.g., Chrome or the headless browser PhantomJS) by exporting the BROWSER environment variable.


 * Chrome
 * Install Chrome
 * Install ChromeDriver
 * PhantomJS
 * Install PhantomJS

Okay, now what?
So you may have gotten things working with the setup above. But if not, please visit the IRC channel #wikimedia-qa on freenode. Also, the QA mail list welcomes subscribers with questions.

Note also that some of the best places to see up-to-date working examples for Cucumber is actually in a number of MediaWiki extensions. For example, the MobileFrontend and Flow extensions have a number of tests in them. You will pretty much always find the Cucumber tests in the  directory of an extension. So you typically need to do stuff with RVM and Bundler as described above, but in each one of the  directories for each extension to account for the unique needs of the extensions' test scaffolding.

To some extent, you should be able to navigate the,   and   directories inside of the   folder to put together how Cucumber works for a given set of tests. You may be able to follow the examples from the extensions to even create your own tests. If you hit problems creating your own tests, you can always make small changes to the existing tests to learn how Cucumber behaves.

As mentioned earlier, read up on the Cucumber site for a fuller grounding in Cucumber. Note that there are also books on Cucumber available from numerous booksellers, in addition to a book from the author of the Page Object.