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 !

• Kevin Lacointe's blog