Middleman Rspec Bootstrap4

version 1.1 (stable & working beautifully)

A convenient starter app for Middleman 4 that comes preloaded with RSpec, Bootstrap4 Beta and a host of other goodies

A basic "starting point" middleman app that is tested through RSpec with some additional handy features to help you get up and running quickly.

I use this app as a starting point for new projects since it has a lot of convenient things already in place... CoffeeScript namespacing, example feature specs, RSpec and Capybara configurations, etc.

Note: Inspiration and starting points for getting my own initial Middleman apps up and running is thanks to simonrice's middleman-rspec. Tons of appreciation to simonrice.

TLDR;

A detailed walkthrough is down below this TLDR... but if you're out of time and just need to get up and running quickly... go through this process. By the way, this assumes you have ruby, homebrew and Google Chrome setup and in place on your machine. If you don't have those, get them in place first.

Clone the repo (if copying and pasting the commands below, don't copy the $ sign into your terminal):

Install Middleman
$ gem install middleman

From within your root project folder, eg: /Users/jonathanroehm/projects/
$ git clone https://github.com/jonathanroehm/middleman-rspec-bootstrap4.git

From within your app folder on terminal, e.g: /Users/jonathanroehm/projects/middleman-rspec-bootstrap4/ bundle the gems
$ bundle exec bundle

Install ChromeDriver
$ homebrew install chromedriver

Run the pre-loaded specs:
$ bundle exec rspec

Run the app (browsable on your machine at http://localhost:4567):

$ middleman server

Build your files:

$ middleman build

Everything else

The general toolset:

1. HAML
2. CoffeeScript
3. RSpec & Capybara
4. I18n
5. Bootstrap 4 (Currently v4.0.0 beta)
6. FontAwesome

If you stumbled here because you were looking for help in getting Middleman setup with RSpec, this should be a useful app for you. Follow the docs and you should be up and running in no time. For the uninitiated, the '$' symbol is just a visual cue that you should type in the following code in terminal. Don't actually copy in the '$' sign.

Getting Started

This'll walk you through the basic setup 'for your info.'

Install middleman

If you do not have middleman installed locally, run the command below.

$ gem install middleman

Cloning repo

After you clone this repo locally, be sure to run bundle install. Basic setup once in your normal projects root folder, clone the app:

$ git clone https://github.com/jonathanroehm/middleman-rspec-bootstrap4.git
$ bundle exec bundle

Working in middleman

All files should go into the source directories. Example:

1. HAML files: my_app/source/index.html.haml
2. JavaScript: my_app/source/javascripts/application.js.coffee
3. Images: my_app/source/images/image.jpg

Starting middleman

To see live updates in your browser, at the root of the project in terminal run the command below and follow the displayed instructions

$ middleman server

To build the html files, run:

They'll output to a build folder, e.g.: my_app/build/index.html

$ middleman build

All of the assets will be created in a build folder.

Setting up a convenient config.rb in my_app/config.rb file

See individual walkthrough and then the full config.rb file below:

Getting I18n and relative files and links setup:

###
# Page options, layouts, aliases and proxies
###

activate :i18n
activate :relative_assets
set :relative_links, true
set :relative_assets, true

Make life easier with livereload and sprockets

# General configuration
configure :development do
  activate :livereload
  activate :sprockets do |c|
    c.expose_middleman_helpers = true
  end

  if defined? RailsAssets
    RailsAssets.load_paths.each do |path|
      sprockets.append_path path
    end
  end
end

Build only a single minified application.js and application.css instead of every source file (cut down on those http requests and speed up your site):

# Build-specific configuration
configure :build do
  activate :sprockets do |c|
    c.expose_middleman_helpers = true
  end

  # Minify CSS on build
  activate :minify_css
  # Don't pump out source CSS files
  ignore %r{stylesheets/(?!application\.css).*$}

  # Minify Javascript on build
  activate :minify_javascript
  # Don't pump out source JS files
  ignore %r{javascripts/(?!application\.js).*$}
end

All together, config.rb:

# Activate and configure extensions
# https://middlemanapp.com/advanced/configuration/#configuring-extensions
ignore 'README.md'

# Layouts
# https://middlemanapp.com/basics/layouts/

###
# Page options, layouts, aliases and proxies
###

activate :i18n
activate :relative_assets
set :relative_links, true
set :relative_assets, true

# Per-page layout changes:
#
# With no layout
page '/*.xml', layout: false
page '/*.json', layout: false
page '/*.txt', layout: false

# General configuration
configure :development do
  activate :livereload
  activate :sprockets do |c|
    c.expose_middleman_helpers = true
  end

  if defined? RailsAssets
    RailsAssets.load_paths.each do |path|
      sprockets.append_path path
    end
  end
end

# Build-specific configuration
configure :build do
  activate :sprockets do |c|
    c.expose_middleman_helpers = true
  end

  # Minify CSS on build
  activate :minify_css
  # Don't pump out source CSS files
  ignore %r{stylesheets/(?!application\.css).*$}

  # Minify Javascript on build
  activate :minify_javascript
  # Don't pump out source JS files
  ignore %r{javascripts/(?!application\.js).*$}
end

Gems

Getting rspec and everything else in place:

The useful Middleman gems:

# Middleman Gems
gem 'middleman', '>= 4.0.0'
gem 'middleman-livereload', '~> 3.4.3'
gem 'middleman-compass', '>= 4.0.0'
gem 'middleman-sprockets'

Secondary tools: Bootstrap, Font Awesome, JQuery, HAML

gem 'haml'
gem 'bootstrap', '~> 4.0.0.beta'

source 'https://rails-assets.org' do
  gem 'rails-assets-jquery'
end

Getting the testing gems in place:

group :test do
  gem 'selenium-webdriver'
  gem 'chromedriver-helper'
  gem 'rspec'
  gem 'capybara'
end

All together, my_app/Gemfile

# If you do not have OpenSSL installed, change
# the following line to use 'http://'
source 'https://rubygems.org'

# Middleman Gems
gem 'middleman', '>= 4.0.0'
gem 'middleman-livereload', '~> 3.4.3'
gem 'middleman-compass', '>= 4.0.0'
gem 'middleman-sprockets'

gem 'haml'
gem 'bootstrap', '~> 4.0.0.beta'

source 'https://rails-assets.org' do
  gem 'rails-assets-jquery'
end

group :test do
  gem 'selenium-webdriver'
  gem 'chromedriver-helper'
  gem 'rspec'
  gem 'capybara'
end

# For faster file watcher updates on Windows:
gem 'wdm', '~> 0.1.0', platforms: [:mswin, :mingw]

# Windows does not come with time zone data
gem 'tzinfo-data', platforms: [:mswin, :mingw, :jruby]

Configuring RSpec

1. Create a 'spec' folder in your app's root folder: my_app/spec/
2. Add spec_helper.rb; so within my_app/spec/spec_helper.rb

Within my_app/spec/spec_helper.rb

Require these:

require 'rspec'
require 'middleman'
require 'capybara/rspec'
require 'middleman-core'
require 'middleman-core/rack'
require 'middleman-core/load_paths'
require 'middleman-livereload'
require 'middleman-sprockets'
require 'middleman-compass'

Add the ability to locate supporting spec files like shared_examples:

# Utilize spec support files like shared_examples
Dir["./spec/support/**/**/*.rb"].sort.each { |f| require f}

Setup your feature spec's browser:

# Capybara & Selenium
prefered_browser = :chrome

Capybara.default_driver = :selenium
Capybara.register_driver :selenium do |app|
  # Use Chrome (Firefox has a host of issues)
  Capybara::Selenium::Driver.new(app, browser: prefered_browser)
end

Add iPhone driver for iPhone feature tests

# Use an iPhone user agent
Capybara.register_driver :iphone do |app|
  Capybara::RackTest::Driver.new(app, browser: prefered_browser, headers: { 'HTTP_USER_AGENT' => 'Mozilla/5.0 (iPhone; CPU iPhone OS 10_0 like Mac OS X) AppleWebKit/602.1.38 (KHTML, like Gecko) Version/10.0 Mobile/14A5297c Safari/602.1' })
end

Add 'by' and 'and_by' to your specs (to help speed up tare down and rebuilds associated with each 'it' statement):

# Allow 'by' 'and_by' in specs
def by(message)
  if block_given?
    yield
  else
    pending message
  end
end

alias and_by by

And everything else, all together:

require 'rspec'
require 'middleman'
require 'capybara/rspec'
require 'middleman-core'
require 'middleman-core/rack'
require 'middleman-core/load_paths'
require 'middleman-livereload'
require 'middleman-sprockets'
require 'middleman-compass'

# Utilize spec support files like shared_examples
Dir["./spec/support/**/**/*.rb"].sort.each { |f| require f}

# Capybara & Selenium
prefered_browser = :chrome

Capybara.default_driver = :selenium
Capybara.register_driver :selenium do |app|
  # Use Chrome (Firefox has a host of issues)
  Capybara::Selenium::Driver.new(app, browser: prefered_browser)
end

# Use an iPhone user agent
Capybara.register_driver :iphone do |app|
  Capybara::RackTest::Driver.new(app, browser: prefered_browser, headers: { 'HTTP_USER_AGENT' => 'Mozilla/5.0 (iPhone; CPU iPhone OS 10_0 like Mac OS X) AppleWebKit/602.1.38 (KHTML, like Gecko) Version/10.0 Mobile/14A5297c Safari/602.1' })
end

RSpec.configure do |config|
 config.include Capybara::DSL
end

# Configure middleman
Middleman.setup_load_paths
middleman_app = ::Middleman::Application.new

Capybara.app = ::Middleman::Rack.new(middleman_app).to_app do
  set :root, File.expand_path(File.join(File.dirname(__FILE__), '..'))
  set :environment, :development
  set :show_exceptions, false
end

# Allow 'by' 'and_by' in specs
def by(message)
  if block_given?
    yield
  else
    pending message
  end
end

alias and_by by

Running RSpec

This app uses Google Chrome for feature specs. You'll need to have the Chrome browser installed and in its usual path for everything to run easily.

To run RSpec:

bundle exec rspec

RSpec files

To add a new spec, go to my_app/spec/features/ and add a new feature spec and add _spec.rb to the filename, e.g.:

my_app/spec/features/index_spec.rb

To get a barebones feature spec up and running, in my_app/spec/features/index_spec.rb

require 'spec_helper'

describe 'the index page', type: :feature, js: true do
  before { visit '/index.html' }
  it 'is the index page' do
    by 'being the index page' do
      expect(current_path).to eq '/index.html'
    end  
    and_by 'having the index page heading' do
      expect(page).to have_text I18n.t('index.headings.page')
    end
  end
end

Then run this spec specifically:

$ bundle exec rspec spec/features/index_spec.rb

You can also run specific lines in rspec (e.g.: if you run a test and get a specific error on a specific line, you don't have to re-run the full test over again)... so to run line 32, for example:

$ bundle exec rspec spec/features/index_spec.rb:32

And, of course, if you want to run your entire test suite:

$ bundle exec rspec

This is what a simple rspec output looks like:

== Locales: en (Default en)
== LiveReload accepting connections from ws://10.0.0.182:35729
.

Finished in 7.68 seconds (files took 5.03 seconds to load)
1 example, 0 failures