Débuter avec RSpec : installation, conventions et structure des fichiers
TL;DR : C’est quoi RSpec ?
RSpec est un framework de test pour Ruby et Ruby on Rails, centré sur le comportement attendu du code : pour telle entrée, j’attends telle sortie. Créé en 2005 par Steven Baker, RSpec est, avec Minitest, l’un des deux frameworks de test les plus utilisés de l’écosystème Ruby. Il permet de tester la quasi-totalité d’une application : modèles, requêtes, jobs, mailers, etc.
Comment installer RSpec dans une application Rails ?
- Ajoutez
gem "rspec-rails", group: [:development, :test]à votre Gemfile, puis lancezbundle install.- Lancez
rails generate rspec:install: cette commande crée le dossierspec/, les fichiersspec_helper.rbetrails_helper.rb, et le fichier.rspec.- Lancez vos tests avec
bundle exec rspec.Quelles sont les conventions de RSpec ? Chaque fichier testé a son fichier
_spec.rb(user.rbest testé paruser_spec.rb), et le dossierspec/reproduit l’arborescence du dossierapp/. Seule exception : l’équipe de RSpec recommande de tester les contrôleurs dansspec/requests/plutôt que dansspec/controllers/.
Quand on débute en programmation, pas facile de savoir quoi tester, comment tester, et pourquoi tester. Vous avez sûrement entendu dire que le TDD (pour Test Driven Development) est LA bonne pratique par excellence. Mais au début, difficile de savoir ce que votre code doit faire avant même de l’écrire.
Les tests révèlent leur potentiel avec la pratique.
Quand j’ai commencé à programmer, je recopiais les tests des autres parce que, bon, il fallait bien commencer quelque part. Mais après quelques mois, mes tests ont commencé à révéler des edge cases, des bugs potentiels qui m’avaient échappé.
Commençons cette série sur les fondamentaux de RSpec par une introduction à RSpec : comment installer RSpec dans votre application Rails, quelle convention de nommage suivre et comment structurer vos fichiers de test.
Comment ajouter RSpec à votre application Rails ?
L’équipe de RSpec maintient la gem rspec-rails qui facilite l’utilisation du framework dans les applications Rails.
D’abord, ajoutez RSpec à votre Gemfile.
# Gemfile
gem "rspec-rails", group: [:development, :test]
Installez la gem.
bundle install
Générez la configuration de RSpec et faites de RSpec le framework de test de votre application.
rails generate rspec:install
Maintenant, lancez vos migrations et préparez votre base de données de test.
rails db:migrate && rails db:test:prepare
Et voilà ! Vous pouvez maintenant lancer vos tests en tapant rspec spec dans votre terminal. spec est le dossier où vous créerez vos fichiers de test.
La convention de nommage de RSpec
La convention de nommage de RSpec est simple :
- Le contrôleur
users_controller.rbest testé parusers_controller_spec.rb - Le modèle
user.rbest testé paruser_spec.rb - Le job
user_notification_job.rbest testé paruser_notification_job_spec.rb - etc.
Organisez votre dossier spec
Pour que RSpec et Rails fonctionnent ensemble, reproduisez l’arborescence de votre dossier app dans le dossier spec.
my_app_directory
|
|- app
| |
| |- models
| |
| |- user.rb
|
|- spec
|
|- models
|
|- user_spec.rb
Vos tests pourraient fonctionner, en partie, même si vous mettiez tous vos fichiers de test à la racine de spec. Mais RSpec essaie de deviner le type de test à partir de l’arborescence. Autant suivre cette convention.
Juste une subtilité : l’équipe de RSpec déconseille d’utiliser spec/controllers.
app/controllers/users_controller.rb est ainsi testé dans spec/requests/users_controller_spec.rb plutôt que dans spec/controllers/users_controller_spec.rb.
Pourquoi ? Parce que tester les requêtes vous permet de tester le comportement des actions de votre contrôleur à travers toute la stack (routage, requête, réponse, etc.), plutôt que de tester le contrôleur isolément1.
Pour tester vos contrôleurs, la structure de votre dossier ressemble donc à ça :
my_app_directory
|
|- app
| |
| |- controllers
| |
| |- users_controller.rb
|
|- spec
|
|- controllers ❌
|
|- requests ✓
|
|- users_controller_spec.rb
La structure de vos fichiers RSpec
Imaginons que nous voulions tester notre modèle User. Notre fichier ressemblera à ça :
# spec/models/user_spec.rb
require 'rails_helper'
RSpec.describe User do
# test stuff
end
Regardons chaque élément de plus près pour mieux comprendre ce qui se passe.
-
require 'rails_helper'charge la configuration de RSpec.rails_helper.rbse trouve à la racine du dossierspec. RSpec est configuré d’office, donc pas besoin de vous en soucier. -
RSpecest le module principal de tout le code RSpec. Il encapsule et charge beaucoup de choses à l’instanciation : la configuration, le DSL des expectations, les exemples, etc. Vous pouvez jeter un œil au code ici. -
.describeest une méthode définie sur le moduleRSpec. Elle regroupe vos tests autour d’une abstraction commune : une classe, une requête, etc. Dans l’exemple ci-dessus, notre abstraction est le modèleUser.
Le code ci-dessous vient du dépôt de RSpec.
def self.expose_example_group_alias(name)
return if example_group_aliases.include?(name)
example_group_aliases << name
(class << RSpec; self; end).__send__(:define_method, name) do |*args, &example_group_block|
group = RSpec::Core::ExampleGroup.__send__(name, *args, &example_group_block)
RSpec.world.record(group)
group
end
expose_example_group_alias_globally(name) if exposed_globally?
end
C’est un peu difficile à lire à cause de la métaprogrammation, mais l’idée principale est la suivante : ce code définit describe comme une méthode du module RSpec. Quand vous appelez RSpec.describe User do ... end, elle transmet vos arguments (User) et votre bloc à RSpec::Core::ExampleGroup.describe, qui en construit un groupe de tests, puis elle enregistre ce groupe pour que RSpec puisse l’exécuter.
-
Userest la classe que vous testez. Elle est passée en argument à la méthode.describe. -
do ... endest le bloc dans lequel vous écrivez vos tests. Ils seront passés en second argument à la méthode.describe(voir&example_group_blockci-dessus).
J’espère que ces explications vous aideront à mieux comprendre le fonctionnement de RSpec. La prochaine fois, nous écrirons nos premiers tests.
À bientôt,
Rémi - @remi@ruby.social
Version française de l'article anglais An introduction to RSpec: how to install RSpec, naming convention and basic files structure. Première traduction par Opus 5.5. Revue, éditée et mise à jour par mes soins.