Introduction
Ce tutoriel va vous guider dans l'installation et la configuration d'un environnement de test d'acceptance sur un projet PHP.
Pour cela nous utiliserons plusieurs gems ruby, notamment cucumber, webrat et selenium-client, et écrirons nos scénarios sous forme de features cucumber.
Voici un exemple :
Feature: Example Features
Scenario: I am connected and i visit my page
Given I am connected as "username password"
When I visit "home page"
Then I should see "Hello username"
L'avantage de cette syntaxe est qu'elle reste très lisible pour le communs des mortels, pas besoin de mettre le nez dans le code ruby pour comprendre ce que le test est sensé faire.
Chaque "phrase" de ce scénario fait référence à des "steps" (étapes) qui sont en réalité les actions utilisateurs nécessaires pour effectuer l'action correspondante dans l'interface utilisateur.
Les actions utilisateurs peuvent être déclenchés par les librairies webrat et selenium-client.
Webrat est plus particulièrement adapté aux interactions ne faisant pas intervenir de javascript alors que selenium-client saura les interpréter correctement.
Installation
Pour cet exemple nous utiliserons un système debian.
Commençons par installer rubygems et les gems nécessaires.
aptitude install rubygems
gem install rspec cucumber webrat selenium-client
Pour pouvoir exécuter les binaires packagés avec les gems en ligne de commande vous devrez ajouter le chemin vers ces binaires à votre PATH :
export PATH=$PATH:$HOME/.gem/ruby/1.8/bin
Pour pouvoir utiliser selenium, il faut démarrer un serveur selenium-rc (ie: remote control). Le démarrage du serveur selenium est fait automatiquement par webrat, en revanche la version utilisée m'a posé plusieurs problèmes avec les versions récentes de firefox. Je vous conseille donc de récupérer la dernière version stable à l'adresse suivante : http://seleniumhq.org/download/ (1.0.3 au 28 juin 2010).
Il suffira ensuite de remplacer le fichier ~/.gem/ruby/1.8/gems/webrat-0.7.1/vendor/selenium-server.jar par la version que vous venez de télécharger.
wget http://selenium.googlecode.com/files/selenium-remote-control-1.0.3.zip
unzip selenium-remote-control-1.0.3.zip
cp selenium-server-1.0.3/selenium-server.jar $GEM_HOME/webrat-0.7.1/vendor/selenium-server.jar
(Remplacez $GEM_HOME par le répertoire d'installation de vos gems.)
Voila, nous allons pouvoir écrire nos scénarios.
Note pour iceweasel : vous devrez ajouter le chemin vers le dossier contenant le fichier application.ini de iceweasel à votre PATH, sinon iceweasel ne démarrera pas.
export PATH=$PATH:/usr/lib/iceweasel
Configuration
Maintenant que l'installation est terminée, il va falloir configurer un environnement web pour lancer nos tests.
Cet environnement peut être votre environnement de développement, la démarche est spécifique à chaque projet donc je ne m'attarderai pas sur ce point.
Passons maintenant à la configuration de notre environnement de test.
Créons un répertoire features à la racine de votre projet. Ce répertoire aura la structure suivante :
$: features % tree
.
├── fixtures
│ └── image.jpg
├── home.feature
├── step_definitions
│ ├── user_steps.rb
│ └── webrat_steps.rb
└── support
├── env.rb
├── paths.rb
└── selenium.rb
3 directories, 10 files
Voyons plus précisément quel est le rôle de chacun de ces répertoires.
Le racine du répertoire features contiendra vos "features" cucumber, c'est à dire les scénarios.
Le répertoire fixtures contiendra les fichiers utilisés dans vos scénarios (par exemple une image à envoyer dans un champs file).
Le répertoire step_definitions stocke les définitions des étapes utilisées dans les scénarios. Il contiendra généralement un fichier par type d'action, dans notre exemple nous aurons deux fichiers :
- webrat_steps : les actions communes, ce fichier peut être trouvé dans le code du gem webrat (templates/skeleton/step_definitions/webrat_steps.rb.erb). Il contient, entre autre, les helpers communs à tout type de projet web (visiter une page, vérifier qu'elle contient un texte ou une balise, ...)
- user_steps : les actions utilisateurs (se connecter, poster un commentaire...)
Le répertoire support est le répertoire de configuration, il doit contenir les fichiers suivants :
- env.rb, le fichier de configuration de webrat
- path.rb, c'est le fichier qui définit la correspondance entre les routes nommées que vous appellerez et les véritables URL à envoyer au navigateur (par exemple : "home page" => "/")
- selenium.rb, c'est le fichier où vous pourrez factoriser les actions spécifiques à selenium.
Webrat
Par défaut webrat n'utilise pas selenium pour controler le navigateur mais mechanize, voici un exemple de configuration à placer dans le fichier support/env.rb pour spécifier l'utilisation de selenium
(on notera au passage que l'adresse de votre environnement web de test sera configurée via une variable d'environnement pour plus de simplicité) :
unless ENV['CUCUMBER_HOST']
raise 'You must set CUCUMBER_HOST environment variable with the name of your host used to run cucumber features'
end
RSpec
require 'spec/expectations'
Webrat
require 'webrat'
require 'test/unit/assertions'
World(Test::Unit::Assertions)
Webrat.configure do |config|
#config.mode = :mechanize
config.mode = :selenium
config.application_framework = :external
config.application_address = ENV['CUCUMBER_HOST']
config.application_port = "80"
end
World do
session = Webrat::Session.new
session.extend(Webrat::Methods)
session.extend(Webrat::Matchers)
session
end
Routes nommées
Ensuite vous devez spécifier les routes pouvant être appelées dans vos tests ainsi que leurs versions texte.
En effet, dans les scénarios cucumber, une correspondance littéraire sera beaucoup plus lisible que les URL brutes.
Voici un exemple de configuration de ces routes qui seront stockées dans le fichier support/path.rb :
module NavigationHelpers
def path_to(page_name)
case page_name
when /home/
'/'
when /accueil/
'/accueil'
when /login/
'/identification'
else
raise "Can't find mapping from \"#{page_name}\" to a path.\n" +
"Now, go and add a mapping in #{FILE}"
end
end
end
World(NavigationHelpers)
Helpers
Dans le but d'avoir des scénarios les plus clairs et compréhensibles possibles, nous allons définir quelques helpers.
Tous les fichiers présents dans le répertoire support seront chargés par cucumber, dans notre exemple nous allons ajouter un fichier selenium.rb pour les actions relatives à selenium.
Voici donc le fichier support/selenium.rb :
def wait_for_ajax(timeout=50000, request_count = 1)
request_count.times do |index|
selenium.wait_for_ajax :javascript_framework => :jquery
end
end
def wait_for_gritter
selenium.wait_for_element "gritter-notice-wrapper"
end
Vous pourrez faire de même pour les autres librairies dont vous pourriez avoir besoin.
Écrire des scénarios
Les scénarios cucumber sont définis par plusieurs mots-clés : Given, When, Then et And.
- Given définit le contexte de départ.
- When définit une action utilisateur.
- Then définit une assertion, le résultat à obtenir.
- And est un mot de liaison permettant de rendre encore plus lisible le scénario, il a le même rôle que le mot-clé de la ligne précédente.
Certaines d'actions seront appelées dans plusieurs scénarios, d'où le besoin de factorisation de ce code.
Par exemple, l'action Given I am connected as "username password" sera très certainement présentes dans 75% de vos tests.
Pour éviter de répéter les X actions nécessaires pour se connecter, nous allons factoriser cela dans les étapes du répertoire step_definitions.
Voici un exemple d'étapes correspondant à l'exemple suivant :
Given /^I am connected as "(\w)\ (\w)"$/ do |login, password|
visit path_to "login"
fill_in 'login', :with => login
fill_in 'password', :with => password
click_button "login"
wait_for_ajax # if your form is submitted via ajax
end
Désormais dans chacun de nos test nous pourront appeler : Given I am connected as "MyUsername MyPassword".
Feature: Example Features
Scenario: I am connected and i visit my page
Given I am connected as "username password"
When I visit "home page"
Then I should see "Hello username"
Run !
Maintenant que vous avez écrit votre premier scénario, placez-vous à la racine de votre projet et lancer la commande suivante :
CUCUMBER_HOST=YOUR_HOST cucumber
(Remplacez YOUR_HOST par l'adresse de votre environnement de test.)
Vous devriez voir votre navigateur réaliser votre scénario... sans les mains !
