brianjbayer/gist-rspec-rails-system-specs.md

## gist-rspec-rails-system-specs.md

      
    Raw
  

              gist-rspec-rails-system-specs.md
            
          
    Use RSpec Rails System Specs for Web Server Level Functional Tests


🕐 Updated March 2024


Why

Test all of your Rails app's functionality even at the highest feature
level right in RSpec with the rest of your unit and integration tests.
Use RSpec Rails system specs to test your app's functionality at the
web server (e.g. Puma) level.
Consider using RSpec Rails system specs and test doubles to reduce your
End-to-End testing in a test environment.

What This Is

This is an overview and recipe for adding RSpec Rails system specs to your app's RSpec
test suite.  Here you will get...

The background on system specs
Their gem dependencies and how to add them
An overview of configuring Capybara
An overview of writing system specs and how to run them


Background

RSpec Rails system specs
are the only level of RSpec Rails tests that launch the web server
(Puma by default).
system specs...

Rely on and require Capybara gem
Use database transactions (which are rolled back) so the
DatabaseCleaner gem
is NOT needed

What Are RSpec Rails System Specs

Rails (Minitest) introduced system tests
in Rails 5.1 to build in the ability to functionally test your Rails application at
the web browser level with Capybara.
system specs are RSpec Rails' wrapper for the Rails' (Minitest) system tests.

Configuring RSpec Rails System Specs

Defaults


By default, system tests are run with the Selenium driver, using the Chrome browser,
and a screen size of 1400x1400.


RSpec does not use your ApplicationSystemTestCase helper. Instead it uses the
default driven_by(:selenium) from Rails.

Configure Required Gems

At a minimum, your system specs require...

gem 'capybara'
gem 'selenium-webdriver'

By default, Rails (i.e. rails new myapp) should automatically include Minitest
system test dependencies in the generated Gemfile.
Adding RSpec Rails System Specs Gems Manually

However, IF you skipped adding Minitest when you generated your app
(e.g. rails new myapp -T) and added RSpec Rails manually to your project and Gemfile,
THEN you will need to add the system spec dependencies manually as well.
Ensure that you have in your app's Gemfile...
RSpec-Rails
group :development, :test do
  ...
  gem 'rspec-rails'
  ...
end
Capybara and Selenium Webdriver
group :development, :test do
  ...
  # Adds support for RSpec system specs
  gem 'capybara'
  gem 'selenium-webdriver'
  ...
end
Install Added Gems

IF you manually added gems to the Gemfile, THEN you will need to install
them with bundle install.
Configure Capybara

By default Rails Minitest uses and configures the ApplicationSystemTestCase helper
in test/application_system_test_case.rb...
require 'test_helper'

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  driven_by :selenium, using: :chrome, screen_size: [1400, 1400]
end
However, as mentioned, RSpec does not use your ApplicationSystemTestCase helper!
Configuring Capybara Manually for RSpec Rails

By default, RSpec Rails uses the Rails default driven_by(:selenium).
Your specific Rails app's Capybara configuration depends on your intended supported
browsers and whether they are local or remote. However, I have included a sample
Capybara configuration that I use to demonstrate its configuration.  Since this is
at the web server level, you must set the IP and Port of the host/webserver
for your app.
Sample Local and Remote Browser (Container) Capybara Implementation

I like to have my development (and other) environment(s) as close to the intended
production environment as possible to reduce the risk of surprises later.  Running
your Rails app in containers and containerized dev environments is a great way
to do this.  I also recommend
using Selenium's Docker Containers
to simplify browser dependencies.

👉 If you are using an ARM-based Mac (e.g. M2 chip), you will
need to use the forked
Docker Seleniarm Containers

This sample Capybara implementation supports both remote browsers
(i.e. Selenium/Seleniarm Containers) and local/native browsers.
You implement this by...

Creating a spec/support/capybara.rb configuration file
Requiring the capybara configuration file in spec/rails_helper.rb

Create spec/support/capybara.rb Capybara Configuration File

This implementation uses environment variables to supply the
running environment-specific values for...

PORT - the port for your Rails App
(e.g. PORT="3000")
BROWSER - the type of Selenium-supported browser
(e.g. BROWSER=chrome)
HEADLESS - if set (including set to empty), specifies
running in headless mode provided that the specified browser
supports it (e.g. HEADLESS=)
SELENIUM_REMOTE - the remote browser URL
(e.g. SELENIUM_REMOTE='http://localhost:4444/wd/hub' )
CAPYBARA_WAIT - the time in seconds for Capybara to wait
on page URLs or elements to load

