3.0
Shared Docs
Community & Team
Testing
Matestack layouts, pages and components can be tested with various test setups. We're using Rspec and Capybara a lot when creating apps with Matestack or work on Matestack's Gems itself and want to show you some basic elements of this setup.
We will show you how to setup a headless chrome for testing, because a headless browser approach gives you performance benefits and is better suited to be integrated in a CI/CD pipeline.
Setup
In this guide we assume that you know the basics of Rspec and Capybara and have both gems installed. If not, please read the basics about these tools here:
Additionally you need a Chrome browser installed on your system.
We recommend to configure Capybara in a separate file and require it in your
rails_helper.rbspec/rails:helper.rb
spec/support/capybara.rb
1
# This file is copied to spec/ when you run 'rails generate rspec:install'
2
require "spec_helper"
3
ENV["RAILS_ENV"] ||= "test"
4
require File.expand_path("../config/environment", __dir__)
5
# Prevent database truncation if the environment is production
6
abort("The Rails environment is running in production mode!") if Rails.env.production?
7
require "rspec/rails"
8
9
Dir[File.join File.dirname(__FILE__), "support", "**", "*.rb"].each { |f| require f }
10
# Add additional requires below this line. Rails is not loaded until this point!
Copied!
1
require "capybara/rspec"
2
require "capybara/rails"
3
require "selenium/webdriver"
4
5
# port used for debugging (explained later)
6
Capybara.server_port = 33123
7
Capybara.server_host = "0.0.0.0"
8
9
Capybara.register_driver :headless_chrome do |app|
10
chrome_options = Selenium::WebDriver::Chrome::Options.new.tap do |o|
11
o.add_argument "--headless"
12
o.add_argument "--no-sandbox"
13
o.add_argument "--disable-dev-shm-usage"
14
o.add_argument "--disable-gpu"
15
o.add_argument "--enable-features=NetworkService,NetworkServiceInProcess"
16
end
17
Capybara::Selenium::Driver.new(app, browser: :chrome, options: chrome_options)
18
end
19
Capybara.default_driver = :headless_chrome
Copied!
Writing basic specs
Imagine having implemented a Matestack page like:
app/matestack/some:page.rb
app/controllers/some:controller.rb
config/routes.rb
1
class SomePage < Matestack::Ui::Page
2
3
def response
4
plain "hello world!"
5
end
6
7
end
Copied!
1
class SomeController < ApplicationController
2
3
include Matestack::Ui::Core::Helper
4
5
def some_page
6
render SomePage
7
end
8
9
end
Copied!
1
Rails.application.routes.draw do
2
3
get 'some_page', to: 'some#some_page'
4
5
end
Copied!
A spec might look like this:
spec/features/hello:world:spec.rb
1
require "rails_helper"
2
3
describe "Some Page", type: :feature do
4
5
it "should render hello world" do
6
visit some_page_path
7
expect(page).to have_content("hello world!")
8
end
9
10
end
Copied!
and then run this spec with
bundle exec rspec spec/features/hello_world_spec.rbThis should start a webserver and trigger the headless chrome to request the specified page from it. Just like Capybara is working.
Testing asynchronous features
Above, we just tested a static "hello world" rendering and didn't use any JavaScript based functionality. We need to activate the JavaScript driver in specs where Matestack's built-in (or your own) JavaScript is required.
Let's add some basic built-in reactivity of Matestack, which requires JavaScript to work:
1
class SomePage < Matestack::Ui::Page
2
3
def response
4
onclick emit: "show_hello" do
5
button "click me"
6
end
7
async show_on: "show_hello", id: "hello" do
8
plain "hello world!"
9
end
10
end
11
12
end
Copied!
The spec could look like this: Note that you now have to add the
js: true on line 3!spec/features/hello:world:spec.rb
1
require "rails_helper"
2
3
describe "Some Page", type: :feature, js: true do
4
5
it "should render hello world after clicking on a button" do
6
visit some_page_path
7
expect(page).not_to have_content("hello world!")
8
click "click me"
9
expect(page).to have_content("hello world!")
10
end
11
12
end
Copied!
Capybara by default will wait for 2000ms before failing on an expectation.
expect(page).to have_content("hello world!") therefore may take up to 2000ms to become truthy without breaking the spec. Following the documentation of Capybara, you can adjust the default wait time or set it individually on specific expectations. This built-in wait mechanism is especially useful when working with features requiring client-server communication, like page transitions, form or action submissions!Testing forms and actions
Imagine a
matestack_form used for creating new User ActiveRecord Model instances:1
class SomePage < Matestack::Ui::Page
2
3
def response
4
matestack_form form_config do
5
form_input key: :name, type: :text, label: "Name"
6
button "submit me", type: :submit
7
end
8
toggle show_on: "succeeded" do
9
plain "succeeded!"
10
end
11
toggle show_on: "failed" do
12
plain "failed!"
13
end
14
end
15
16
def form_config
17
{
18
for: User.new,
19
path: users_path,
20
method: :post,
21
success: { emit: "succeeded" },
22
failure: { emit: "failed" }
23
}
24
end
25
26
end
Copied!
The according spec might look like this:
spec/features/form:submission:spec.rb
1
require "rails_helper"
2
3
describe "Some Page", type: :feature, js: true do
4
5
it "should render hello world" do
6
visit some_page_path
7
fill_in "Name", with: "Foo"
8
click "submit me"
9
10
expect(page).to have_content("succeeded!")
11
end
12
13
end
Copied!
If you want to test if the User model was correctly saved in the Database, you could do something like this:
spec/features/form:submission:spec.rb
1
describe "Some Page", type: :feature, js: true do
2
3
it "should render hello world" do
4
visit some_page_path
5
fill_in "Name", with: "Foo"
6
7
expect {
8
click "submit me"
9
expect(page).to have_content("succeeded!") #required to work properly!
10
}.to change { User.count }.by(1)
11
12
# from here on, we know for sure that the form was submitted
13
expect(User.last.name).to eq "Foo"
14
end
15
16
end
Copied!
Beware of the timing trap!
Without adding
expect(page).to have_content("succeeded!") after click "submit me" the spec would fail. The User.count would be executed too early! You somehow need to use Capybara's built-in wait mechanisim in order to identify a successful asynchronous form submission. Otherwise the spec would just click the submit button and immediately expect a database state change. Unlike Capybara, plain Rspec expectations do not wait a certain amount of time before failing! Gems like https://github.com/laserlemon/rspec-wait are trying to address this issue. In our experience, you're better of using Capybara's built-in wait mechanism like shown in the example, though.Above described approaches and hints apply for actions as well!
Debugging specs
When running specs in a headless browser, you're loosing insights on what exactly happens when a spec is failing. You have a simple yet powerful option to overcome this issue:
As described within the Setup section, it's possible to tell Capybara, which port should be used by the webserver while executing the specs. (By default it's randomly chosen on every spec run). When adding a simple
sleep after a visit in your spec, you can request the same page, your spec would visit in you local browser and review what's going on there by manually executing the steps your spec would perform while reviewing the DOM and browser debugging tools:spec/features/form:submission:spec.rb
1
describe "Some Page", type: :feature, js: true do
2
3
it "should render hello world" do
4
visit some_page_path
5
6
p some_page_path # see the resolved URL string, copy to your browser
7
sleep # add the sleep after the visit
8
9
fill_in "Name", with: "Foo"
10
click "submit me"
11
12
expect(page).to have_content("succeeded!")
13
end
14
15
end
Copied!
Execute the spec and then visit the logged path in your local browser via
localhost:33123/xyz for example.This approach is especially useful when using factories in order to create temporary test data which is only accessible in your test ENV and that specific spec. In other words: you can review the test state way better compared to perform the spec steps in your local development ENV.
Last modified 3mo ago