Capybara : tests d'acceptation Ruby pour applis web

Qu'est-ce que Capybara ?

Capybara est une bibliothèque Ruby pour les tests d'acceptation d'applications web. Elle offre un DSL pour visiter des pages, remplir des formulaires, cliquer sur des liens et vérifier ce qui est affiché, et fonctionne avec un pilote simple dans le même processus ou avec un vrai navigateur. Ce n'est pas un lanceur de tests : on l'utilise dans RSpec, Minitest ou Cucumber. Les tests système de Rails s'appuient dessus.

Comment fonctionne Capybara

Votre test décrit ce que fait un utilisateur, et Capybara confie chaque étape à un pilote. Le pilote par défaut, RackTest, est du Ruby pur, n'a pas besoin de serveur et ne gère pas JavaScript : il est rapide mais n'exécute pas de scripts. Pour les pages qui dépendent de JavaScript, on passe à un pilote de navigateur. Capybara.javascript_driver vaut :selenium par défaut, et un test l'utilise s'il porte le tag js: true dans RSpec ou @javascript dans Cucumber. Cuprite est une gem à part qui pilote Chrome via le Chrome DevTools Protocol et n'a besoin ni de Selenium ni de ChromeDriver.

Exemple

require 'rails_helper'

RSpec.describe 'Signup', type: :system do
  it 'creates an account' do
    visit '/signup'
    fill_in 'Email', with: 'alice@example.com'
    fill_in 'Password', with: 'secret123'
    click_button 'Create account'

    expect(page).to have_content 'Welcome, alice'
  end
end

Il n'y a aucun sleep. Les finders et matchers comme have_content réessaient jusqu'à réussir ou jusqu'à la fin du délai, et reviennent aussitôt en cas de succès. La valeur par défaut de Capybara.default_max_wait_time est de 2 secondes ; augmentez-la avec Capybara.default_max_wait_time = 5 si une page est vraiment lente. Les tests système de Rails utilisent par défaut Selenium avec Chrome, et driven_by permet de choisir un autre pilote.

Erreurs fréquentes

• Attentes fixes. Elles ralentissent la suite et échouent quand même sur une exécution lente. Utilisez un matcher qui attend plutôt que sleep.
• Vérifications négatives qui n'attendent pas. Préférez expect(page).to have_no_content(...) à !page.has_content?(...), qui abandonne au premier coup d'œil.
• Attendre du JavaScript de RackTest. Si un clic ne fait rien, vérifiez que le test tourne sur un pilote JavaScript.
• Sélecteurs fragiles. Préférez les libellés et le texte visible aux longs chemins CSS qui cassent à chaque refonte.
• Données de test mal préparées. Les courses entre le navigateur et le serveur sont une source majeure de tests instables.

Capybara dans une stratégie de test

Capybara vérifie qu'une fonctionnalité marche pour un utilisateur dans un navigateur. Il est lent comparé aux tests unitaires, réservez-le donc aux parcours clés : inscription, paiement, connexion. Il convient bien aux tests de régression de ces parcours et travaille avec le DOM rendu plutôt qu'avec vos détails internes. Si vous ne travaillez pas en Ruby, la même idée avec Playwright est dans notre tutoriel Playwright.

Il ne dit pas comment l'appli se comporte avec beaucoup d'utilisateurs en même temps. Pour cela, lancez un test de charge sur les mêmes parcours.

Questions fréquentes sur Capybara

Capybara est-il un framework de test ?

Non. C'est une bibliothèque pour piloter une appli web, utilisée dans RSpec, Minitest ou Cucumber, qui fournissent la structure des tests et les rapports.

Quels pilotes Capybara prend-il en charge ?

RackTest est le pilote par défaut et ne gère pas JavaScript. Selenium pilote de vrais navigateurs. Cuprite pilote Chrome via le DevTools Protocol, et d'autres pilotes comme WebKit existent sous forme de gems externes.

Combien de temps Capybara attend-il ?

2 secondes par défaut, réglable avec Capybara.default_max_wait_time. Les finders et matchers réessaient pendant ce délai et reviennent aussitôt en cas de succès.

Faut-il Selenium pour utiliser Capybara ?

Non. RackTest n'a pas besoin de navigateur et Cuprite utilise Chrome directement. Selenium est le pilote JavaScript par défaut et celui des tests système de Rails tant que vous ne le changez pas.

Capybara fonctionne-t-il avec Rails ?

Oui. Les tests système de Rails s'appuient sur Capybara, et le pilote du navigateur se choisit avec driven_by dans le cas de test système.