Note that when running locally/natively, if BROWSER is not set,
this example will default to the :selenium browser which is Chrome.
In your Rails app's project directory, create file
spec/support/capybara.rb with the following Capybara configuration...
# frozen_string_literal: true

def create_capybara_browser(browser:, url:)
  return :selenium unless browser

  Capybara.register_driver :capybara_browser do |app|
    options = browser_options(browser)
    Capybara::Selenium::Driver.new(
      app,
      browser: url ? :remote : browser.to_sym,
      options: options,
      url:)
  end
  :capybara_browser
end

def browser_options(browser)
  browser = browser.to_s.gsub(/\W/, '').capitalize
  # e.g. Selenium::WebDriver::Chrome::Options.new
  options = Selenium::WebDriver.const_get(browser).const_get('Options').new
  options.add_argument('--headless') if headless_specified?
  options
end

def headless_specified?
  headless = ENV.include?('HEADLESS')
end

def configure_rspec_capybara(capybara_browser, app_host_port)
  # This is always running locally (even in container) so get local IP address
  app_host = IPSocket.getaddress(Socket.gethostname)
  RSpec.configure do |config|
    config.before(:each, type: :system) do
      driven_by capybara_browser

      Capybara.app_host = "http://#{app_host}:#{app_host_port}"
      Capybara.server_host = app_host
      Capybara.server_port = app_host_port
    end
  end
end

# -- Main Capybar Configuration --
url = ENV['SELENIUM_REMOTE']
browser = ENV['BROWSER']

capybara_browser = create_capybara_browser(browser:, url:)

configure_rspec_capybara(capybara_browser, ENV['PORT'])

# Increase the Capybara Wait Time
# NOTE: Docker Compose can convert environment variables values to string
Capybara.default_max_wait_time = ENV.fetch('CAPYBARA_WAIT', 10).to_i
Require Capybara Configuration File in spec/rails_helper.rb

You add the Capybara configuration you just created to the RSpec Rails framework
by requiring it in your app's spec/rails_helper.rb file by adding the following line...
require 'support/capybara'

Writing RSpec Rails System Specs

Once you have your Capybara configuration implemented as you like, you can start writing and running your system specs.
Specifying RSpec Rails System Specs

By convention in RSpec Rails, you put your system specs under the spec/system directory.
You can also explicitly tag your system specs with :type => :system...
RSpec.describe 'Hello Rails', type: :system do
  ...
end
Generating RSpec Rails System Specs

You can use rails generate to generate your system specs...
bundle exec bin/rails generate rspec:system [test-name]

For example bundle exec bin/rails generate rspec:system hello_rails.
Sample RSpec Rails System Spec Test

Here is a very simple example of an RSpec Rails system spec expecting the phrase "Hello Rails"
to be on the home page of the Rails app...
# Specifies user sees Hello Rails on home page

require 'rails_helper'

RSpec.describe 'Hello Rails', type: :system do
  context 'when user visits the Home Page...' do
    before(:each) do
      visit '/'
    end
    it { expect(page).to have_text('Hello, Rails!') }
  end
end

Running the RSpec Rails System Specs

Be sure to specify any environment variables.
Here's an example of running all the RSpec tests with the
Sample Remote Browser (Container) Capybara Implementation...
SELENIUM_REMOTE='http://localhost:4444/wd/hub' \
BROWSER=chrome \
APP_HOST_PORT="3000" \
bundle exec rspec

Run With Other RSpec Tests (Default)

Run your Rails RSpec tests the way that you normally do to include your system specs,
for example...
bundle exec rspec

bundle exec rake spec

Run Just RSpec Rails System Specs

You can also run just your RSpec Rails system specs using...


Rails rake task rake spec:system
bundle exec rake spec:system


RSpec's abilities to specify tests to run your system specs...


To run only specs in the spec/system folder...
bundle exec rspec spec/system


To run only type: :system tagged system specs...
bundle exec rspec --tag type:system


Run All RSpec Specs Except for Rails System Specs

You can run all of your tests except for your RSpec Rails system specs using
RSpec's exclude functions...


To exclude specs in the spec/system folder...
bundle exec rspec --exclude-pattern "spec/system/*_spec.rb"


To exclude type: :system tagged system specs...
bundle exec rspec --tag ~type:system


I Learned This From... (Sources)

I used some of the Capybara configuration from my personal projects which I've refined over the years.
When I learned and implemented this, I was specifically doing it in containers and in Kubernetes.
These sources reflect that.

Hint.io Rails System Tests In Docker
 Plymouth Software Rails on Docker: System Specs in Containers with RSpec, Capybara, Chrome, and Selenium