Lesson 1: Introduction and Overview of Capybara

Capybara is a Ruby library that provides a simple yet powerful Domain Specific Language (DSL) for interacting with web applications during integration testing. It assists you in simulating how a user interacts with your application, all in a straightforward and easy to read syntax.

In this first lesson, we're going to provide a practical guide for setting up the Capybara environment.

Step 1: Install Ruby

Capybara runs on Ruby. Therefore, you should ensure Ruby is installed in your environment. If Ruby is not yet installed, you can use the following command in a terminal:

sudo apt-get install ruby-full

To verify the installation, use:

ruby --version

Step 2: Install Bundler

Bundler is a dependency management tool for Ruby. We can install it via gem, the Ruby package manager:

gem install bundler

To check if the bundler is installed:

bundle --version

Step 3: Install Capybara

Navigate to the root of your project directoy. Creat a file named Gemfile if it does not exist yet and add the following lines to it:

source "https://rubygems.org"

gem "capybara"
gem "selenium-webdriver"
gem "rspec"

Then run the bundle install command. This command will install Capybara, Selenium webdriver (Capybara's default driver), and rspec (for writing our tests).

Step 4: Configuring Capybara with RSpec

Create a directory called spec in the root of your project and inside the spec directory, create a file called spec_helper.rb. Inside spec_helper.rb, add the following lines:

require 'capybara/rspec'

RSpec.configure do |config|
  config.expect_with :rspec do |expectations|
    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
  end
  config.mock_with :rspec do |mocks|
    mocks.verify_partial_doubles = true
  end
  config.shared_context_metadata_behavior = :apply_to_host_groups
end

For each file for the spec that uses Capybara, require the spec_helper:

require "spec_helper"

You're now set up and ready to use Capybara for your integration tests.

In your actual test files, you would now use Capybara to visit pages, fill in forms, click links, and interact with your web application just as a user would.

Below is an example of how you might structure a spec file (Ex: home_page_spec.rb) for testing a simple home page:

require "spec_helper"

feature "Home page" do
  before do
    visit "/"  # This visits the root path of your app
  end

  it "has a welcome message" do
    expect(page).to have_content("Welcome to Our Awesome App")
  end

  it "has a signup link" do
    expect(page).to have_link("Sign Up", href: "/signup")
  end
end

In this code, visit, have_content, have_link are all built-in Capybara methods for interacting with a web page.

Please note that this reference is simplified and intended to get you started on setting up your environment but Capybara can do much more robust and complex interactions and is highly configurable. For more in depth knowledge, kindly refer to the official Capybara documentation:

https://www.rubydoc.info/github/teamcapybara/capybara/master.

End of Lesson 1.

Lesson 2: Developing Environment Setup for Capybara

Prerequisites

Assuming that you have already set up Ruby and Rails on your machine, for Capybara setup, ensure that you have the following installed:

1. Ruby (version 2.6 or later)
2. Ruby on Rails (version 6.0 or later)

If not, kindly follow the proper installation guide for Ruby and Ruby on Rails.

Setup Procedure

Step 1: Create new Rails application (Skip if you've done in Lesson 1)

Step 2: Setting up RSpec

In your Rails application, add the following to your Gemfile:

group :development, :test do
  gem 'rspec-rails', '~> 4.0.0'
end

Then run bundle install to install the gem.

Once done, initialize the spec directory (where your tests will reside) with:

rails generate rspec:install

That will create the .rspec, spec/spec_helper.rb and spec/rails_helper.rb files.

Step 3: Setting up Capybara

To setup Capybara for your Rails application, add it to your Gemfile:

group :development, :test do
  gem 'capybara', '>= 2.15'
  gem 'selenium-webdriver' # Capybara's selenium driver will need this to interact with the browser
end

And yet again, install the gem by running bundle install.

Step 4: Create a directory in the spec for feature specs

mkdir spec/features

Step 5: Configure Capybara with RSpec

Inside the spec/rails_helper.rb, after the line require 'rspec/rails', add the following:

require 'capybara/rspec'

This will make Capybara DSL available in all example groups.

Step 6: Setup Database Cleaner

Add to Gemfile:

group :development, :test do
  gem 'database_cleaner'
end

Then run bundle install.

In the rails_helper.rb, add the following lines inside the config block:

config.before(:suite) do
  DatabaseCleaner.clean_with(:truncation)
end

config.before(:each) do
  DatabaseCleaner.strategy = :transaction
end

config.before(:each, :js => true) do
  DatabaseCleaner.strategy = :truncation
end

config.before(:each) do
  DatabaseCleaner.start
end

config.after(:each) do
  DatabaseCleaner.clean
end

Your Capybara environment development setup is now complete. You have successfully set up RSpec, Capybara, and DatabaseCleaner. You can now write and run your first Capybara test!

Note: This markdown content is focused only on how to setup Capybara in the Rails application. Please review the official Capybara documentation for deep understanding on how to use Capybara for feature and system testing.

Lesson 3: Architect a Basic Capybara Test Application

In this lesson, we'll be architecting a basic Capybara test application. After setting up the environment, we will proceed with the following:

1. Building a test script.
2. Executing the test.

Section 1: Building a Test Script

For this application, we will use the example of a simple test of a login page. This script will test the login functionality of a web application.

Let's name our test file login_spec.rb. Save this file in your Capybara project directory under the spec sub-directory.

The structure of the login_spec.rb test script would be as follows:

require 'capybara/rspec'

Capybara.app_host = "http://the-internet.herokuapp.com/login"
Capybara.default_driver = :selenium_chrome

describe 'Login', type: :feature do
  it 'Users can sign in' do
    visit '/'

    within('form') do
      fill_in 'Username', with: 'tomsmith'
      fill_in 'Password', with: 'SuperSecretPassword!'
    end

    click_button 'Login'

    expect(page).to have_content 'Secure Area'
    end

  it 'Users cannot sign in with incorrect credentials' do
    visit '/'

    within('form') do
        fill_in 'Username', with: 'wrong_username'
        fill_in 'Password', with: 'wrong_password'
    end

    click_button 'Login'

    expect(page).to have_content 'Login and/or password are wrong.'
  end
end

Section 2: Executing the Test

You can run the test from your terminal with the following command:

rspec spec/login_spec.rb

This script will launch a new automated browser window, navigate to the specified URL (http://the-internet.herokuapp.com/login), and perform the described functionalities (entering username and password, clicking on login, verifying the result).

Please ensure that your testing environment has Internet access and the target URL is available. Otherwise, the test cannot be executed successfully.

The rspec command should provide a well-structured output showing how many tests were executed, and how many of them failed or passed.

If the tests are passing, it indicates that the login functionality of the web page is working as expected. If they fail, then it suggests that there might be issues with the login functionality.

Note: Ensure rspec, capybara, and selenium-webdriver gems are installed in your environment to run the test.