Capybara: tests de aceptación en Ruby para apps web

¿Qué es Capybara?

Capybara es una biblioteca de Ruby para tests de aceptación de aplicaciones web. Ofrece un DSL para visitar páginas, rellenar formularios, pulsar enlaces y comprobar lo que se muestra, y funciona con un driver sencillo en el mismo proceso o con un navegador real. No es un ejecutor de tests: se usa dentro de RSpec, Minitest o Cucumber. Los tests de sistema de Rails se apoyan en él.

Cómo funciona Capybara

Tu test describe lo que hace un usuario y Capybara pasa cada paso a un driver. El driver por defecto, RackTest, es Ruby puro, no necesita servidor y no admite JavaScript, así que es rápido pero no ejecuta scripts. Para páginas que dependen de JavaScript cambias a un driver de navegador. Capybara.javascript_driver vale :selenium por defecto, y un test lo usa si lleva la etiqueta js: true en RSpec o @javascript en Cucumber. Cuprite es una gema aparte que maneja Chrome mediante el Chrome DevTools Protocol y no necesita Selenium ni ChromeDriver.

Ejemplo

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

No hay ningún sleep. Los buscadores y matchers como have_content reintentan hasta que pasan o se agota el tiempo de espera, y vuelven al instante si tienen éxito. El valor por defecto de Capybara.default_max_wait_time es 2 segundos; súbelo con Capybara.default_max_wait_time = 5 si una página es realmente lenta. Los tests de sistema de Rails usan por defecto Selenium con Chrome y puedes elegir otro driver con driven_by.

Errores comunes

• Esperas fijas. Ralentizan la suite y aun así fallan en una ejecución lenta. Usa un matcher que espere en lugar de sleep.
• Comprobaciones negativas que no esperan. Prefiere expect(page).to have_no_content(...) a !page.has_content?(...), que se rinde a la primera.
• Esperar JavaScript de RackTest. Si un clic no hace nada, comprueba que el test se ejecuta con un driver de JavaScript.
• Selectores frágiles. Prefiere etiquetas y texto visible a rutas CSS largas que se rompen en cada rediseño.
• Datos de prueba mal preparados. Las carreras entre el navegador y el servidor son una fuente principal de tests inestables.

Capybara en una estrategia de testing

Capybara comprueba que una funcionalidad sirve para un usuario en un navegador. Es lento frente a los tests unitarios, así que resérvalo para los recorridos clave: registro, pago, inicio de sesión. Encaja bien en las pruebas de regresión de esos flujos y trabaja con el DOM renderizado, no con tus detalles internos. Si no trabajas con Ruby, la misma idea con Playwright está en nuestro tutorial de Playwright.

Lo que no te dice es cómo se comporta la app con muchos usuarios a la vez. Para eso, lanza una prueba de carga sobre los mismos recorridos.

Preguntas frecuentes sobre Capybara

¿Capybara es un framework de testing?

No. Es una biblioteca para manejar una app web, que se usa dentro de RSpec, Minitest o Cucumber, los cuales aportan la estructura de los tests y los informes.

¿Qué drivers admite Capybara?

RackTest es el predeterminado y no admite JavaScript. Selenium maneja navegadores reales. Cuprite maneja Chrome mediante el DevTools Protocol, y otros drivers como WebKit existen como gemas externas.

¿Cuánto espera Capybara?

Por defecto 2 segundos, ajustable con Capybara.default_max_wait_time. Los buscadores y matchers reintentan dentro de ese tiempo y vuelven de inmediato si tienen éxito.

¿Necesito Selenium para usar Capybara?

No. RackTest no necesita navegador y Cuprite usa Chrome directamente. Selenium es el driver de JavaScript por defecto y el que usan los tests de sistema de Rails si no lo cambias.

¿Capybara funciona con Rails?

Sí. Los tests de sistema de Rails se apoyan en Capybara, y el driver del navegador se elige con driven_by en el caso de test de sistema.