And just to be nice, here is an English version of this tutorial…
This tutorial will guide you through installing and configuring an acceptance test environment for PHP project. For this we use several ruby gems, including cucumber, webrat and selenium-client, and write our scripts as cucumber features. Here's an example:
The advantage of this syntax is that it remains very readable for the mere mortals, no need to delve into the ruby code to understand what the test is supposed to do.
Each "sentence" in this scenario refers to a step which is the user actions necessary to perform that action in the user interface.
For this example we will use a debian system.
Let's start by installing rubygems and the needed gems.
To run the binaries packaged with gems from the command line you must add the path to these binaries to your
To use selenium, start a selenium-rc server (ie: remote control). Starting selenium server is done automatically by webrat, however the version used caused me many problems with recent versions of Firefox. I suggest you grab the latest stable version at the following address:
http://seleniumhq.org/download/ (1.0.3 au 28 juin 2010).
It is sufficient to replace the file
~/.gem/ruby/1.8/gems/webrat-0.7.1/vendor/selenium-server.jar with the version you just downloaded.
(Remplace $GEM_HOME by your gems installation directory.)
Voila, now we can start writing our scenarios.
Note for iceweasel: you must add the path to the folder containing the iceweasel
application.ini file to your
Now that the installation is complete, we will have to configure a web environment to run our tests. This environment can be your development environment, the approach is specific to each project so I will not dwell on this point.
Let's turn to the configuration of our test environment.
We will create a directory
features in the root of your project. This directory has the following structure:
Let us see more precisely what role each of these directories is.
The root of the
features will contain your cucumber "features", ie scenarios.
fixtures contains the files used in your scripts (eg an image to upload to a file field).
step_definitions stores definitions of steps used in the scenarios. It will usually contain a file per action type, in our example we have two files:
webrat_steps: Common actions, this file can be found in the code of the webrat gem (
templates/skeleton/step_definitions/webrat_steps.rb.erb). It contains, among other common helpers to any type of web project (visit a page, check that it contains a text or an html tag, ...)
user_steps: the user actions (login, post a comment ...)
support is the configuration directory, it must contain the following files:
env.rb, the webrat configuration file
path.rb, is the file that defines the correspondence between the named routes that you call and the actual URL to send to the browser (example: "home page" => "/")
selenium.rb, is the file where you can refactor out the specific actions to selenium.
By default webrat does not use selenium to control the browser but uses instead mechanize, here is a sample configuration file to be placed in the support/env.rb to specify the use of selenium: (Note in passing that the address of your test web environment will be configured via an environment variable for simplicities sake):
Next you must specify the routes that can be called in your tests and their text versions. Indeed, in cucumber scenarios , a literary correspondence will be much more readable than the raw URL. Here is an example configuration of these routes to be stored in the file
In order to have the scenarios as clear and as understandable as possible, we will define some helpers.
All files in the
support will be loaded by cucumber in our example we will add a file selenium.rb for actions related to selenium.
Here is the
You can do the same for other libraries you might need.
The scenarios are defined by several cucumber keywords: Given, When, Then and And.
Givendefines the initial context
Whendefines user actions
Thendefines an assertion, the expected result
Andis an association word to make the scenatio more readable, it has the same role as the keyword of the previous line.
Some actions will be called in several scenarios, hence the need for code refactoring.
For example, the action
Given I am connected as "username password" will certainly be present in 75% of your tests.
To avoid repeating the X actions necessary to connect, we refactored that in the steps of the
Here is an example of steps for the following example:
Now in each of our tests we can call:
Given I am connected as "MyUsername MyPassword".
Now that you've written your first scenario, go to the root of your project and run the following command:
YOUR_HOST by your test enviroment address.)
You should see your browser run your script … hands free!