Le vitrail Ruby est disponible en précommande!!! Réservez le vôtre.

Voir en Markdown

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 ?

  1. Ajoutez gem "rspec-rails", group: [:development, :test] à votre Gemfile, puis lancez bundle install.
  2. Lancez rails generate rspec:install : cette commande crée le dossier spec/, les fichiers spec_helper.rb et rails_helper.rb, et le fichier .rspec.
  3. Lancez vos tests avec bundle exec rspec.

Quelles sont les conventions de RSpec ? Chaque fichier testé a son fichier _spec.rb (user.rb est testé par user_spec.rb), et le dossier spec/ reproduit l’arborescence du dossier app/. Seule exception : l’équipe de RSpec recommande de tester les contrôleurs dans spec/requests/ plutôt que dans spec/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.

ruby
  # Gemfile

  gem "rspec-rails", group: [:development, :test]

Installez la gem.

terminal
  bundle install

Générez la configuration de RSpec et faites de RSpec le framework de test de votre application.

terminal
  rails generate rspec:install

Maintenant, lancez vos migrations et préparez votre base de données de test.

terminal
  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.rb est testé par users_controller_spec.rb
  • Le modèle user.rb est testé par user_spec.rb
  • Le job user_notification_job.rb est testé par user_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.

terminal
  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 :

terminal
  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 :

ruby
  # 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.rb se trouve à la racine du dossier spec. RSpec est configuré d’office, donc pas besoin de vous en soucier.

  • RSpec est 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.

  • .describe est une méthode définie sur le module RSpec. 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èle User.

Le code ci-dessous vient du dépôt de RSpec.

ruby
  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.

  • User est la classe que vous testez. Elle est passée en argument à la méthode .describe.

  • do ... end est le bloc dans lequel vous écrivez vos tests. Ils seront passés en second argument à la méthode .describe (voir &example_group_block ci-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

  1. Merci à @Benoit de me l’avoir fait remarquer ! ↩

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.