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.
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 The general toolset:
- HAML
- CoffeeScript
- RSpec & Capybara
- I18n
- Bootstrap 4 (Currently v4.0.0 beta)
- 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.
This'll walk you through the basic setup 'for your info.'
If you do not have middleman installed locally, run the command below.
$ gem install middleman 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 All files should go into the source directories. Example:
- HAML files: my_app/source/index.html.haml
- JavaScript: my_app/source/javascripts/application.js.coffee
- Images: my_app/source/images/image.jpg
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 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.
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, trueMake 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 endBuild 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).*$} endAll 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).*$} endGetting 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' endGetting the testing gems in place:
group :test do gem 'selenium-webdriver' gem 'chromedriver-helper' gem 'rspec' gem 'capybara' endAll 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]- Create a 'spec' folder in your app's root folder: my_app/spec/
- 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) endAdd 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' }) endAdd '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 byAnd 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 byThis 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 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 endThen 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